MCP 服务器

应用在 /api/mcp 提供无状态的 Streamable HTTP MCP 服务器。请让 MCP 客户端连接到应用的完整 URL，例如：

https://your-app.example/api/mcp

公开工具和受保护工具共用同一个端点。客户端无需登录即可初始化连接并发现全部工具。

公开 Todo 工具

所有调用方共享同一个公开 Todo 集合，无需身份认证或授权。集合最多保存 1,000 条记录；list_todos 接受 filter、orderBy、pageSize 和 pageToken，返回 todos 和 nextPageToken。未指定页大小或设为 0 时默认每页 50 条；超过 1,000 的值会限制为 1,000。筛选使用 AIP 表达式，例如 NOT completed AND title = "*read*"；空筛选表示包含全部 Todo。资源保留规范标识字段 path。

• list_todos
• create_todo
• toggle_todo
• delete_todo
• clear_completed_todos

调用 toggle_todo 时传入 Todo 的 path。省略 completed 会反转当前状态；传入该字段则会设置为指定状态。

Organization 和 Project 工具

Organization 和 Project 工具使用带 PKCE 的 OAuth 2.0 授权码流程。服务器支持动态客户端注册。MCP 客户端可通过发布在 /.well-known/oauth-protected-resource/api/mcp 的受保护资源元数据发现授权服务器。

请求 mcp scope 以调用以下工具：

• list_organizations
• get_organization
• list_projects：接受相同的列表参数以及 parent，例如 filter: "dueAt != null"。
• get_project
• create_project
• update_project
• delete_project

Project 工具使用资源 path 或 parent 字段，其中的路径段可使用稳定 ID 或 slug。读取 Project 需要 Organization 成员身份。现有 Organization 角色继续决定权限：Owner 和 Admin 可以创建、更新 Project，只有 Owner 可以删除。

需要刷新令牌的客户端还可以请求标准 offline_access scope。

结果和错误

工具成功时会同时返回内容等价的结构化 JSON 和文本 JSON。预期失败会返回安全的错误码和消息，例如 NOT_FOUND、PERMISSION_DENIED 或 RESOURCE_EXHAUSTED。未携带 OAuth 凭据调用受保护工具会返回 UNAUTHENTICATED 工具错误。