# teambition-local MCP

将 Teambition 开放平台 v3 API 封装为 MCP 服务(Streamable HTTP),供 n8n 批量建任务工作流调用,也可复用给 Claude 等其他 MCP 客户端。

## 工具清单

| 工具 | 类型 | 用途 |
|---|---|---|
| tb_search_projects | 只读 | 按名称分页搜索项目,解析 projectId |
| tb_get_project | 只读 | 按 ID 查项目详情 |
| tb_list_project_members | 只读 | 分页拉项目成员,用于负责人匹配 |
| tb_search_tasks | 只读 | 项目内按关键词分页搜任务,查重/找父任务 |
| tb_get_task | 只读 | 按 ID 查任务,校验目标父任务 |
| tb_create_task | 写 | 创建任务(仅确认阶段调用),返回真实 taskId 和链接 |

优先级映射:普通→0,紧急→1,非常紧急→2。任务备注经 note 字段完整传入。

## 部署(Docker)

1. 复制 `.env.example` 为 `.env`,填入四个值。Secret 只存在这里,不要提交仓库、不要贴到聊天工具。
2. `docker build -t teambition-local-mcp . && docker run -d --name tb-mcp --env-file .env -p 3300:3300 teambition-local-mcp`
3. 健康检查:`curl http://<主机>:3300/healthz` → `{"ok":true}`
4. 验证工具列表:
   ```bash
   curl -X POST http://<主机>:3300/mcp \
     -H "Authorization: Bearer <MCP_AUTH_TOKEN>" \
     -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
   ```
5. 真实连通性验证(第一次务必做):用 tools/call 调 `tb_search_projects`,name 填一个已知项目名。若报权限错误,去开放平台「权限管理」勾选:项目查看、项目成员查看、任务列表查看(tb-core:task:list)、任务创建(tb-core:task:create),并在「应用发布」发布版本、安装到企业。

## 与 n8n 对接

- n8n 侧使用 MCP Client 节点,Endpoint 填 `http://<主机>:3300/mcp`,传输选 Streamable HTTP,认证用 Header:`Authorization: Bearer <MCP_AUTH_TOKEN>`(存入 n8n Credentials,勿写死在节点里)。
- n8n 与本服务同机或同内网部署时,不要把 3300 端口暴露到公网;必须公网时加 HTTPS 反代。

## 两处可能需要微调的端点

创建任务(/v3/task/create)、项目内任务查询(/v3/project/{id}/task/query)已对照官方文档核实。项目搜索(/v3/project/query)与项目成员(/v3/project/{id}/member/query)的路径和参数名请以你企业开放平台文档实测为准——如果第 5 步验证时报 404,在 server.mjs 顶部对应工具处改一行路径即可,工具名和入参结构不用动。