wishlist-mcp

用于 wishlist.fit 的托管 MCP 服务器。它让 Claude、ChatGPT 或 Codex 代表你读取和更新你的 wishlist。

https://mcp.wishlist.fit/mcp

从 app.wishlist.fit/connect 连接它，那里有按客户端分类的设置步骤。你需要先拥有 wishlist 账户；这台服务器一切不创建账户。

它是什么

一个纯 OAuth 2.1 资源服务器，位于 wishlist REST API 前面。它不持有数据库，也没有业务规则。可见性、速率限制和邀请处理都在 wishlist API 中；此服务器用用户自己的访问令牌调用该 API，从而继承这些规则。

这种拆分是刻意为之。另一种方案是由另一服务带着自己的规则副本，而这正是两个服务悄然对“谁可以看到什么”开始产生分歧的方式。

Claude / ChatGPT / Codex
        │  MCP over HTTP, bearer token
        ▼
   this server ──── verifies the token (issuer + audience)
        │
        │  the same token, forwarded
        ▼
   api.wishlist.fit ──── applies visibility, rate limits, invite rules
        │
        ▼
     Postgres

WorkOS AuthKit 是授权服务器。本服务器不签发任何内容，也不显示权利确认界面；只验证 AuthKit 签名过的内容。

工具

有十四个工具，一个对应你在 Web 应用中能手动完成的每一个事项。对等是原则：没有仅限 agent 的权限，也没有应用程序本身做不了的操作。

wishlist_get_gift_guide 会同时返回一个人的 profile 和 wishlist。它是所有人连接此服务器的原因；只要有它，给券的流程就只要一次往返。

两个破坏性工具带 destructiveHint: true，因此会先确认不可逆操作的客户端会先询问。发送邀请会邮件给一个真实的人，并且无法撤回。接受邀请是双方的：邀请者会访问到你的 circle-only 字段，你也同样能得到他方的字段。

一次连接，everything

这里没有 scopes。WorkOS 无法表达自定义 scopes，因此一个连接就拥有全部工具surface。写入保护是行为性而非结构性的：上面的标注、工具描述，以及 API 的读写限制都是。

本地运行

uv sync
cp .env.example .env      # point it at a local API and the Local WorkOS environment
uv run python -m wishlist_mcp.main

uv run pytest
uv run ruff format --check . && uv run ruff check .

测试用 respx 来桩 wishlist API。它们检验的重点正是本服务器的自身职责：验证令牌、整理请求、把 API 错误转化为模型能行动的句子。规则本身属于 API，并在 API 项目里测试。

配置

每个变量都以 WISHLIST_MCP_ 为前缀。参见 .env.example。

RESOURCE_URI 必须与 WorkOS 中配置的资源 indicator 完全一致，包括 /mcp 路径。不匹配是客户端拒绝连接的最常见原因。

在改动它之前值得知道的事

这些每一条都是曾经到达生产的 bug。

• get_http_headers() 会剥掉 authorization。 要显式要求它，否则每个 tool call 都会报 "no access token" 而 initialize 和 tools/list 还是会成功，因为这两者是在工具函数体执行之前返回的。一个 green handshake 不代表工具可用。

• MCP 应用被挂在网站根路径，并 holds own 路径。 如果把其挂在 /mcp，Starlette 会把 /mcp 重定向到 /mcp/，而所有客户端拿到的地址都没有结尾斜杠。

• X-Forwarded-Proto 被认为是可信的。 Cloud Run 在这层终结 TLS；没有它则每个生成的 URL 都会宣称是 http://。结合上面重定向问题，这曾导致客户端真的明文发送过 bearer token。

• FastMCP 的生命周期被链了 project app 的 lifespan。 把一个 ASGI app 挂载进来并不可启动它的 lifecycle；没有启动时，每个工具调用都会报 "Task group is not initialized"，但 unit test 仍然通过。

• TestClient 默认会重定向。 当你想要验证某个 path 是直接响应时，请传 follow_redirects=False。

部署

Cloud Run，asia-southeast1，与 wishlist 其他服务在同一个 project 中。main 在 push 时自动部署。基础设施相关代码在 wishlist-infrastructure。

许可证

MIT。查看 LICENSE。