QTM4J

qtm4j-mcp-server

用于 QTM4J（QMetry Test Management for Jira）Open API 的 MCP 服务，地址为 qtmcloud.qmetry.com/rest/api/latest。

已发布的软件包：@denis-platonov/qtm4j-mcp-server

MCP Registry 名称：io.github.denis-platonov/qtm4j

支持的客户端

客户端	状态	说明
Cursor	支持	在 ~/.cursor/mcp.json 中使用 npx 配置
JetBrains IDEs	支持	在 AI Assistant MCP 设置中配置
VS Code	支持	在 .vscode/mcp.json 或用户配置文件 mcp.json 中配置
Antigravity	支持	通过原始配置在 mcp_config.json 中配置

工具

工具	说明
create_test_cycle	创建新的测试周期（运行）
search_test_case	按键搜索测试用例（例如 PE26-TC-2）
search_test_cases	分页搜索测试用例，并可选择按摘要筛选
list_all_project_test_cases	获取并合并项目中分页返回的测试用例结果
create_test_case	创建新的测试用例，可选择将其放入文件夹
list_cycle_test_cases	列出测试周期中的所有测试用例
add_test_case_to_cycle	将测试用例添加到测试周期
update_execution_status	更新执行结果（通过/失败）
close_test_cycle	关闭测试周期
get_attachment_url	获取用于上传附件的预签名 URL
add_test_case_steps	向测试用例版本添加一个或多个步骤
add_test_case_to_folders	将测试用例版本添加到一个或多个文件夹
create_test_case_folder	在项目中创建测试用例文件夹
get_test_case	按 ID 或键获取测试用例
get_test_case_details	获取特定测试用例版本的完整详情
get_test_case_steps	列出或搜索测试用例版本中的步骤
list_test_case_folders	列出项目测试用例文件夹，并显示扁平路径
remove_test_case_from_folders	从文件夹中移除测试用例版本
update_test_case_description	更新测试用例版本说明
update_test_case_step	更新现有测试步骤
update_test_case_summary	更新测试用例版本摘要

完整的工具集（包括带有 startAt 的 search_test_cases、list_all_project_test_cases、文件夹和步骤辅助工具）定义在 src/tools.ts 中。运行 npm run build 后，运行 npm run list-tools 可打印所有已注册的工具名称 — 用它确认 Cursor 使用的是此构建版本（你应该能看到 list_all_project_test_cases）。

Cursor：使用本地构建以获得完整功能

npx @denis-platonov/qtm4j-mcp-server 可能是较旧的 npm 版本。为确保可使用 list_all_project_test_cases 等工具并正确处理 startAt：

1. 在此目录中运行：npm install && npm run build。
2. 将 cursor-mcp.example.json 合并到你的 Cursor 用户配置 ~/.cursor/mcp.json 中（Windows：%USERPROFILE%\.cursor\mcp.json）。将 args 路径调整为 dist/index.js 的绝对路径。
3. 运行 npm run list-tools，确认工具数量符合预期。
4. 重启 Cursor，或关闭再开启 MCP 服务。

Cursor 工作区工具描述符

如果你使用 Cursor 工作区的 mcps/<server>/tools/*.json 提示来辅助 Agent，请确保这些 JSON schema 与 src/tools.ts 保持同步（参数名称与 Zod 定义一致）。更改工具后，请重新构建并重启 MCP。

设置

先决条件

• Node.js 20+
• QTM4J Open API 密钥（从 Jira 生成：QMetry > Configuration > Open API）

与 Cursor 配合使用

添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "qtm4j": {
      "command": "npx",
      "args": ["-y", "@denis-platonov/qtm4j-mcp-server"],
      "env": {
        "QTM4J_API_KEY": "your-api-key",
        "QTM4J_BASE_URL": "https://qtmcloud.qmetry.com/rest/api/latest",
        "QTM4J_PROJECT_ID": "10800"
      }
    }
  }
}

与 JetBrains IDE 配合使用

在 JetBrains AI Assistant 中，打开 Tools > AI Assistant > Model Context Protocol (MCP) 并添加：

{
  "mcpServers": {
    "qtm4j": {
      "command": "npx",
      "args": ["-y", "@denis-platonov/qtm4j-mcp-server"],
      "env": {
        "QTM4J_API_KEY": "your-api-key",
        "QTM4J_BASE_URL": "https://qtmcloud.qmetry.com/rest/api/latest",
        "QTM4J_PROJECT_ID": "10800"
      }
    }
  }
}

保存配置后，重启 AI Assistant。

与 VS Code 配合使用

将此内容添加到用户或工作区 MCP 配置文件，通常是 .vscode/mcp.json 或配置文件级别的 mcp.json：

{
  "servers": {
    "qtm4j": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@denis-platonov/qtm4j-mcp-server"],
      "env": {
        "QTM4J_API_KEY": "your-api-key",
        "QTM4J_BASE_URL": "https://qtmcloud.qmetry.com/rest/api/latest",
        "QTM4J_PROJECT_ID": "10800"
      }
    }
  }
}

与 Antigravity 配合使用

在 Antigravity 中，打开 Manage MCP Servers，然后选择 View raw config，再将此内容添加到 mcp_config.json：

{
  "mcpServers": {
    "qtm4j": {
      "command": "npx",
      "args": ["-y", "@denis-platonov/qtm4j-mcp-server"],
      "env": {
        "QTM4J_API_KEY": "your-api-key",
        "QTM4J_BASE_URL": "https://qtmcloud.qmetry.com/rest/api/latest",
        "QTM4J_PROJECT_ID": "10800"
      }
    }
  }
}

构建

npm install
npm run build

测试

运行独立测试套件：

npm test

运行一次，不启用监视模式：

npm run test:run

生成覆盖率报告：

npm run test:coverage

针对真实的 QTM4J 环境运行选择性实时集成测试：

npm run test:live

除非所需环境已就绪，否则会跳过实时测试。目前，实时测试套件支持：

• 使用 QTM4J_API_KEY、QTM4J_BASE_URL 和 QTM4J_PROJECT_ID 进行以读取为主的检查
• 使用 QTM4J_LIVE_TEST_CASE_KEY 覆盖搜索测试
• 使用 QTM4J_LIVE_TEST_CYCLE_ID 覆盖周期列表测试
• 使用 QTM4J_LIVE_TEST_EXECUTION_ID 覆盖附件 URL 测试
• 仅当 QTM4J_LIVE_ENABLE_MUTATIONS=1 时运行可选的修改检查

示例：

QTM4J_API_KEY=your-api-key \
QTM4J_PROJECT_ID=10800 \
QTM4J_LIVE_TEST_CASE_KEY=PE26-TC-2 \
QTM4J_LIVE_TEST_CYCLE_ID=PE26-R1 \
QTM4J_LIVE_TEST_EXECUTION_ID=12345 \
npm run test:live

本地开发

将 cursor-mcp.example.json 复制到 ~/.cursor/mcp.json（与现有的 mcpServers 合并），并将 args 设置为 dist/index.js 的绝对路径，例如在 Windows 上：

"args": ["C:/Users/you/projects/qa-all-in-one/tools/qtm4j-mcp-server/dist/index.js"]

可选：仅当必须使用自签名 TLS 时，才在 env 中设置 NODE_TLS_REJECT_UNAUTHORIZED": "0"。

发布

此仓库使用由标签驱动的 GitHub Actions 发布工作流。

1. 将 package.json 和 server.json 调整为发布版本。
2. 在本地构建并验证：

npm run build
npm run test:run

3. 提交发布准备变更。
4. 创建并推送发布标签：

git tag v1.1.0
git push origin sync/desktop-qtm4j-source
git push origin v1.1.0

5. GitHub Actions 将验证标签与 package.json 和 server.json 中的版本一致，然后发布 npm 包，最后将 server.json 发布到 MCP Registry。

随后，你可以通过以下命令验证是否可发现：

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.denis-platonov/qtm4j"

GitHub Actions

此仓库包含两个工作流：

• CI：在推送到 main 以及提交拉取请求时，运行 npm run build、npm run test:run 和 npm run test:coverage
• Release：在匹配 v* 的标签上运行，验证标签与 package.json 和 server.json 中的版本一致，发布到 npm，然后将 server.json 发布到 MCP Registry

要使用发布工作流，请添加此仓库密钥：

• NPM_TOKEN：具有发布 @denis-platonov/qtm4j-mcp-server 权限的 npm 访问令牌

然后按以下步骤发布：

git tag v1.1.0
git push origin v1.1.0

环境变量

变量	必需	默认值	描述
QTM4J_API_KEY	是	—	QTM4J Open API 密钥
QTM4J_BASE_URL	否	https://qtmcloud.qmetry.com/rest/api/latest	API 基础 URL
QTM4J_PROJECT_ID	否	—	默认项目 ID（避免每次调用时都传入）
NODE_TLS_REJECT_UNAUTHORIZED	否	—	自签名证书设为 0