rtm-mcp

一个开源的 MCP（Model Context Protocol）服务器，用于 Requirements and Test Management for Jira REST API v2。它将需求、测试用例、测试计划、测试执行、 测试用例执行、缺陷、树结构和自动化暴露为 MCP 工具， 因此任何兼容 MCP 的客户端（Claude Desktop、IDE 扩展、自定义代理） 都可以直接驱动 RTM。

使用 NPX 运行——无需安装，无需克隆：

npx rtm-mcp

链接

• 📦 npm 包：https://www.npmjs.com/package/rtm-mcp

• 🐙 GitHub 仓库：https://github.com/ngocdd/rtm-mcp

• 🐛 问题跟踪器：https://github.com/ngocdd/rtm-mcp/issues

• 📚 RTM API 文档：https://deviniti.com/support/addon/cloud/requirements-test-management/latest/rest-api/

功能

• 32 个 MCP 工具，涵盖每个 RTM 资源的 CRUD、链接管理、附件和 CI 结果导入。

• Bearer 令牌认证，通过 RTM_API_TOKEN。在 Jira 中生成令牌： Apps → Requirements and Test Management → ⋯ → Rest API authentication → Generate Token。

• US + EU 区域——通过 RTM_BASE_URL 切换。

• 重试 + 超时 + 抖动内置于 HTTP 客户端（处理 429/5xx/网络错误）。

• 类型化错误映射为友好的 MCP 错误消息——绝不泄露堆栈跟踪。

• 附件上传接受 base64 负载（对沙盒 MCP 客户端安全）。

• 仅 stderr 日志——stdout 保持干净以用于 JSON-RPC。

Related MCP server: Jira QMetry MCP Server

快速开始

1. 生成 RTM API 令牌

1. 打开 Jira。

2. 转到 Apps → Requirements and Test Management。

3. 点击三点菜单（⋯）→ Rest API authentication。

4. 点击 Generate Token，选择用户，添加标签，点击 Generate。

5. 立即复制令牌——RTM 不会再次显示它。

2. 运行服务器

RTM_API_TOKEN=your-token-here npx rtm-mcp

服务器通过 stdio 使用 MCP 协议——将你的 MCP 客户端指向它。

Claude Desktop 设置

添加到 claude_desktop_config.json：

US / 全球（默认 URL）：

{
  "mcpServers": {
    "rtm": {
      "command": "npx",
      "args": ["-y", "rtm-mcp"],
      "env": {
        "RTM_API_TOKEN": "<your-token-here>",
        "RTM_BASE_URL": "https://rtm-us.deviniti.com/api"
      }
    }
  }
}

EU 区域：

{
  "mcpServers": {
    "rtm": {
      "command": "npx",
      "args": ["-y", "rtm-mcp"],
      "env": {
        "RTM_API_TOKEN": "<your-token-here>",
        "RTM_BASE_URL": "https://rtm-eu-api.hexygen.com/api"
      }
    }
  }
}

Claude Code CLI 设置

使用 claude mcp add 命令向 Claude Code 注册服务器。

用户范围（推荐——可用于你的所有项目）

claude mcp add --scope user --transport stdio rtm \
  -e RTM_API_TOKEN=<your-token-here> \
  -e RTM_BASE_URL=https://rtm-us.deviniti.com/api \
  -- npx -y rtm-mcp

EU 区域：

claude mcp add --scope user --transport stdio rtm \
  -e RTM_API_TOKEN=<your-token-here> \
  -e RTM_BASE_URL=https://rtm-eu-api.hexygen.com/api \
  -- npx -y rtm-mcp

--scope user 将条目写入 ~/.claude.json，因此此机器上的每个 Claude Code 项目都可以看到 rtm 服务器。

项目范围（仅此项目）

claude mcp add --scope project --transport stdio rtm \
  -e RTM_API_TOKEN=<your-token-here> \
  -e RTM_BASE_URL=https://rtm-us.deviniti.com/api \
  -- npx -y rtm-mcp

写入当前目录中的 .mcp.json（提交到 git）。

验证注册

claude mcp list           # see all configured servers
claude mcp get rtm        # inspect the rtm entry

移除服务器

claude mcp remove rtm

配置

缺少或为空的 RTM_API_TOKEN 会以友好的提示中止启动。

可用工具

所有工具都返回带有美化 JSON 的 MCP text 内容。共 32 个工具，按 RTM 资源组织如下。使用 MCP 主机的工具列表命令在运行时枚举它们。

需求（REQUIREMENTS）

• rtm_get_requirement — 按 requirementKey 获取

• rtm_create_requirement — 创建

• rtm_update_requirement — 部分更新

• rtm_delete_requirement — 永久删除

RTM 没有需求列表端点——使用 rtm_get_tree_structure 按项目枚举它们。

测试用例（TEST_CASES）

• rtm_get_test_case — 按 testCaseKey 获取

• rtm_create_test_case — 创建（传递 stepGroups 以定义步骤）

• rtm_update_test_case — 部分更新

• rtm_update_test_case_covered_requirements — 管理覆盖需求链接。传递 set / add / remove 中的一个。底层调用：PUT /api/v2/test-case/{key}/covered-requirements，请求体为 { coveredRequirements: { <op>: [...] } }。

rtm_delete_test_case 有意不暴露——通过 Jira UI 执行删除。RTM 没有列表端点——使用 rtm_get_tree_structure。

测试计划（TEST_PLANS）

镜像公共 RTM REST API 中记录的 8 个端点：

• rtm_get_test_plan — GET /api/test-plan/{testKey}

• rtm_create_test_plan — POST /api/test-plan

• rtm_update_test_plan — PUT /api/test-plan/{testKey}

• rtm_delete_test_plan — DELETE /api/test-plan/{testKey}

• rtm_update_test_plan_tc_order — PUT /api/test-plan/{testKey}/tc-order，请求体为 { order: [...] }

• rtm_create_test_plan_folder — POST /api/test-plan/{testKey}/tree/folders

• rtm_add_test_case_to_test_plan — POST /api/test-plan/{testKey}/testcases，请求体为 { testKey: "..." }

• rtm_remove_test_case_from_test_plan — DELETE /api/test-plan/{testKey}/testcases/{tcKey}

RTM 没有列表端点——使用 rtm_get_tree_structure。

测试执行（TEST_EXECUTIONS）

• rtm_get_test_execution — 按 testExecutionKey 获取

• rtm_create_test_execution — 通过执行测试计划创建（传递 testPlanTestKey）

• rtm_update_test_execution — 部分更新（接受 status、summary、description、priority、owner、customFields）

• rtm_delete_test_execution — 永久删除

RTM 没有列表端点——使用 rtm_get_tree_structure。

测试用例执行（TCE）

TCE = 测试执行中的一行，记录运行一个测试用例的结果。

• rtm_get_test_case_execution — 获取一个 TCE（结果、执行者、评论、缺陷、步骤）

• rtm_update_test_case_execution — 部分更新。传递 result: "Fail"（或 "Pass"、"Blocked" 等）以更改通过/失败状态。底层调用：PUT /api/v2/test-case-execution/{key}，请求体为 { result: { name: "Fail" } }。

• rtm_link_defect_to_test_case_execution — 将缺陷链接到整个 TCE

• rtm_link_defect_to_test_case_execution_step — 将缺陷链接到特定步骤

• rtm_list_test_case_execution_attachments — 列出 TCE 上的附件

• rtm_upload_test_case_execution_attachment（base64 输入）— 向 TCE 上传文件

• rtm_get_test_case_execution_attachment — 获取一个附件的元数据（返回下载 URL）

• rtm_list_test_case_execution_step_attachments — 列出单个步骤上的附件

• rtm_upload_test_case_execution_step_attachment（base64 输入）— 向特定步骤上传文件

TCE 上的 DELETE 端点（取消链接缺陷、删除附件）有意不暴露——通过 Jira UI 或直接调用底层 REST API 执行。端点存在；仅移除了 MCP 一次性包装器，因为破坏性操作应位于确认流程之后。

缺陷

• rtm_get_defect — 按 defectKey 获取

• rtm_create_defect — 创建（传递 identifyingTestCases 以链接到测试用例）

• rtm_update_defect — 部分更新

• rtm_delete_defect — 永久删除

RTM 没有列表端点——使用 rtm_get_tree_structure 或通过 Atlassian MCP 的 jira_search。

树

• rtm_get_tree_structure — 获取项目的文件夹树。需要数字 projectId（通过 Jira REST API 从 projectKey 解析）和 treeType ∈ REQUIREMENTS / TEST_CASES / TEST_PLANS / TEST_EXECUTIONS。

自动化

• rtm_import_test_results — 上传 JUnit / NUnit / Cucumber JSON 报告的 ZIP/TAR.GZ 归档；返回 taskId

• rtm_get_import_status — 轮询先前的 taskId，直到 status 离开 IMPORTING

每个资源使用的约定

示例

"枚举项目 ACME 中的需求。"

> // No list endpoint — fetch the tree and walk it.
> rtm_get_tree_structure { projectId: 10000, treeType: "REQUIREMENTS" }

"在文件夹 /Smoke 下创建一个名为 'Login with valid credentials' 的测试用例，并将其链接到需求 ACME-42。"

> rtm_create_test_case { projectKey: "ACME", summary: "Login with valid credentials", folder: "/Smoke", stepGroups: [...] }
> rtm_update_test_case_covered_requirements { testCaseKey: "<new>", set: ["ACME-42"] }

"向计划 KAN-52 添加 3 个测试用例，而不替换现有集合。"

> rtm_update_test_plan_included_test_cases {
    testPlanKey: "KAN-52",
    add: ["KAN-30", "KAN-31", "KAN-32"]
  }

"将缺陷 KAN-100 链接到测试用例执行 KAN-53-KAN-46 的步骤 8517443。"

> rtm_link_defect_to_test_case_execution_step {
    testCaseExecutionKey: "KAN-53-KAN-46",
    stepId: "8517443",
    defectTestKey: "KAN-100"
  }

"将 TCE KAN-53-KAN-46 标记为失败并添加评论。"

> rtm_update_test_case_execution {
    testCaseExecutionKey: "KAN-53-KAN-46",
    result: "Fail",
    comment: "Login button did not respond after 3 retries"
  }

"将截图附加到 TCE KAN-53-KAN-46 的步骤 2。"

> rtm_upload_test_case_execution_step_attachment {
    testCaseExecutionKey: "KAN-53-KAN-46",
    stepId: "8517444",
    filename: "evidence.png",
    contentBase64: "<base64 bytes>",
    mimeType: "image/png"
  }

"导入昨晚的 JUnit XML。"

> rtm_import_test_results {
    projectKey: "ACME",
    filename: "junit.zip",
    contentBase64: "<base64>",
    reportType: "JUNIT",
    jobUrl: "https://ci/job/123"
  }
> rtm_get_import_status { taskId: "<returned>" }

故障排除

开发

git clone <repo>
cd rtm-mcp
npm install
npm run build         # compile to dist/
npm test              # unit tests
npm run dev           # run from src/ via tsx
npm run typecheck     # tsc --noEmit

项目结构

src/
├── index.ts                  # entry point (shebang)
├── server.ts                 # McpServer wiring
├── config/                   # env validation + constants
├── client/
│   ├── http.ts               # fetch wrapper w/ retry + timeout
│   ├── errors.ts             # RTMError hierarchy
│   └── rtm-client.ts         # facade composing all resources
├── resources/                # one file per RTM resource
├── tools/                    # MCP tool registrations
├── schemas/                  # zod input schemas per tool group
└── utils/                    # logger, MCP response helpers
tests/
├── unit/                     # mocked fetch tests
└── integration/              # opt-in live tests (gated by RTM_LIVE=1)

实时集成测试

RTM_API_TOKEN=xxx \
RTM_BASE_URL=https://rtm-us.deviniti.com/api \
RTM_LIVE=1 \
RTM_TEST_PROJECT=ACME \
npm run test:integration

使用沙箱 Jira 项目。冒烟测试会创建一个需求，获取它，列出附近内容，然后进行清理。

发布

npm login
npm version patch   # or minor / major
npm publish --access public

prepublishOnly 会自动运行 typecheck、test、build。

贡献

这是一个开源项目——欢迎提交 issue 和 PR！

1. Fork 仓库：https://github.com/ngocdd/rtm-mcp

2. 创建功能分支：git checkout -b feat/my-tool

3. 在本地安装并运行测试：

   npm install
   npm run typecheck
   npm test

4. 为任何新的资源方法或工具添加测试。

5. 向 main 分支发起 Pull Request： https://github.com/ngocdd/rtm-mcp/compare

添加新的 RTM 端点

1. 向对应的 src/resources/<resource>.ts 模块添加类型化方法。

2. 向 src/schemas/<resource>.schema.ts 添加 zod 输入模式。

3. 在 src/tools/<resource>.ts 中注册 MCP 工具。

4. 在 tests/unit/ 中添加单元测试。

5. 运行 npm run typecheck && npm test。

报告错误

使用 https://github.com/ngocdd/rtm-mcp/issues——请包含 RTM 资源类型、端点路径、预期与实际响应以及（脱敏后的）请求体。

许可证

MIT——参见 LICENSE。

版权所有 (c) 2026 rtm-mcp 贡献者。根据 MIT 许可证 发布；只要保留版权声明，您就可以在开源和专有软件中自由使用、修改和分发本项目。