rtm-mcp

一个开源的 MCP（Model Context Protocol）服务器，用于 Requirements and Test Management for Jira REST API v2。它把 Requirements、Test Cases、Test Plans、Test Executions、 Test Case Executions、Defects、Tree Structure 和 Automation 暴露为 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

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

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

功能

• 40+ 工具：覆盖每个 RTM 资源的 CRUD 和链接管理。

• Bearer token 认证：通过 RTM_API_TOKEN 实现。在 Jira 中生成 token： Apps → Requirements and Test Management → ⋯ → REST API 身份验证 → 生成 Token。

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

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

• 类型化错误：映射为友好的 MCP 错误消息，不泄漏堆栈跟踪。

• 附件上传：支持 base64 负载（对沙箱化 MCP 客户端安全）。

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

快速开始

1. 生成 RTM API Token

1. 打开 Jira。

2. 进入 Apps → Requirements and Test Management。

3. 点击三点菜单（⋯）→ REST API 身份验证。

4. 点击 生成 Token，选择一个用户，添加一个标签，然后点击 生成。

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

2. 运行服务器

RTM_API_TOKEN=your-token-here npx rtm-mcp

服务器通过 stdio 提供 MCP 服务——将你的 MCP 客户端指向它即可。

Claude Desktop 配置

添加到 claude_desktop_config.json：

US / Global（默认 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"
      }
    }
  }
}

欧盟区域：

{
  "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.devinti.com/api \
  -- npx -y rtm-mcp

欧盟区域：

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.devinti.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 缺失或为空，服务器启动时会退出并给出友好的提示。

可用工具

所有工具都返回经过 pretty-print JSON 格式化的 MCP text 内容。

Requirements（REQUIREMENTS）

• rtm_list_requirements — 使用 projectKey 列出，可选用 folder、page、pageSize

• rtm_get_requirement — 按 requirementKey 获取

• rtm_create_requirement — 创建

• rtm_update_requirement — 部分更新

• rtm_delete_requirement — 删除

• rtm_set_requirement_covered_test_cases — 替换链接集合

• rtm_add_requirement_covered_test_cases — 追加

• rtm_remove_requirement_covered_test_cases — 移除子集

Test Cases（TEST_CASES）

• rtm_list_test_cases, rtm_get_test_case, rtm_create_test_case, rtm_update_test_case, rtm_delete_test_case

• rtm_set_test_case_covered_requirements, rtm_add_test_case_covered_requirements, rtm_remove_test_case_covered_requirements

Test Plans（TEST_PLANS）

• rtm_list_test_plans, rtm_get_test_plan, rtm_create_test_plan, rtm_update_test_plan, rtm_delete_test_plan

• rtm_set_test_plan_included_test_cases, rtm_add_test_plan_included_test_cases, rtm_remove_test_plan_included_test_cases

Test Executions（TEST_EXECUTIONS）

• rtm_list_test_executions, rtm_get_test_execution, rtm_create_test_execution, rtm_update_test_execution, rtm_delete_test_execution

Test Case Executions（TCE）

• rtm_link_defect_to_test_case_execution — 将缺陷关联到测试用例执行

• rtm_unlink_defect_from_test_case_execution — 取消关联缺陷

• rtm_link_defect_to_test_case_execution_step — 将缺陷关联到测试用例执行的步骤

• rtm_unlink_defect_from_test_case_execution_step — 取消步骤中的缺陷关联

• rtm_list_test_case_execution_attachments — 列出附件

• rtm_upload_test_case_execution_attachment — 上传附件（base64 输入）

Defects

• rtm_list_defects, rtm_get_defect, rtm_create_defect, rtm_update_defect, rtm_delete_defect

• rtm_set_defect_identifying_test_cases — 设置识别缺陷的测试用例

Tree

• rtm_get_tree_structure — 可选 projectKey、可选 resourceType

Automation

• rtm_import_test_results — 上传 JUnit/NUnit/Cucumber JSON 的 ZIP/TAR.GZ 包；返回 taskId

• rtm_get_import_status — 轮询直到 status 离开 IMPORTING 状态

示例

"列出项目 ACME 中最近的 10 条 Requirements。"

> rtm_list_requirements { projectKey: "ACME", pageSize: 10 }

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

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

"将缺陷 DEF-1 链接到测试用例执行 TCE-42 的第 3 步。"

> rtm_link_defect_to_test_case_execution_step { testCaseExecutionKey: "TCE-42", stepId: "3", defectTestKey: "DEF-1" }

"导入昨晚的 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 项目。冒烟测试会创建一个 Requirement，获取它，列出附近对象，然后清理。

发布

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.

报告 Bug

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

许可证

MIT —— 参见 LICENSE。

Copyright (c) 2026 rtm-mcp 贡献者。根据 MIT License 发布；你可以 自由地在开源和专有软件中使用、修改和分发本项目，前提是保留版权声明。