{
  "markdown": "<p align=\"center\">\n  <img src=\"./icon.png\" width=\"128\" height=\"128\" alt=\"tapd-mcp-server icon\" />\n</p>\n\n<h1 align=\"center\">TAPD MCP Server</h1>\n\n<p align=\"center\">\n  <strong>把 TAPD 装进你的 IDE 对话框 —— 查需求、评 PRD、修 Bug、回填提测，一句话直达，全程不切窗口。</strong>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://www.npmjs.com/package/tapd-mcp-server\"><img src=\"https://img.shields.io/npm/v/tapd-mcp-server?color=red\" alt=\"npm version\" /></a>\n  <a href=\"./CHANGELOG.md\"><img src=\"https://img.shields.io/badge/changelog-available-blue\" alt=\"changelog\" /></a>\n  <img src=\"https://img.shields.io/badge/tools-18-green\" alt=\"tools\" />\n  <img src=\"https://img.shields.io/badge/prompts-3-orange\" alt=\"prompts\" />\n  <a href=\"./package.json\"><img src=\"https://img.shields.io/npm/l/tapd-mcp-server\" alt=\"license\" /></a>\n</p>\n\n## ✨ 核心亮点\n\n- 🔌 **一键安装** —— 一段 `npx` 配置即用，无需 clone 仓库或装依赖，团队复制即接入。\n- 🐞 **Bug / 需求一条龙** —— 查询、读详情、分析定位、回填状态 / 评论 / 处理人，缺陷与需求全流程都在对话里完成（写操作均需你确认）。\n- 🗂️ **跨项目自动聚合** —— 一人负责多个项目？列表查询自动聚合你参与的全部项目，每条结果标注归属，无需逐个切换。\n- 🤖 **内置工作流 Prompt** —— PRD 研发评估、提测报告、Bug 修复回填三套开箱即用，编排现有工具、读着你的代码给结论。\n- 👥 **团队视角** —— 一句话让 Agent 跨成员、跨项目统计全组 bug / 需求（总数、未关闭、超 24h 未关闭、按成员拆分），组长盯进度直接可用（见下方「团队 Bug 统计」示例）。\n\n## 🚀 快速开始\n\n在 MCP 配置文件中添加以下内容，例如 `.cursor/mcp.json` 或 `.vscode/mcp.json`：\n\n```json\n{\n  \"mcpServers\": {\n    \"TAPD MCP\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"tapd-mcp-server\"],\n      \"env\": {\n        \"TAPD_ACCESS_TOKEN\": \"你的访问令牌\"\n      }\n    }\n  }\n}\n```\n\n| 变量 | 说明 |\n| --- | --- |\n| `TAPD_ACCESS_TOKEN` | 必填。TAPD 个人访问令牌，获取路径：TAPD 个人设置 → 个人访问令牌。请只放在本机 MCP 配置里，不要提交到代码仓库 |\n| `TAPD_ALLOW_RAW_WRITE` | 可选，默认关闭。设为 `true` 后才允许 `tapd_call_api` 发起 POST 写操作（每次调用仍需你在对话中确认），详见下文「通用透传」 |\n| `TAPD_MCP_SENTRY_DSN` | 可选。默认已启用错误上报（详见下文「错误上报与隐私」）；设为空字符串可关闭，或填自己的 DSN 覆盖默认上报目标 |\n\n### 错误上报与隐私\n\n本工具默认通过 [Sentry](https://sentry.io) 上报**未捕获的运行时错误**（崩溃堆栈、Node 版本、包版本），帮助维护者发现和修复问题。已做脱敏处理：\n\n- ✅ 上报：错误堆栈、HTTP 请求的域名与路径、响应状态码\n- ❌ 不上报：`TAPD_ACCESS_TOKEN`（走请求头，不进任何上报字段）、URL 查询参数（workspace_id、检索关键词等业务数据）、console 日志内容\n- 正常的工具调用与查询结果**不会**触发任何上报\n\n如需完全关闭，在 MCP 配置的 `env` 中设置 `TAPD_MCP_SENTRY_DSN` 为空字符串即可：\n\n```json\n\"env\": { \"TAPD_MCP_SENTRY_DSN\": \"\" }\n```\n\n## 💡 使用示例\n\n### 1. 团队 Bug 统计\n\n> 统计我们组每个成员名下的 bug 数量，重点关注今日新增、超 24h 未修复、bug 存留超 72h，图表展示\n\nAgent 会先用 `tapd_search_users` 确认各成员 nick，再用 `tapd_list_bugs`（跨项目聚合）逐个统计，汇总出全组视图：每人的未关闭、今日新增、超 24h / 72h、挂起等数量，并可按成员拆分明细。配合客户端的可视化能力（如 Cursor Canvas），还能直接生成下面这样的看板，组长盯进度一目了然。\n\n![团队 Bug 统计看板](./assets/team-bug.png)\n\n> 这是一个由 Agent 编排多个 MCP 工具完成的使用场景，并非单个内置工具；统计维度与可视化形式由你的指令和客户端能力决定。\n\n### 2. 查询我名下的需求和 Bug\n\n> 列出我名下待处理的需求和 bug\n\nAgent 跨项目聚合查询你负责的需求与缺陷，返回带内嵌超链接的 Markdown 表格——名称即链接、点击直达 TAPD，并标注每条所属项目。可继续按状态、创建时间、关联需求等过滤，或指定某个项目 ID 只查该项目。\n\n![查询名下需求与 Bug](./assets/view-bug-story.png)\n\n### 3. 批量判断服务端归因并追加处理人\n\n> 分析我名下待处理的 bug，哪些更像是服务端原因，并在处理人里添加服务端同学亚勇\n\nAgent 会先查询 bug 详情，再根据现象、接口返回、复现步骤等信息判断疑似服务端问题。更新处理人前会先用 `tapd_search_users` 确认成员身份，最后经你确认后再写回 TAPD。\n\n### 4. Bug 批量修复并回填\n\n> 帮我修复 123456、123457，结合代码定位并给出修改方案\n\nAgent 跨项目定位各 bug、拉取完整上下文（描述、复现、评论、附件、图片），结合当前代码库给出问题定位与修改建议（改码需你确认）；修复后用内置 Prompt `tapd_bug_fix_writeback` 生成回填草稿，确认后把状态改为已解决并写入评论，不会主动更新处理人。\n\n![Bug 批量修复并回填](./assets/bug-fix.png)\n\n### 5. 需求宣讲前研发评估\n\n> 使用 tapd_prd_analysis 分析需求 123456，生成需求宣讲前研发评估报告\n\n支持 MCP Prompts 的客户端会自动获得 `tapd_prd_analysis`。Agent 获取需求详情，按需查询需求变更、关联测试用例和关联 bug，再阅读当前代码库定位相关路由、页面、组件、接口、状态管理、数据模型、权限、埋点和配置，结合代码现状给出研发视角的判断（结论先行、不复述 PRD，写操作均需你确认）。\n\n报告按固定模板输出，便于宣讲前快速过审：\n\n- **结论** —— 需求目标、改动范围、最大风险、必须确认；\n- **技术判断** —— 相关代码、实现方案、接口 / 数据 / 权限；\n- **风险与依赖** —— 主要风险、外部依赖、漏洞 / 异常场景；\n- **测试建议** —— 验收路径、边界 / 回归；\n- **待确认问题** —— 最多 3 条，不确定项标注「需要确认」，不臆测、不凑数。\n\n### 6. 提测准入判断并生成提测文档\n\n> 使用 tapd_test_doc 生成提测文档，测试环境是 https://example.com/checkout.html\n\n支持 MCP Prompts 的客户端会自动获得 `tapd_test_doc`，只读代码、不改 TAPD，分两阶段：\n\n1. **提测准入判断** —— 自动对照需求的 PRD 用例、验收要点和未关闭缺陷，判断本次改动是否达标。\n2. **生成提测文档** —— 达标或你确认后，把代码改动翻译成「本次提测」与「测试重点」，写入项目根目录 `提测文档.md`。\n\n两种典型结果：\n\n- **准入通过** —— 直接生成提测文档，含 `测试环境` / `本次提测` / `测试重点` / `已知问题` 四段。\n- **准入不达标** —— 逐条列出差距，请你三选一：**A 继续提测并记为已知问题** / **B 继续提测忽略风险** / **C 终止提测**；未决策前不生成文档。\n\n## 🧰 能力总览\n\n### 工具（18）\n\n> 🛡️ 创建、回填、上传等写操作工具均内置二次确认：执行前需要你在对话中明确同意，防止 AI 未经授权修改 TAPD 数据；`tapd_call_api` 的 POST 写操作另需环境变量 `TAPD_ALLOW_RAW_WRITE=true` 开启。详见下文「安全确认」。\n\n**需求（Story）**\n\n| 工具 | 作用 |\n| --- | --- |\n| `tapd_list_stories` | 查询需求列表，支持跨项目聚合与多字段过滤 |\n| `tapd_get_stories` | 获取需求完整详情（描述、评论、附件、内嵌媒体） |\n| `tapd_create_story` | 创建需求，支持处理人、优先级、迭代、父需求、标签、排期、工时、自定义字段等 |\n| `tapd_writeback_story` | 回填需求评论 / 描述 / 状态 / 处理人，及标题、优先级、迭代、工时、标签等标准字段和自定义字段 |\n| `tapd_list_story_changes` | 查询需求变更历史 |\n| `tapd_list_story_test_cases` | 查询需求关联的测试用例 |\n\n**缺陷（Bug）**\n\n| 工具 | 作用 |\n| --- | --- |\n| `tapd_list_bugs` | 查询缺陷列表，支持跨项目聚合与多字段过滤 |\n| `tapd_get_bugs` | 获取缺陷完整详情（描述、复现、评论、附件、内嵌媒体） |\n| `tapd_create_bug` | 创建缺陷，支持处理人、优先级、严重程度、版本、迭代、排期、各类人员、工时、自定义字段等 |\n| `tapd_writeback` | 回填缺陷评论 / 标题 / 描述 / 状态 / 处理人，及优先级、版本、迭代、工时、标签等标准字段和自定义字段 |\n| `tapd_list_bug_changes` | 查询缺陷变更历史 |\n\n**缺陷多媒体**\n\n| 工具 | 作用 |\n| --- | --- |\n| `tapd_upload_bug_attachment` | 上传缺陷附件（png/mp4 等，≤250MB） |\n| `tapd_upload_bug_image` | 上传描述内嵌图，返回 html_code（≤5MB） |\n| `tapd_append_bug_description_image` | 上传图片并自动追加到缺陷描述（先读后写，避免覆盖） |\n\n**项目 / 迭代 / 成员**\n\n| 工具 | 作用 |\n| --- | --- |\n| `tapd_list_workspaces` | 查询你参与的项目（workspace） |\n| `tapd_list_iterations` | 查询项目迭代，支持按名称、状态、起止时间、创建人、自定义字段等过滤并自定义排序 |\n| `tapd_search_users` | 搜索 TAPD 成员，确认 nick，避免重名误写 |\n\n**通用透传**\n\n| 工具 | 作用 |\n| --- | --- |\n| `tapd_call_api` | 直接调用任意 TAPD OpenAPI 接口（任务、工时、测试计划、模块/版本配置、Wiki、看板等），兜底专用工具未覆盖的场景；path 以官方文档为准。POST 写操作默认禁用，需设置环境变量 `TAPD_ALLOW_RAW_WRITE=true` 且每次调用显式确认 |\n\n### 工作流 Prompt（3）\n\n随 MCP Server 一起分发，支持 MCP Prompts 的客户端会自动获得。**只编排现有工具、不新增写入能力**：\n\n| Prompt | 作用 |\n| --- | --- |\n| `tapd_prd_analysis` | 需求宣讲前的简洁研发评估：读需求 + 关联用例 + 关联缺陷 + 你的代码库，输出研发视角判断 |\n| `tapd_bug_fix_writeback` | Bug 修复后生成回填草稿，确认后改状态为已解决并写入评论 |\n| `tapd_test_doc` | 先做提测准入判断（对照 PRD 关联用例评估是否达标），再生成提测文档 |\n\n## 🛡️ 安全确认\n\n- 查询类操作不会修改 TAPD 数据。\n- 创建、回填评论、更新状态、更新处理人等写操作，都需要你在对话中明确确认。\n- 更新处理人前，Agent 会先搜索并确认 TAPD 成员，避免根据中文名或重名信息误写。\n- 处理人更新支持追加和替换。你说“添加、加上、补上”时会倾向追加；你说“改为、替换为、转给”时会倾向替换。\n\n## 🎁 彩蛋玩法\n\n### 定时巡检，模拟 AI 研发助理\n\n> 每 2 小时检查需求 123456 下是否有新增未解决 bug；发现后读取 bug 详情和当前代码，判断原因、生成修复方案，并在我确认后修改代码和回填处理结果\n\n配合支持定时任务的 Agent，可以把 TAPD MCP 变成一个轻量的 AI 研发助理：定时发现新缺陷、自动理解上下文、定位影响范围，并生成修复建议和回填草稿。\n\n它也可以巡检工作空间里的新需求，自动完成研发评估，必要时进入创建分支和开发流程。巡检与分析自动执行，改代码、提交、回填 TAPD 等写操作仍由你确认。\n",
  "bytes": 6198,
  "sha": "bdae80b9ac4d34252f2e7eb615d31c16c707501ea902fbe5072a0d8e3c83f5a0",
  "repo_slug": "sun-jingtao/tapd-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sun_jingtao_tapd_mcp_server_dfd71026/readme"
}