tapd-server-cli
为腾讯 TAPD 开发的 MCP（Model Context Protocol）Server。
通过个人访问令牌（personal access token, PAT）暴露 TAPD Open API，
让 Claude Code / Claude Desktop / Cursor / OpenCode / Codex 等 MCP 客户端
直接读写 TAPD 数据（需求 / 缺陷 / 迭代 / 工时 / 评论 / 附件 / 工作流 / 成员…）。
TAPD 官方 API 文档：https://o.tapd.tencent.com/document/api-doc/next/api/
字段语义、参数细节以官方文档为准。
特性
- 个人令牌零配置：仅
TAPD_TOKEN 一个环境变量即可启动，不需要注册 TAPD 应用。
- 一键安装到 MCP 客户端：
npx tapd-server-cli install 弹出 checkbox 多选 Claude Code / Codex / OpenCode / Cursor（也可命令行显式列出多家），自动写入对应客户端的 MCP 配置。
- 对称的卸载入口：
npx tapd-server-cli uninstall 同款多选界面，仅移除 mcpServers.tapd 节，保留同节其它 server 与文件其它字段；可加 --purge 一并清理本地 cookie / token 文件。
- Slash 命令向导：在客户端里输入
/mcp__tapd__setup 一键完成 PAT 验证、cookie 登录、附件下载工具装配。
- 基于令牌的权限按需暴露：仅对令牌真正可访问的 workspace 暴露
workspace_id 参数枚举。
- 资源覆盖：stories / bugs / tasks / iterations / releases / timesheets / comments / attachments / workflows / users / categories / modules / custom-fields。
- 错误归一化：把 TAPD 的
status 字段统一映射为 MCP 工具的结构化错误（unauthenticated / permission_denied / not_found / invalid_argument / rate_limited / internal）。
- 限流与重试：429 ≤3 次、5xx ≤2 次、指数退避；并发上限默认 8。
- 令牌脱敏：日志强制脱敏（
前 4 + *** + 后 4），令牌不落盘。
- stdio + streamable HTTP 双传输；HTTP 模式带
/healthz。
获取 TAPD 个人访问令牌
- 登录 TAPD（https://www.tapd.cn）。
- 进入「设置 → 个人设置 → 安全设置 → API 令牌」，按提示生成个人访问令牌。
- 复制令牌字符串（仅显示一次），保存到安全位置。
注意：令牌等同于账号凭证，不要提交到 Git，不要分享到聊天工具。
在 Claude Code 中安装（推荐）
最简单的安装方式——完全在 Claude Code 内完成，不需要终端：
> /plugin marketplace add wanggan768q/tapd-server-cli
> /plugin install tapd-server-cli@tapd-server-cli
弹窗会要求你输入「TAPD 个人访问令牌」（PAT），一次性输入即可：
- PAT 走系统 keychain（macOS/Windows 钥匙串、Linux 走
~/.claude/.credentials.json），不会落普通配置文件
- Plugin 启用后 MCP server 自动通过
npx -y tapd-server-cli 拉起，env 注入 PAT
/mcp 应该立即显示 tapd ✓ Connected
注意 — 配置文件位置：Claude Code 的 MCP 配置存在 ~/.claude.json（家目录顶层），不是 ~/.claude/settings.json（settings 文件不放 MCP）。如果你之前在 settings.json 里找过 tapd 配置没找到，是找错文件了——plugin 路径完全屏蔽这个困惑。
首次使用附件下载
附件下载需要浏览器 cookie（PAT 不够，TAPD 限制）。在 Claude Code 会话里输入：
> /tapd-server-cli:login
会弹出隔离浏览器窗口，登录 TAPD 后 cookie 自动持久化，附件下载工具立即可用。
升级（已通过 npx install claude-code 装过）
如果你之前用 npx tapd-server-cli install claude-code 装过，要切换到 plugin：
- 先卸载老的 user-scope 配置：
npx tapd-server-cli uninstall claude-code（清掉 ~/.claude.json 顶层 mcpServers.tapd）
- 在 Claude Code 内
/plugin marketplace add wanggan768q/tapd-server-cli
/plugin install tapd-server-cli@tapd-server-cli，弹窗输入 PAT- 重启 Claude Code
按 Claude Code 官方优先级（local > project > user > plugin > claude.ai），如果不先卸载 user scope 那条 tapd 配置，会屏蔽 plugin 提供的同名 server。
在其它客户端中安装（npx install）
适用于 Codex / OpenCode / Cursor，以及在终端里批量装 / CI 场景。
⚠️ 注意 — Claude Code 的 MCP 配置文件位置：MCP server 写在 ~/.claude.json（家目录顶层 mcpServers.tapd），不是 ~/.claude/settings.json（permissions / hooks / UI 行为的设置）。settings.json 里找不到 tapd 不是 bug——是找错文件了。如果你不想再纠结这两个文件，改用上面的 plugin 路径，PAT 直接进 keychain，不用碰任何配置文件。
如果你用 Claude Code，请优先看上面的「在 Claude Code 中安装（推荐）」节——plugin 路径更简单、PAT 直接进 keychain。
Claude Code / Codex 这两家客户端，本工具会优先调官方 CLI（claude mcp add-json --scope user / codex mcp add）写入配置；CLI 不可用时回退到手写配置文件，行为与旧版兼容。
最省事的形态——在 TTY 终端跑零参，按空格挑想装的客户端：
npx -y tapd-server-cli install
会弹出一个 checkbox 多选界面，列出 Claude Code / Codex / OpenCode / Cursor。空格切换、回车确认，可以一次选多家。
也可以在命令行直接显式列出客户端（跳过交互、CI 友好）：
# 单家（向后兼容旧用法）
npx -y tapd-server-cli install claude-code
# 多家（一次安装，PAT 只输入一次）
npx -y tapd-server-cli install claude-code codex
npx -y tapd-server-cli install claude-code codex opencode cursor
命令会：
- 交互式提示输入 TAPD 个人访问令牌一次，复用给所有目标客户端（隐藏输入，不留 shell history）
- 把
mcpServers.tapd 条目写入对应客户端的配置文件（写前自动备份到 .bak.<timestamp>）
- 输出每家结果汇总（
✔ wrote / = no-op / ✗ failed），并提示重启客户端
任意一家失败时不会中断其他家，最后整体退出码为非零。
然后在客户端新会话里输入 /mcp__tapd__setup，根据向导一路确认，登录 TAPD 后即装配完毕。
只授权一次即可。cookie 持久化到 ~/.config/tapd-mcp/cookie，过期后再跑一次 /mcp__tapd__setup 重新登录。
--dry-run 预览
不写文件，只打印将写入的内容（单家/多家均支持）：
npx -y tapd-server-cli install claude-code --dry-run
npx -y tapd-server-cli install claude-code codex --dry-run
非 tty / CI 场景
非 TTY 环境下零参会直接报错以保护脚本。请通过 TAPD_TOKEN env 提供令牌、并显式列出客户端：
TAPD_TOKEN=<your-pat> npx -y tapd-server-cli install claude-code
TAPD_TOKEN=<your-pat> npx -y tapd-server-cli install claude-code codex
卸载
Claude Code 用户（plugin 路径）
> /plugin uninstall tapd-server-cli
如需同时清理本地 cookie / token 文件：
npx -y tapd-server-cli uninstall claude-code --purge
其它客户端（npx install 路径）
与安装对称的撤销入口。零参 TTY 弹 checkbox 多选；显式列出客户端走非交互流程；--dry-run 只预览；--purge 额外清理本地凭据文件。不需要输入 PAT（卸载不读 token）。
# 交互式多选（TTY 下，空格选，回车确认）
npx -y tapd-server-cli uninstall
# 显式列出
npx -y tapd-server-cli uninstall claude-code
npx -y tapd-server-cli uninstall claude-code codex opencode cursor
# 预览不写入
npx -y tapd-server-cli uninstall claude-code --dry-run
