qtm4j-mcp-server

MCP server for QTM4J (QMetry Test Management for Jira) Open API at qtmcloud.qmetry.com/rest/api/latest.

Published package: @denis-platonov/qtm4j-mcp-server

MCP Registry name: io.github.denis-platonov/qtm4j

Supported Clients

Client	Status	Notes
Cursor	Supported	Configure with npx in ~/.cursor/mcp.json
JetBrains IDEs	Supported	Configure in AI Assistant MCP settings
VS Code	Supported	Configure in .vscode/mcp.json or user profile mcp.json
Antigravity	Supported	Configure in mcp_config.json via raw config

Tools

Tool	Description
create_test_cycle	Create a new test cycle (run)
search_test_case	Search for a test case by key (e.g. PE26-TC-2)
search_test_cases	Search test cases with pagination and optional summary filters
list_all_project_test_cases	Fetch and merge paginated test case results across a project
create_test_case	Create a new test case, optionally placing it in folders
list_cycle_test_cases	List all test cases in a cycle
add_test_case_to_cycle	Add a test case to a cycle
update_execution_status	Update execution result (Pass/Fail)
close_test_cycle	Close a test cycle
get_attachment_url	Get presigned URL for attachment upload
add_test_case_steps	Add one or more steps to a test case version
add_test_case_to_folders	Add a test case version to one or more folders
create_test_case_folder	Create a test case folder in a project
get_test_case	Fetch a test case by ID or key
get_test_case_details	Fetch full details for a specific test case version
get_test_case_steps	List or search steps on a test case version
list_test_case_folders	List project test case folders with flat paths
remove_test_case_from_folders	Remove a test case version from folders
update_test_case_description	Update a test case version description
update_test_case_step	Update an existing test step
update_test_case_summary	Update a test case version summary

The full set of tools (including search_test_cases with startAt, list_all_project_test_cases, folder and step helpers) is defined in src/tools.ts. After npm run build, run npm run list-tools to print every registered tool name — use this to confirm Cursor is using this build (you should see list_all_project_test_cases).

Cursor: use the local build for full functionality

npx @denis-platonov/qtm4j-mcp-server may be an older npm release. To guarantee tools such as list_all_project_test_cases and correct startAt handling:

1. In this directory: npm install && npm run build.
2. Merge cursor-mcp.example.json into your user Cursor config ~/.cursor/mcp.json (Windows: %USERPROFILE%\.cursor\mcp.json). Adjust the args path to your absolute dist/index.js.
3. Run npm run list-tools and confirm the tool count matches expectations.
4. Restart Cursor or toggle the MCP server off/on.

Cursor workspace tool descriptors

If you use Cursor’s workspace mcps/<server>/tools/*.json hints for the agent, keep those JSON schemas in sync with src/tools.ts (same parameter names as the Zod definitions). Rebuild and restart MCP after changing tools.

Setup

Prerequisites

• Node.js 20+
• QTM4J Open API key (generate from Jira: QMetry > Configuration > Open API)

Use with Cursor

Add to ~/.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"
      }
    }
  }
}

Use with JetBrains IDEs

In JetBrains AI Assistant, open Tools > AI Assistant > Model Context Protocol (MCP) and add:

{
  "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"
      }
    }
  }
}

Restart AI Assistant after saving the configuration.

Use with VS Code

Add this to your user or workspace MCP configuration file, typically .vscode/mcp.json or your profile-level 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"
      }
    }
  }
}

Use with Antigravity

In Antigravity, open Manage MCP Servers and then View raw config, then add this to 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"
      }
    }
  }
}

Build

npm install
npm run build

Testing

Run the hermetic test suite:

npm test

Run once without watch mode:

npm run test:run

Generate a coverage report:

npm run test:coverage

Run opt-in live integration tests against a real QTM4J environment:

npm run test:live

Live tests are skipped unless the required environment is present. The live suite currently supports:

• Read-focused checks using QTM4J_API_KEY, QTM4J_BASE_URL, and QTM4J_PROJECT_ID
• Search coverage with QTM4J_LIVE_TEST_CASE_KEY
• Cycle listing coverage with QTM4J_LIVE_TEST_CYCLE_ID
• Attachment URL coverage with QTM4J_LIVE_TEST_EXECUTION_ID
• Optional mutation checks only when QTM4J_LIVE_ENABLE_MUTATIONS=1

Example:

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

Local Development

Copy cursor-mcp.example.json into ~/.cursor/mcp.json (merge with existing mcpServers) and set args to the absolute path of dist/index.js, for example on Windows:

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

Optional: NODE_TLS_REJECT_UNAUTHORIZED": "0" in env only if you must use self-signed TLS.

Publish

This repository uses a tag-driven GitHub Actions release workflow.

1. Align package.json and server.json to the release version.
2. Build and verify locally:

npm run build
npm run test:run

3. Commit the release-prep changes.
4. Create and push the release tag:

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

5. GitHub Actions will verify the tag matches package.json and server.json, publish the npm package, and then publish server.json to the MCP Registry.

You can then verify discovery with:

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

GitHub Actions

This repo includes two workflows:

• CI: runs npm run build, npm run test:run, and npm run test:coverage on pushes to main and on pull requests
• Release: runs on tags matching v*, verifies the tag matches package.json and server.json, publishes to npm, and then publishes server.json to the MCP Registry

To use the release workflow, add this repository secret:

• NPM_TOKEN: npm access token with permission to publish @denis-platonov/qtm4j-mcp-server

Then cut a release like this:

git tag v1.1.0
git push origin v1.1.0

Environment Variables

Variable	Required	Default	Description
QTM4J_API_KEY	Yes	—	QTM4J Open API key
QTM4J_BASE_URL	No	https://qtmcloud.qmetry.com/rest/api/latest	API base URL
QTM4J_PROJECT_ID	No	—	Default project ID (avoids passing it in every call)
NODE_TLS_REJECT_UNAUTHORIZED	No	—	Set to 0 for self-signed certs