QTM4J MCP 服务器

一个拥有 42 个工具 的 MCP 服务器，用于 QMetry Test Management for Jira (QTM4J)。通过 Claude Desktop、Claude Code、VS Code Copilot、Cursor 或任何支持 MCP 的客户端，搜索并管理测试用例、周期、执行、计划、文件夹、自动化规则和项目元数据。

分发方式：

• npm: qtm4j-mcp-server

• MCP 注册表: 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 来获取新版本。

Related MCP server: qtm4j-mcp-server

配置

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

工具

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

请参阅 docs/TOOLS.md 获取完整参考，并参阅 docs/COOKBOOK.md 获取同事可以粘贴到任何 MCP 客户端中的示例提示词。

每个工具都附带注释（readOnlyHint, destructiveHint, idempotentHint, openWorldHint），以便客户端决定是否需要请求确认。读取工具接受 response_format 参数（默认为 json，或 markdown 以获得人类可读的输出）。大型响应会自动截断为 25k 字符，并提示缩小查询范围。

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

试用

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

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

客户端将调用 qtm4j_search_test_cases 并渲染响应。

获取测试周期 FS-TR-747 中的所有执行，并将任何未执行的标记为通过。

工具调用示例

将下方的 10011 替换为你的数字 Jira 项目 ID。在项目 URL 中查找它：…?projectId=10011&projectKey=FS。

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

// Update an execution result
// (executionResultId: 239444=Pass, 239441=Fail, 239443=Not Executed)
{
  "name": "qtm4j_update_test_execution",
  "arguments": {
    "cycleId": "gxMbioKJsyEr3E",
    "testCaseExecutionId": 287595809,
    "executionResultId": 239444,
    "comment": "Verified on staging"
  }
}

故障排除

• 工具未在我的客户端中显示。 编辑配置后重启客户端。检查 claude mcp list (Claude Code) 或 VS Code 的 MCP 面板以查看连接状态。首次运行时，npx -y qtm4j-mcp-server 可能需要几秒钟来下载包。

• 401 Unauthorized。 你的 QTM4J_API_KEY 无效或已过期。在 QMetry → API Keys 中生成一个新的。

• 执行或搜索端点返回 404。 许多端点需要内部数字 id，而不是像 FS-TR-747 这样的人类可读键。先调用 qtm4j_get_test_cycle 将键转换为内部 ID。

• 文件夹响应为空或过大。 将 folderId 传递给 qtm4j_list_folders 以限定在子树范围内——大型项目上的完整项目树可能会超过响应大小限制。

• projectId 被拒绝。 使用数字 Jira 项目 ID（例如 10011），而不是项目键（"FS"）。你可以在 Jira 项目 URL 中找到它：…?projectId=10011&projectKey=FS。

注意事项

• 搜索端点使用 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

错误和贡献

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

许可证

MIT