TAPD MCP Server
TAPD 是腾讯敏捷研发管理平台，覆盖需求、计划、研发、测试、发布研发全生命周期。通过 MCP (Model Context Protocol) 接入 Claude、Cursor 等 AI 助手，用自然语言管理需求、缺陷、任务和迭代。
系统要求
- Node.js >= 18.0.0
- TAPD Access Token（推荐）或 TAPD API 账号密码
快速开始
1. 获取凭证
方式一：个人访问令牌（推荐）
TAPD_ACCESS_TOKEN 为 TAPD 个人令牌：
- 登录 TAPD，进入 我的设置 → 个人访问令牌
- 点击"创建个人访问令牌"
- 令牌只显示一次，注意保存
方式二：API 账号密码（兼容）
- 未注册：前往 TAPD 开放平台 注册
- 已注册未授权 API：登录 TAPD，进入 公司管理 → API账号管理，复制 API 账号和 API 密钥
2. 配置 MCP 客户端
方式一：一键安装命令
注意替换以下参数（必填项标记为 必填，其余可选）。-s user 为用户级配置（所有项目生效），改为 -s project 则仅当前项目生效：
claude mcp add -s user tapd \
--env TAPD_ACCESS_TOKEN=your_access_token \ # 必填：个人访问令牌
--env TAPD_DEFAULT_WORKSPACE_ID=your_workspace_id \ # 必填：默认项目 ID
--env TAPD_NICK_NAME=your_nick_name \ # 推荐：用户昵称，用于 owner/creator 默认值
--env TAPD_DEFAULT_TASK_WORKITEM_TYPE_ID=your_task_type_id \ # 可选：默认 TASK 类型 ID，可通过 tapd_get_workitem_types 查询
--env TAPD_DEFAULT_STORY_WORKITEM_TYPE_ID=your_story_type_id \ # 可选：默认 STORY 类型 ID
-- npx -y "@xihe-lab/tapd-mcp-server@latest"
若忘记替换凭证，重新安装前需先卸载旧的配置：
claude mcp list
claude mcp remove tapd
方式二：手动配置
编辑 Claude Code 的配置文件（用户目录下 .claude.json）：
{
"mcpServers": {
"tapd": {
"command": "npx",
"args": ["-y", "@xihe-lab/tapd-mcp-server@latest"],
"env": {
"TAPD_ACCESS_TOKEN": "",
"TAPD_API_USER": "",
"TAPD_API_PASSWORD": "",
"TAPD_API_BASE_URL": "https://api.tapd.cn",
"TAPD_DEFAULT_WORKSPACE_ID": "",
"TAPD_NICK_NAME": "",
"TAPD_DEFAULT_STORY_WORKITEM_TYPE_ID": "",
"TAPD_DEFAULT_TASK_WORKITEM_TYPE_ID": ""
}
}
}
}
其他客户端配置方式：
- Claude Desktop：编辑
~/Library/Application Support/Claude/claude_desktop_config.json（macOS） - Cursor / VS Code：在项目根目录创建
.cursor/mcp.json或.vscode/mcp.json - WorkBuddy（腾讯 CodeBuddy 办公客户端）：见下方专节
配置格式与上方相同。
WorkBuddy（腾讯 CodeBuddy 办公客户端）
WorkBuddy 采用标准 mcpServers 配置，支持两级配置文件：
操作入口：侧边栏 插件 → 右上角 MCP 服务器 → 配置 MCP，在可视化编辑器中粘贴与上方相同的 mcpServers 配置并保存（也可直接编辑上述路径的 JSON 文件）。
保存后检查 MCP Server 状态灯：🟢 连接成功；🔴 配置异常（依次检查 JSON 格式、npx 环境、凭证有效性）。
安全提示：
TAPD_ACCESS_TOKEN是调用凭证。使用项目级配置时，请将.workbuddy/加入.gitignore，避免提交到仓库。
3. 开始使用
配置完成后重启客户端，直接用自然语言与 AI 助手对话：
查看我的待办需求
创建一个高优先级缺陷：登录页面报 500 错误
当前迭代的进度怎么样
给任务 10001 录入 3 小时工时
环境变量
注意：TAPD_API_USER/TAPD_API_PASSWORD（API 账号密码）与 TAPD_ACCESS_TOKEN（个人访问令牌）为两种调用方式，选一种即可。
工具集分级（2.1.0 新增）
2.1.0 起，server 默认只挂载工作台 8 域 85 工具 + 1 个 tapd_discover_tools 元工具（共 86 个），tools/list 上下文占用从约 46k token 降到约 17k token。其余工具不挂载即不可调用（可见性即权限边界），需要时用 discover 按需激活，无需重启。
默认集（启动即挂载）
discover 元工具：按需激活
- 无参调用：返回全部 27 个工具集
{id, label, toolCount, active, isDefault}及操作提示。 {"toolset": "<id>"}：立即注册该域全部工具并触发tools/list_changed（幂等，重复调用安全）。{"toolset": "all"}：一次性激活全部 216 工具。
AI 助手：tapd_discover_tools()
→ 发现 wiki 域（11 工具，active: false）
AI 助手：tapd_discover_tools({"toolset": "wiki"})
→ wiki 工具全部可见，随后可调用 tapd_get_wikis 等
环境变量配置（启动即挂载，免 discover）
# 追加域（默认集之外）：wiki + 发布计划
TAPD_TOOLSETS=wiki,release
# 完全恢复 2.0 全量挂载行为（推荐 2.0 老用户迁移期使用）
TAPD_TOOLSETS=all
# 只回补个别工具（与默认集并集生效，tapd_ 前缀可省略）
TAPD_TOOLS=tapd_create_release,get_wikis
# 只读档：全部写工具（含 tapd_change_workitem_type）不进入注册面
TAPD_PERMISSION_MODE=readonly
非法域 / 未知工具会在启动时经 MCP logging notification 告警并忽略（不写 stderr，不影响启动）。
从 2.0 升级
如果你依赖全量工具清单（如配置了工具白名单、或 AI 助手依赖少见的测试计划 / Wiki 工具），在 env 加一行 TAPD_TOOLSETS=all 即可恢复 2.0 行为；否则建议保持默认并让助手按需 discover。
支持的能力
共 216 个工具，覆盖 27 个模块。2.1.0 起默认只挂载其中工作台 8 域 85 工具（见工具集分级），其余经 tapd_discover_tools 或 TAPD_TOOLSETS 激活。
富媒体协作
在评论、需求/缺陷/任务描述和 Wiki 里 @ 人、贴图、挂附件，四类用法如下（rc.2 新增）。
@ 提及
在 md 正文里直接写 @昵称（如 请 @徐昭 今天内确认），写管道会自动转成 TAPD at-who 提及标记（角标 + 通知）。@@ 表示字面 @（不触发提及）；代码段、链接 URL、邮箱里的 @ 不会被误伤。tapd_md_to_html 可传 workspace_id 校验昵称是否项目成员（成员接口不可用时自动跳过校验，服务端仍会智能识别）；关键通知场景建议同时填 cc 兜底。
图片
1. tapd_upload_image(image_path="./截图.png")
→ { image_src: "/tfl/pictures/202609/截图.png", markdown: "" }
2. 把返回的 markdown 拼进 description / comment 正文
或者一步到位：tapd_md_to_html(content="......", upload_images=true)——扫描 md 里本地存在的图片路径，逐个上传图床并替换为 /tfl/ 远端路径（默认关闭的显式副作用，返回 uploaded_images 清单）。读侧用 tapd_get_image_url 可把 /tfl/ 路径换回临时访问 URL。
附件
1. tapd_upload_attachment(file_path="./设计稿.pdf", entity_type="story", entity_id="1139...")
→ 返回 embed_html（富文本锚点）与 embed_md（[📎 设计稿.pdf](attach:<ws>/<id>)）
2. 把 embed_md / embed_html 拼进评论或描述正文
tapd_md_to_html / 写管道会把 [📎 名称](attach:<ws>/<id>) 引用自动渲染成 TAPD 附件锚点卡片；读方向 tapd_html_to_md 把锚点还原为同名 md 引用。下载走 tapd_download_attachment（/attachments/down，无需额外授权）。第三方系统文件不传本体、只登记链接：tapd_attach_external_file。
内部链接（零成本）
正文里直接写 TAPD 工作项 URL 的 md 链接即可，如 [需求详情](https://www.tapd.cn/39814312/prong/stories/view/1139814312001001548)——前端自动卡片化，无需任何转换。
raw_html 直发通道
comment/story/task/bug/wiki 的 create/update 工具支持 raw_html: true：description 原样透传（绕过 md→html 自动转换），适合已含 TAPD 原生富文本标记或需要确定性透传的场景。默认 false 走 md 管道（@昵称 / 附件引用自动转换）。
常见问题
AI 助手没有识别到 TAPD 工具
确认 Node.js >= 18 已安装，npx 可正常执行。修改配置后需重启客户端。
升级 2.1.0 后工具清单变短了
这是预期行为：默认只挂载工作台 8 域 85 工具（见工具集分级）。测试计划、Wiki、发布计划等工具需先 tapd_discover_tools({"toolset": "<id>"}) 激活；要完全恢复 2.0 全量挂载，设 TAPD_TOOLSETS=all。直接调用未激活工具会返回 "Tool not found"——这不是能力缺失，先 discover 即可。
工具返回权限不足 (403)
按错误 JSON 的 code 分诊：
TAPD_AUTH_METHOD_MISMATCH：当前凭证是 Basic Auth（仅支持读接口），写操作必须配置TAPD_ACCESS_TOKEN（OAuth access token）。常见于「同时配了双凭证但 token 没生效」——检查变量名拼写与值非空（空串会回落 Basic）、配置作用域（项目级.mcp.json与用户级配置是两处）、改配置后必须重连 MCP/重启 CLI；重连后用tapd_get_current_user验证凭证身份TAPD_HTTP_403：读tapdMessage字段看 TAPD 原始原因——company does not match workspace表示 token 所属企业与目标项目不匹配（或 workspace_id 传错）；其余在 TAPD 开放平台检查应用权限，确认已勾选所需 API 模块且对目标项目有授权
创建任务时提示权限不足
如果 OAuth Token 没有 tasks::create 权限，可以通过 tapd_create_story 工具传入 TASK 类型的 workitem_type_id 来创建任务（仅需 stories::create 权限）：
用 tapd_create_story 创建一个任务，workitem_type_id 设为 TASK 类型
可通过 tapd_get_workitem_types 查询项目中可用的 TASK 类型 ID。
调用工具报「ID 超出 JS 安全整数范围」或首次调用 ID 校验失败
TAPD 的需求/缺陷/任务等实体长 ID 为 19-20 位数字（如 1139814312001001378），超出 JS 安全整数上限（Number.MAX_SAFE_INTEGER，16 位），以 JSON 数值形式传递会丢精度导致查询为空。所有长 ID 参数必须以字符串（带引号）传递。
所有工具的长 ID 参数描述均已包含引导提示；若传入安全整数范围内的数值（≤16 位，如短 ID）会自动转为字符串；超出安全范围的数值会返回明确错误提示，请按提示以字符串重传。
支持 Basic Auth 吗
支持。设置 TAPD_API_USER 和 TAPD_API_PASSWORD 即可，与 Access Token 二选一。注意：TAPD 权限模型下 Basic Auth 仅支持读取类接口，写操作（create/update 等）会直接返回 TAPD_AUTH_METHOD_MISMATCH 指引错误；写场景请使用 Access Token。双凭证并存时 Access Token 优先。
更新
MCP 客户端使用 npx 运行时会自动检查并下载最新版本。如需确保使用最新版本：
Claude Code
重新安装配置（会自动使用最新版本）：
claude mcp remove tapd
claude mcp add -s user tapd \
--env TAPD_ACCESS_TOKEN=your_access_token \
--env TAPD_DEFAULT_WORKSPACE_ID=your_workspace_id \
--env TAPD_NICK_NAME=your_nick_name \
--env TAPD_DEFAULT_TASK_WORKITEM_TYPE_ID=your_task_type_id \
--env TAPD_DEFAULT_STORY_WORKITEM_TYPE_ID=your_story_type_id \
-- npx -y "@xihe-lab/tapd-mcp-server@latest"
Claude Desktop / Cursor
修改配置文件中的版本号为 @latest 或删除版本锁定（WorkBuddy 的配置文件路径见「配置 MCP 客户端 → WorkBuddy」小节）：
{
"mcpServers": {
"tapd": {
"command": "npx",
"args": ["-y", "@xihe-lab/tapd-mcp-server@latest"],
"env": { ... }
}
}
}
npm 全局安装方式
如果通过 npm 全局安装使用：
# 查看当前安装版本
npm list -g @xihe-lab/tapd-mcp-server
# 更新到最新版本
npm update -g @xihe-lab/tapd-mcp-server
# 或指定版本安装
npm install -g @xihe-lab/[email protected]
更新后需重启 MCP 客户端。
npx 缓存清理
如果 npx 使用了旧版本缓存，可手动清理后重新运行：
# 清理 npx 缓存
npx clear-npx-cache
# 或手动删除缓存目录
rm -rf ~/.npm/_npx
查看版本信息
# 查看最新发布版本
npm view @xihe-lab/tapd-mcp-server version
# 查看所有已发布版本
npm view @xihe-lab/tapd-mcp-server versions
查看更新日志
查看 CHANGELOG.md 了解各版本的变更内容。
本地开发
@xihe-lab/tapd-mcp-server 以 npm 包分发，通过 npx -y @xihe-lab/tapd-mcp-server 运行（配置见上文）。本仓为 MCP 入口层（stdio server 接线），工具内核在同组织包 @xihe-lab/tapd-core 中演进——新增工具遵循其 ToolDef[] 模式（zod schema + handler，按 TAPD 领域模块组织）。
