QTM4J MCP 服务器

一个 MCP 服务器，将 QMetry Test Management for Jira Cloud (QTM4J) REST API 暴露为 Claude（或任何支持 MCP 的客户端）可以调用的工具。

功能

工具涵盖了 QTM4J 主要实体中最常见的 CRUD 流程：

所有工具都使用 Zod 验证输入，通过 startAt / maxResults 对列表端点进行分页，并自动重试受速率限制 (HTTP 429) 的响应，最多尝试 3 次，并采用指数退避策略。

要求

• Node.js 18+ (使用原生 fetch)

• QMetry API 密钥 (从 QMetry → API Keys 获取)

安装

git clone https://github.com/salehrifai42/qmetrymcp.git
cd qmetrymcp
npm install
npm run build

配置

服务器完全通过环境变量进行配置：

运行

QTM4J_API_KEY=your-key npm start

服务器通过 stdio 进行 MCP 通信 — 你通常不需要直接运行它；你的 MCP 客户端（Claude Desktop、Claude Code 等）会启动它。

MCP 客户端配置

所有客户端都使用 node 直接运行服务器。将 /path/to/qmetrymcp 替换为你克隆仓库的绝对路径。

Claude Desktop

在 macOS 上编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（或平台等效文件）并重启 Claude Desktop：

{
  "mcpServers": {
    "qtm4j": {
      "command": "node",
      "args": ["/path/to/qmetrymcp/dist/index.js"],
      "env": {
        "QTM4J_API_KEY": "your-api-key-here",
        "QTM4J_REGION": "US"
      }
    }
  }
}

Claude Code (CLI)

使用 claude mcp add 命令：

claude mcp add qtm4j \
  -e QTM4J_API_KEY=your-api-key-here \
  -e QTM4J_REGION=US \
  -- node /path/to/qmetrymcp/dist/index.js

这会写入你的用户级配置文件 (~/.claude.json)。若要将其限定在单个仓库中，请在项目根目录下放置一个 .mcp.json，其 mcpServers 结构与上面的 Claude Desktop 示例相同 — Claude Code 会自动识别它。

验证它是否已注册：

claude mcp list

在会话中，你也可以运行 /mcp 来查看已连接的服务器及其工具。

GitHub Copilot (VS Code)

Copilot 的代理模式通过工作区中的 .vscode/mcp.json 文件（或用户 settings.json 中 github.copilot.chat.mcp.servers 下的等效块）支持 MCP。注意：Copilot 的模式使用 servers（而不是 mcpServers）并需要显式的 type：

// .vscode/mcp.json
{
  "servers": {
    "qtm4j": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/qmetrymcp/dist/index.js"],
      "env": {
        "QTM4J_API_KEY": "your-api-key-here",
        "QTM4J_REGION": "US"
      }
    }
  }
}

保存后，打开 Copilot Chat 面板，切换到 Agent 模式，qtm4j 工具就会出现在工具选择器中。如果你不想提交 API 密钥，请使用 VS Code 的密钥输入功能：

{
  "inputs": [
    { "id": "qtm4jKey", "type": "promptString", "description": "QTM4J API Key", "password": true }
  ],
  "servers": {
    "qtm4j": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/qmetrymcp/dist/index.js"],
      "env": {
        "QTM4J_API_KEY": "${input:qtm4jKey}",
        "QTM4J_REGION": "US"
      }
    }
  }
}

试用

连接后，向助手询问类似以下内容：

在 QMetry 项目 10011 中搜索状态为 "Approved" 的测试用例，并显示前 5 个。

客户端将调用 search_test_cases 并传入 { projectId: 10011, status: ["Approved"], maxResults: 5 }，然后渲染响应。

工具调用示例

// Search test cases in project with numeric ID 10011
{
  "name": "search_test_cases",
  "arguments": {
    "projectId": 10011,
    "status": ["Approved"],
    "maxResults": 20
  }
}

// Update an execution result
{
  "name": "update_test_execution",
  "arguments": {
    "cycleId": 1234,
    "testCaseExecutionId": 56789,
    "executionResultId": 2,
    "comment": "Verified on staging"
  }
}

错误处理

• 非 2xx 响应会返回一个包含 HTTP 状态和已解析 API 正文的工具错误。

• 网络错误会返回描述性的错误消息。

• 429 响应会自动重试，并采用指数退避策略（最多尝试 3 次）。

注意事项

• projectId 必须是数字形式的 Jira 项目 ID (例如 10011)，而不是项目键 (例如 "FS")。你可以在 Jira 项目 URL 中找到它：…?projectId=10011&projectKey=FS。

• 搜索端点使用 POST /…/search — 过滤器放在正文的 filter 下，分页/排序放在查询字符串中。MCP 处理程序会自动为你封装此过程。

• 返回 204 No Content 的“更新”端点会解析为一个简单的 { message: "…" } 有效负载。

• Swagger 规范目前不记录框架式的自动化导入结果端点（例如 JUnit/TestNG/Cucumber 摄取）；此处的自动化工具涵盖了规范中暴露的规则运行和规则链接流程。