supost-mcp

supost-mcp

面向 SUpost（斯坦福的 marketplace）的远程 MCP 服务；通过 BRAND=capmus，也可用于 Capmus （capmus.com），它基于同一 supost-web 代码库提供相同的公共 API。一个代码仓库，两个 Vercel 项目：

品牌	Vercel 项目	端点	环境变量
SUpost	supost-mcp	https://mcp.supost.com/mcp	（默认）
Capmus	capmus-mcp	https://mcp.capmus.com/mcp	BRAND=capmus

BRAND 用于选择服务名称、工具标题和描述，以及默认基础 URL；预览环境中仍可通过 SUPOST_BASE_URL 覆盖基础 URL。

让 AI Agent 搜索当前发布的信息、获取信息详情、查看经验证的市场统计数据、给发布者发消息，以及创建草稿信息。

这是文档 190 工作流 E3（参见 supost-web/docs/dev/190-ai-agent-discovery-implementation-plan.md）。 它是 SUpost 公共接口的纯客户端，包括只读信息 API（E2）、公开信息页面和 /stats.md。它没有特权数据库访问权限，也不持有任何机密信息；唯一的配置是公共基础 URL。

工具

工具	底层接口	返回内容
search_listings	GET /api/public/listings	按最新优先顺序返回当前发布的信息（id、标题、价格、类别、created_at、规范 URL），并支持不透明游标分页。参数：q、cat、university、max_price、limit（≤50）、cursor。
get_listing	GET /post/index/<id> → 规范信息页面	返回一条信息及其完整描述，解析自页面的 schema.org Product JSON-LD。
get_market_stats	GET /stats.md	公共统计页面的 Markdown 版本（受众、信息数量、回复率／时间）。
list_categories	GET /api/public/categories	当前有效的类别／子类别体系——即 create_post 可使用的有效值。
create_post	POST /api/public/posts	创建一条草稿信息；返回 continue_url，发布者可在此添加照片、检查并发布（若不在免费套餐内，须先付费）。绝不会直接发布。
send_message	POST /api/public/messages	向信息的发布者发送消息。不会立即送达：确认链接会发送到 reply_to_email，只有人工点击后消息才会发出——Agent 必须将其报告为待确认，绝不能说已发送。
check_message_status	PostgREST RPC get_guest_verification_status（publishable key）	查询 send_message 提交对应的确认邮件是否已送达：queued / sent / failed（+ 原因）/ unknown。无法确认链接是否已被点击。

绝不会返回任何个人信息。send_message 是联系发布者的受支持方式；信息的 url 也包含站内消息表单。API 条款： https://supost.com/api/public/openapi.json。

地址退回

只有在用户点击确认链接后，消息才会送达；因此，如果链接无法联系到某个地址，消息就永远不会送达（supost-web docs/dev/20260917-2040-guest-reply-bounce-feedback-handoff.md）。 因此，对于无法投递的地址，send_message 绝不会只返回“待处理”：

• 如果某个地址的确认邮件在过去 30 天内发生过硬退信，API 会在存储任何内容之前拒绝请求，并返回 422 email_undeliverable。工具会返回一个错误结果，内容为 {status: "email_undeliverable", reason, email, message}，并告知 Agent 应询问其他地址，而不是重试。
• 否则，API 会返回 202 和一个 status_key，工具会轮询确认邮件的投递状态，最长约 8 秒（检查 4 次，间隔 2 秒——被抑制的地址会在 1 秒内失败，新发生的硬退信会在 1–16 秒内失败）。如果判定结果为 failed，则会像处理 422 一样报告；sent / queued 会作为 confirmation_email 返回在结果中，并附上供稍后调用 check_message_status 使用的 status_key。

轮询调用的是与网页表单相同的匿名可调用 PostgREST RPC：get_guest_verification_status(status_key)，并使用市场的publishable密钥（每个浏览器都会获得该值）。它只返回 queued | sent | failed 和失败分类（mailbox_unknown | no_mx | suppressed | other）——绝不会返回兑换令牌、消息或地址。环境变量：SUPOST_STATUS_URL / SUPOST_STATUS_KEY 可覆盖默认值（生产项目）；SUPOST_STATUS_KEY="" 可禁用轮询（工具会报告 unknown）；SUPOST_STATUS_POLL_ATTEMPTS / SUPOST_STATUS_POLL_INTERVAL_MS 可调整单次调用中的等待时间。

托管

通过 Vercel 部署为无状态的流式 HTTP MCP 端点（mcp-handler + @modelcontextprotocol/sdk）：

https://mcp.supost.com/mcp        (rewritten to /api/mcp)
https://mcp.supost.com/health     (rewritten to /api/health)

没有会话、没有 Redis、没有身份验证——每个请求都会独立处理，所有上游数据均为公开数据，并由 CDN 缓存。

当前运行的提交

在 Vercel 上，initialize 响应中的 serverInfo.version 为 <package version>+<short git sha>（例如 0.3.0+835efb3，来自 VERCEL_GIT_COMMIT_SHA；本地则为纯 0.3.0——参见 src/version.ts），因此任何 MCP 客户端或 GET /health 都能显示已部署的提交。如果发现内容似乎过期，可将其与 git rev-parse --short origin/master 进行比较。

健康检查和运行时间监控

GET /health 会返回 {"ok": true, "brand": "supost", "version": "…"} 且不会调用上游（api/health.ts）：它表示函数正在提供服务，并不表示 supost.com 正常运行。为每个品牌配置一个 UptimeRobot HTTP 监控器（手动操作，两个都需要）：

• https://mcp.supost.com/health
• https://mcp.capmus.com/health

对非 200 状态码发出警报（可选关键词 "ok":true），能够捕获部署故障或域名失效；响应正文中的 version 会显示响应所对应的提交。

部署

vercel deploy          # preview
vercel deploy --prod   # production

可选环境变量：SUPOST_BASE_URL（默认值为 https://supost.com；在预览部署中设为 https://preview.supost.com，以指向开发环境）。

生产部署通过 GitHub 集成从 master 分支发布。除非本地检出版本与 origin/master 一致，否则请避免运行 vercel deploy --prod：过期的 CLI 部署会取代 Git 构建并接管生产别名（此问题于 2026-09-17 发生，已通过 vercel promote 修复）。

使用情况分析

每次工具调用都会触发一个 PostHog mcp_tool_called 事件（参数经过清理，不含个人身份信息 — 参见 src/analytics.ts）；如果设置了 TOOL_LOG_URL / TOOL_LOG_KEY，还会在 marketplace 的私有 ops.mcp_tool_call 表中写入一行包含完整参数的记录（src/toollog.ts）。

失败的调用会带有 error_code：公共 API 的错误代码 （rate_limited、not_found、email_undeliverable、invalid_request 等）， 或其他情况对应的 unknown（网络故障、响应结构异常）；成功时为 null。错误消息绝不会发送，因为其中可能引用用户内容 — 按 error_code 分类，即可区分速率限制激增和上游服务中断。

PostHog 的 distinct_id 是调用方 IP + User-Agent 的加盐 SHA-256 哈希 （src/client.ts），因此 uniq(distinct_id) 可以统计不同的 Agent，而无需存储 IP。事件还包含 client_ua （MCP 客户端的 User-Agent，其中会注明所用的运行环境）和 client_country （Vercel 的地理位置请求头）。在 Vercel 项目的环境变量中设置 CLIENT_ID_SALT，使哈希无法被猜出；仓库内的默认值可确保本地开发正常运行。 未携带 IP 或 User-Agent 的调用会回退到按品牌区分的 ID mcp.<brand>.com。

连接客户端

claude mcp add --transport http supost https://mcp.supost.com/mcp

或者，在任何支持远程服务的 MCP 客户端中，将上方 URL 添加为一个可流式传输的 HTTP 服务。

速率限制

公共 API 将请求限制为每个 IP 每分钟约 60 次，并提供 5 分钟的 CDN 缓存。src/http.ts 中的客户端会遵循这一限制：收到 429 响应时，会遵从 Retry-After（最长 5 秒），只重试一次；否则会返回结构化的 rate_limited 错误，提示 Agent 暂缓请求 — 不会循环重试。所有请求都会携带 supost-mcp/… User-Agent。

每次 marketplace 调用（状态 RPC 除外）还会携带可信 Agent 请求头：x-supost-api-key（部署环境中的 SUPOST_API_KEY，绝不提交到 git），以及在调用方 Agent 的 IP 已知时携带 x-supost-agent-client-ip，其值取自 MCP 自身收到的 x-forwarded-for 的第一跳。（supost-web docs/dev/469-mcp-agent-api-hardening-handoff.md）只有在密钥验证通过时，API 才会信任该 IP，因此每 IP 限制可以按 Agent 生效，而不是对所有 Agent 共享的单个 Vercel 出口 IP 生效。直接使用 X-Forwarded-For 无效：supost.com 运行在 Vercel 上，该平台会在边缘节点覆盖此请求头。

开发

npm install
npm run check    # typecheck + tests
SUPOST_BASE_URL=https://preview.supost.com npx tsx scripts/smoke.ts   # live end-to-end

测试（vitest）涵盖每个工具的请求/响应映射、错误映射、JSON-LD 提取，以及速率限制约定（遵从 Retry-After、限制等待时长、仅重试一次、结构化失败）。

后续事项（手动步骤）

• 发布到 MCP 注册表 — server.json 已准备就绪。 先将仓库设为公开（gh repo edit Capmus-Team/supost-mcp --visibility public），然后： sh brew install mcp-publisher mcp-publisher login github # 设备授权流程，需要浏览器 mcp-publisher publish # 在仓库根目录运行 对于 Capmus 条目，以相同方式发布 server.capmus.json （在临时检出目录中执行 cp server.capmus.json server.json， 或在支持时执行 mcp-publisher publish --file server.capmus.json）。
• supost-web 中的 /help/mcp 文档页 — PR #1242（指南 注册表条目 + llms.txt 中的 MCP 行）；合并到 dev → master 后上线。
• PR/引用公告 — 草稿和故事要点见 docs/announcement-draft.md；注册表条目和 /help/mcp 上线后发布（文档 190 工作流 F）。
• E2 已于 2026-07-09 在生产环境上线（supost.com）；冒烟脚本已在生产环境验证，服务部署地址为 https://mcp.supost.com/mcp。