用途
Pantrist MCP Server 是一个 Model Context Protocol（MCP）服务器，用于封装 Pantrist REST API。它的目的是让 LLM 客户端（例如 Claude Desktop、Claude 网页/移动端连接器、Cursor 等）能够通过自然语言管理 Pantrist 中的购物清单、食品储藏室、食谱和周计划。
主要能力
该服务器是一个轻量封装，不包含业务逻辑。每个工具都映射到一个现有的 REST 端点，并转发调用者的 Bearer 令牌。HTTP 客户端是根据公开的 OpenAPI 规范生成的（src/generated/pantrist-api.ts），因此请求和响应类型会自动跟踪 API 的变化；只有精心设计的工具层（src/tools.ts）是手工编写的。
它支持以下功能领域：购物清单、食品储藏室、食谱和周计划。具体工具的参数、REST 映射和项目结构可参考 docs/TOOLS.md。
使用方式
连接 Claude 到托管服务器
如果只需在 Claude 中使用 Pantrist（而非自托管），公共端点是 https://mcp.pantrist.app/mcp 。无论使用哪种 Claude 界面，首次工具调用都会引导你通过 OAuth 登录到 Pantrist 账户，无需手动复制令牌。
Claude.ai（网页或桌面应用）
- 打开 claude.ai → 个人资料菜单 → Settings → Connectors
- 点击 Add custom connector
- 填写：Name: Pantrist；URL: https://mcp.pantrist.app/mcp
- 保存 → 点击 Connect。会弹出一个 Pantrist 同意页面。
- 登录 → 授权 → 弹窗关闭。
- 开始新对话 —— Pantrist 工具（购物清单、食品储藏室、周计划、食谱）会出现在工具选择器中。可以尝试“我的购物清单上有什么？”
Claude Code（CLI）
在会话中运行 /mcp 确认它已被列出。首次工具调用会在浏览器中触发 OAuth 流程。
Claude Desktop（手动配置）
对于支持远程 MCP 的 Claude Desktop 版本，在 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 Windows/Linux 上的对应位置进行配置。重启 Claude Desktop。首次使用工具会启动 OAuth。
快速启动（stdio —— 最快路径）
可以在几分钟内验证整个工具集，无需接触 OAuth，只需使用在 Pantrist 网页应用中生成的 API 密钥。
在 claude_desktop_config.json（macOS: ~/Library/Application Support/Claude/claude_desktop_config.json）中配置。重启 Claude Desktop，然后尝试：“我的购物清单上有什么？”或“添加牛奶和鸡蛋。”
远程（Streamable HTTP + OAuth）
然后将其作为自定义连接器添加到 Claude，URL 为 https://mcp.pantrist.app/mcp 。服务器还暴露 GET /healthz 用于探针。完整的环境变量参考、入口和扩展说明参见 docs/DEPLOYMENT.md。
OAuth 握手流程
MCP 服务器是资源服务器；授权服务器是 Pantrist API。Claude 收到的令牌是 API Bearer，因此该服务器只是转发它。
⚠️ 依赖 —— 同意页面。API 的 authorization_endpoint 必须是一个浏览器可导航的登录/同意页面（API 的 /access-token/authorize 是一个受保护的 JSON 端点，无法直接导航）。需要在应用上托管一个（例如 https://pantrist.app/oauth/authorize），并将 API 的 OAUTH_AUTHORIZE_URL 环境变量设置为指向它。在该页面存在之前，请使用上面带有手动提供令牌的 stdio 路径。
大多数工具接受一个可选的 listId；如果省略，它们仅在 stdio 模式下使用 PANTRIST_LIST_ID（HTTP 模式要求显式提供 —— 参见多用户隔离）。完整的参数和项目结构细节见 docs/TOOLS.md。
所有这些端点都是公共 API 端点（存在于 /swagger-ui-json 中），因此此封装只需要已发布的规范 —— 从不需要私有 API 源代码。这为将该目录作为独立仓库开源保留了可能性。
重新生成 API 客户端
当 API 合约变更时，运行两个步骤。规范快照（openapi/pantrist-openapi.json）和生成的客户端（src/generated/pantrist-api.ts）都会被提交，以便项目在无网络访问的情况下构建。src/tools.ts 中的工具层是手工编写的，不会重新生成。
请参阅 .env.example。
