FindA.Sale

FindA.Sale MCP 服务

用于查找 FindA.Sale 上的促销活动和商品的公开、只读 Model Context Protocol 服务。 基于官方 TypeScript MCP SDK v2（@modelcontextprotocol/server 2.3.x，MCP 规范 2026-07-28）构建。

生产环境：https://mcp.finda.sale（Railway 服务 findasale，项目 keen-wisdom，根目录 packages/mcp-server，Dockerfile.production，在触及 packages/mcp-server/** 的提交推送到 main 时自动部署）。

端点

路径	用途
POST /mcp	Streamable HTTP 传输，无状态。为 2026-07-28 客户端和 2025 年前后的客户端提供服务（无状态回退）。GET/DELETE 返回 405。
GET /sse + POST /messages?sessionId=…	旧版 HTTP+SSE 传输（规范中已弃用，为现有客户端保留），通过 @modelcontextprotocol/server-legacy/sse 提供。
POST /messages（无 sessionId）	从 v1 保留的无会话 JSON-RPC 适配层：initialize、ping、tools/list、tools/call。
GET /mcp/server-card	MCP 服务卡（application/mcp-server-card+json）。别名：/.well-known/mcp/server-card.json。
GET /.well-known/ai-catalog.json	链接到服务卡的 AI 目录。
GET /.well-known/mcp.json	非正式清单（也在 finda.sale/.well-known/mcp.json 镜像）。
GET /health	Railway 健康检查。

工具

全部十个工具均为只读（readOnlyHint: true、destructiveHint: false、idempotentHint: true）。 架构与各工具一同存放于 src/tools/*.ts（zod v4）；处理程序位于 src/handlers.ts。

search_sales、get_sale、search_items、get_item、list_cities、list_sale_types、 list_categories、get_trending_sales、get_sales_starting_soon、find_item_for_sale。

隐私与安全规则

• 始终以匿名方式调用后端（绝不会发送或转发认证标头），因此适用公开查看者规则：草稿/已取消/已删除的促销活动返回 404，抢先体验商品和 Legendary 商品继续保密，街道地址不会公开。
• 每个响应都会根据 src/lib/publicShape.ts 中的允许列表重新构建。绝不返回街道地址、入口密码、路线说明、组织者电话/地址/用户 ID、支付处理商 ID 和抓取元数据。坐标会四舍五入到小数点后 2 位（约 1 公里精度）。
• 后端错误会转换为简短的通用消息。

速率限制与缓存

• 每个 IP：每分钟最多 120 个 MCP HTTP 请求（RATE_LIMIT_MAX_REQUESTS），另有 src/lib/rateLimiter.ts 中的每工具限制（每分钟 10 到 40 次）。
• 旧版 SSE：每个 IP 最多 10 个开放会话，总计最多 300 个；会话在 1 小时后关闭。
• 后端 GET 响应会缓存在内存中（搜索缓存 60 秒，城市/类别缓存 10 分钟，按城市筛选商品搜索所用的促销活动摘要缓存 30 分钟）。

配置

参见 .env.example：BACKEND_URL、PORT（3003）、MCP_PUBLIC_ORIGIN、RATE_LIMIT_MAX_REQUESTS、NODE_ENV。

本地运行

npm install
npm run build
BACKEND_URL=https://api.finda.sale PORT=3003 npm start

使用 MCP Inspector（npx @modelcontextprotocol/inspector）连接 http://localhost:3003/mcp 进行测试。

注册表

官方 MCP 注册表名称：sale.finda/findasale（经 DNS 验证的 finda.sale 命名空间）。 提交步骤：claude_docs/operations/mcp-registry-submission-2026-10-23.md。