qtm4j-mcp-server

QTM4J MCP 服务

一个 MCP 服务，提供 87 个工具，用于 QMetry Test Management for Jira (QTM4J)。可通过 Claude Desktop、Claude Code、VS Code Copilot、Cursor 或任何兼容 MCP 的客户端搜索和管理测试用例、周期、执行、计划、文件夹、评论、缺陷、自动化规则和项目元数据。

分发渠道：

• npm：qtm4j-mcp-server
• MCP Registry：io.github.salehrifai42/qtm4j-mcp-server
• GitHub：salehrifai42/qmetrymcp

快速开始（无需克隆）

你需要一个 QMetry API 密钥（QMetry → API Keys）和 Node.js 18+。

Claude Desktop

编辑配置文件并重启 Claude：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "qtm4j": {
      "command": "npx",
      "args": ["-y", "qtm4j-mcp-server@^0.1"],
      "env": {
        "QTM4J_API_KEY": "your-api-key-here",
        "QTM4J_REGION": "US"
      }
    }
  }
}

Claude Code（CLI）

claude mcp add qtm4j -e QTM4J_API_KEY=your-api-key-here -e QTM4J_REGION=US -- npx -y qtm4j-mcp-server@^0.1

VS Code（GitHub Copilot Agent 模式）

在工作区中创建 .vscode/mcp.json：

{
  "servers": {
    "qtm4j": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "qtm4j-mcp-server@^0.1"],
      "env": {
        "QTM4J_API_KEY": "${env:QTM4J_API_KEY}",
        "QTM4J_REGION": "US"
      }
    }
  }
}

将 Copilot Chat 切换到 Agent 模式后，qtm4j_* 工具会自动显示。

Cursor

添加到 ~/.cursor/mcp.json（项目级配置则添加到 <project>/.cursor/mcp.json）：

{
  "mcpServers": {
    "qtm4j": {
      "command": "npx",
      "args": ["-y", "qtm4j-mcp-server@^0.1"],
      "env": { "QTM4J_API_KEY": "your-api-key-here" }
    }
  }
}

上述示例配置将软件包版本固定为 ^0.1，这样未来发布不兼容版本时就不会自动升级。如果你希望始终运行最新版本，可以移除 @^0.1 后缀。

全局安装（启动更快）

每次启动时，npx 都会重新解析软件包，这会增加几秒的启动延迟。如果你经常使用此服务，可以全局安装并让客户端直接指向其可执行文件：

npm install -g qtm4j-mcp-server

然后在客户端配置中，将 npx 命令替换为：

{
  "mcpServers": {
    "qtm4j": {
      "command": "qtm4j-mcp-server",
      "env": {
        "QTM4J_API_KEY": "your-api-key-here",
        "QTM4J_REGION": "US"
      }
    }
  }
}

权衡：启动即时且可离线运行，但需要执行 npm update -g qtm4j-mcp-server 才能获取新版本。

配置

变量	必填	默认值	说明
QTM4J_API_KEY	是	—	QMetry API 密钥；每次请求都会通过 apiKey 标头发送
QTM4J_REGION	否	US	US → https://qtmcloud.qmetry.com，AU → https://syd-qtmcloud.qmetry.com

💡 如果你的 QMetry 实例位于悉尼集群，请设置 QTM4J_REGION=AU。

工具

所有工具均以 qtm4j_ 为前缀，以避免与其他 MCP 服务冲突。

区域	工具
测试用例	qtm4j_create_test_case、qtm4j_get_test_case、qtm4j_search_test_cases、qtm4j_update_test_case、qtm4j_delete_test_case、qtm4j_archive_test_case、qtm4j_unarchive_test_case、qtm4j_clone_test_cases、qtm4j_create_test_steps、qtm4j_update_test_steps
测试周期	qtm4j_create_test_cycle、qtm4j_get_test_cycle、qtm4j_search_test_cycles、qtm4j_update_test_cycle、qtm4j_delete_test_cycle、qtm4j_archive_test_cycle、qtm4j_unarchive_test_cycle
测试执行	qtm4j_get_test_cycle_executions、qtm4j_get_test_execution、qtm4j_update_test_execution、qtm4j_update_test_step_execution、qtm4j_bulk_update_test_executions、qtm4j_get_execution_teststeps、qtm4j_update_execution_custom_fields、qtm4j_upload_execution_attachment、qtm4j_list_execution_attachments、qtm4j_delete_execution_attachment
测试计划	qtm4j_create_test_plan、qtm4j_get_test_plan、qtm4j_search_test_plans、qtm4j_update_test_plan、qtm4j_delete_test_plan、qtm4j_archive_test_plan、qtm4j_unarchive_test_plan、qtm4j_link_test_cycles_to_plan、qtm4j_get_linked_test_cycles、qtm4j_unlink_test_cycles_from_plan
评论	qtm4j_get_test_case_comments、qtm4j_add_test_case_comment、qtm4j_update_test_case_comment、qtm4j_delete_test_case_comment、qtm4j_get_test_cycle_comments、qtm4j_add_test_cycle_comment、qtm4j_update_test_cycle_comment、qtm4j_delete_test_cycle_comment、qtm4j_get_test_plan_comments、qtm4j_add_test_plan_comment、qtm4j_update_test_plan_comment、qtm4j_delete_test_plan_comment
缺陷	qtm4j_get_execution_defects、qtm4j_link_execution_defects、qtm4j_unlink_execution_defects、qtm4j_get_step_execution_defects、qtm4j_link_step_execution_defects、qtm4j_unlink_step_execution_defects、qtm4j_search_cycle_defects、qtm4j_get_cycle_defect_summary
文件夹	qtm4j_list_folders、qtm4j_create_folder
自动化	qtm4j_link_automation_rule、qtm4j_unlink_automation_rule、qtm4j_run_automation_rules
元数据（只读）	qtm4j_get_projects、qtm4j_get_priorities、qtm4j_get_priority_icons、qtm4j_get_statuses、qtm4j_get_environments、qtm4j_get_builds、qtm4j_get_labels、qtm4j_get_components、qtm4j_get_execution_results、qtm4j_get_custom_fields、qtm4j_get_parameters、qtm4j_get_user_permissions

完整参考请参阅 docs/TOOLS.md，示例提示词请参阅 docs/COOKBOOK.md，同事可以将这些提示词粘贴到任意 MCP 客户端中使用。

每个工具都带有注解（readOnlyHint、destructiveHint、idempotentHint、openWorldHint），以便客户端判断是否需要请求确认。读取工具接受 response_format 参数（默认值为 json，也可以使用 markdown 输出便于阅读的内容）。大型响应会自动截断至 25k 个字符，并提示缩小查询范围。

所有工具都使用 Zod 验证输入，通过 startAt/maxResults 分页，并会针对限流响应（HTTP 429）自动进行指数退避重试（最多 3 次）。

试用

连接后，可以向助手提出类似这样的请求：

搜索 QMetry 项目 <your project ID> 中状态为 "To Do" 的测试用例，并显示前 5 个。

客户端将调用 qtm4j_search_test_cases 并呈现响应。

获取测试周期 <KEY>-TR-747 中的所有执行，并将任何尚未执行的项标记为 Pass。

工具调用示例

将 <projectId> 和 <KEY> 替换为你所在租户的 Jira 数字项目 ID 和项目密钥。可以在项目 URL 中找到：…?projectId=<projectId>&projectKey=<KEY>。使用 qtm4j_get_execution_results 获取你所在租户的 executionResultId 值。

// Search test cases
{
  "name": "qtm4j_search_test_cases",
  "arguments": {
    "projectId": "<projectId>",
    "status": ["Approved"],
    "maxResults": 20,
    "response_format": "markdown"
  }
}

// Update an execution result
{
  "name": "qtm4j_update_test_execution",
  "arguments": {
    "cycleId": "<internal-cycle-id>",
    "testCaseExecutionId": "<internal-tc-execution-id>",
    "executionResultId": "<pass-id>",
    "comment": "Verified on staging"
  }
}

故障排查

• 客户端中未显示工具。 编辑配置后重启客户端。检查 claude mcp list（Claude Code）或 VS Code 的 MCP 面板，确认连接状态。首次运行时，npx -y qtm4j-mcp-server 可能需要几秒钟来下载软件包。
• 401 未授权。 你的 QTM4J_API_KEY 无效或已过期。前往 QMetry → API Keys 生成新的密钥。
• 执行或搜索端点返回 404。 许多端点需要的是内部数字 id，而不是 <KEY>-TR-747 这样的用户可见键值。先调用 qtm4j_get_test_cycle，将键值转换为内部 ID。
• 文件夹响应为空或过大。 将 folderId 传给 qtm4j_list_folders，以限定到某个子树——大型项目的完整项目树可能会超出响应大小限制。
• projectId 被拒绝。 使用 Jira 项目的数字 ID，而不是项目键字符串。可在 Jira 项目 URL 中找到：…?projectId=<numeric-id>&projectKey=<KEY>。

说明

• 搜索端点使用 POST /…/search——筛选条件放在请求正文的 filter 下，分页和排序参数放在查询字符串中。工具处理程序会为你封装这些操作。
• 204 No Content 响应会解析为 { message: "…" }。
• Swagger 规范目前未记录类似框架的自动化导入结果端点（例如 JUnit/TestNG/Cucumber 数据导入）；自动化工具涵盖规范中公开的规则运行和规则关联工作流。

开发

如果你想修改服务，可按以下步骤在本地设置：

git clone https://github.com/salehrifai42/qmetrymcp.git
cd qmetrymcp
npm install
npm run build
QTM4J_API_KEY=your-key npm start

使用 MCP Inspector 测试更改：

QTM4J_API_KEY=your-key npx @modelcontextprotocol/inspector node dist/index.js

运行单元测试（无需 API 密钥或网络——HTTP 客户端的传输层使用内存中的模拟实现）：

npm test

复现批量 xlsx 导入工作流

此仓库提供一个 Claude Code 技能（.claude/skills/xlsx-to-qmetry/）和一个 Python 导入程序（scripts/import-xlsx-to-qmetry.py），用于将包含 Excel 测试用例的文件夹导入 QMetry。项目、父文件夹、状态、自定义字段 ID、组件等租户专属 ID 不会提交到 git——请在自己的 config.json 中提供这些信息。

克隆后的首次运行：

cp config.template.json config.json
# Edit config.json — fill in:
#   connection.apiKey         (QMetry → avatar → API Keys → Generate)
#   connection.projectId      (numeric Jira project ID)
#   xlsxImport.parentFolderId (target folder for new test cases)
#   xlsxImport.statusId       (e.g. Draft / Approved)
#   xlsxImport.apiTestFieldId (custom field ID for "API Test" toggle, if used)
#   xlsxImport.options        (Yes/No option IDs for that custom field)
#   xlsxImport.componentIds   (default components to attach; can be [])

cp .claude/commands/qtm4j.template.md .claude/commands/qtm4j.md
# Optional: populate qtm4j.md with your tenant's IDs using the GET endpoints listed inside.

使用运行中的 MCP 服务（qtm4j_get_projects、qtm4j_get_statuses、qtm4j_get_components、qtm4j_get_custom_fields、qtm4j_list_folders）查找所需 ID，或运行 node scripts/refresh-field-reference.mjs，将所有内容导出到 field_reference.json。

然后从仓库根目录启动 Claude Code，xlsx-to-qmetry 技能会自动加载。将工作簿放在 Input/<batch-name>/ 下，并让 Claude 执行导入——完整工作流请参阅 docs/EXCEL-IMPORT-GUIDE.md。

错误和贡献

发现错误或想提出功能建议？请在 https://github.com/salehrifai42/qmetrymcp/issues 上提交 issue。欢迎提交 PR。

许可证

MIT