QTM4J MCP-Server

Ein MCP-Server mit 42 Tools für QMetry Test Management for Jira (QTM4J). Suchen und verwalten Sie Testfälle, Zyklen, Ausführungen, Pläne, Ordner, Automatisierungsregeln und Projektmetadaten direkt aus Claude Desktop, Claude Code, VS Code Copilot, Cursor oder jedem anderen MCP-kompatiblen Client.

Distribution:

• npm: qtm4j-mcp-server

• MCP Registry: io.github.salehrifai42/qtm4j-mcp-server

• GitHub: salehrifai42/qmetrymcp

Schnellstart (kein Klonen erforderlich)

Sie benötigen einen QMetry-API-Schlüssel (QMetry → API Keys) und Node.js 18+.

Claude Desktop

Bearbeiten Sie Ihre Konfigurationsdatei und starten Sie Claude neu:

• 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-Modus)

Erstellen Sie .vscode/mcp.json in Ihrem Arbeitsbereich:

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

Schalten Sie Copilot Chat in den Agent-Modus, und die qtm4j_*-Tools erscheinen automatisch.

Cursor

Fügen Sie dies zu ~/.cursor/mcp.json hinzu (oder <project>/.cursor/mcp.json für Projektebene):

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

Die obigen Beispielkonfigurationen fixieren das Paket auf ^0.1, damit ein zukünftiges Breaking-Release kein automatisches Upgrade auslöst. Entfernen Sie den @^0.1-Suffix, wenn Sie immer die neueste Version verwenden möchten.

Globale Installation (schnellerer Start)

npx löst das Paket bei jedem Start neu auf, was zu einer Startverzögerung von einigen Sekunden führt. Wenn Sie den Server häufig verwenden, installieren Sie ihn global und verweisen Sie Ihren Client direkt auf die Binärdatei:

npm install -g qtm4j-mcp-server

Ersetzen Sie dann in Ihrer Client-Konfiguration den npx-Befehl:

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

Kompromiss: Sofortiger Start und Offline-Funktionalität, aber Sie müssen npm update -g qtm4j-mcp-server ausführen, um neue Versionen zu erhalten.

Related MCP server: qtm4j-mcp-server

Konfiguration

💡 Setzen Sie QTM4J_REGION=AU, wenn sich Ihre QMetry-Instanz im Sydney-Cluster befindet.

Tools

Alle Tools haben das Präfix qtm4j_, um Kollisionen mit anderen MCP-Servern zu vermeiden.

Siehe docs/TOOLS.md für die vollständige Referenz und docs/COOKBOOK.md für Beispiel-Prompts, die Kollegen in jeden MCP-Client kopieren können.

Jedes Tool wird mit Annotationen (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) geliefert, damit Clients entscheiden können, ob eine Bestätigung erforderlich ist. Lese-Tools akzeptieren einen response_format-Parameter (Standard json oder markdown für menschenlesbare Ausgabe). Große Antworten werden automatisch bei 25.000 Zeichen abgeschnitten, mit einem Hinweis, die Abfrage einzugrenzen.

Alle Tools validieren Eingaben mit Zod, paginieren über startAt/maxResults und wiederholen automatisch ratenbegrenzte (HTTP 429) Antworten mit exponentiellem Back-off (bis zu 3 Versuche).

Ausprobieren

Sobald die Verbindung hergestellt ist, fragen Sie Ihren Assistenten etwa so:

Durchsuche das QMetry-Projekt <Ihre Projekt-ID> nach Testfällen mit dem Status "To Do" und zeige mir die ersten 5.

Der Client ruft qtm4j_search_test_cases auf und rendert die Antwort.

Hole alle Ausführungen im Testzyklus FS-TR-747 und markiere alle nicht ausgeführten als "Pass".

Beispiel-Tool-Aufrufe

Ersetzen Sie 10011 unten durch Ihre numerische Jira-Projekt-ID. Sie finden diese in der Projekt-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"
  }
}

Fehlerbehebung

• Tools erscheinen nicht in meinem Client. Starten Sie den Client nach dem Bearbeiten der Konfiguration neu. Überprüfen Sie claude mcp list (Claude Code) oder das MCP-Panel von VS Code auf den Verbindungsstatus. Beim ersten Ausführen kann npx -y qtm4j-mcp-server einige Sekunden dauern, um das Paket herunterzuladen.

• 401 Unauthorized. Ihr QTM4J_API_KEY ist ungültig oder abgelaufen. Generieren Sie einen neuen unter QMetry → API Keys.

• 404 bei Ausführungs- oder Such-Endpunkten. Viele Endpunkte benötigen die interne numerische id, nicht den menschenlesbaren Schlüssel wie FS-TR-747. Rufen Sie zuerst qtm4j_get_test_cycle auf, um den Schlüssel in die interne ID zu übersetzen.

• Leere oder zu große Ordnerantwort. Übergeben Sie folderId an qtm4j_list_folders, um den Bereich auf einen Teilbaum einzugrenzen — vollständige Projektbäume bei großen Projekten können das Antwortgrößenlimit überschreiten.

• projectId abgelehnt. Verwenden Sie die numerische Jira-Projekt-ID (z. B. 10011), nicht den Projektschlüssel ("FS"). Sie finden diese in der Jira-Projekt-URL: …?projectId=10011&projectKey=FS.

Hinweise

• Such-Endpunkte verwenden POST /…/search — Filter kommen in den Body unter filter, Paginierung/Sortierung in den Query-String. Tool-Handler kapseln dies für Sie.

• 204 No Content-Antworten werden als { message: "…" } aufgelöst.

• Die Swagger-Spezifikation dokumentiert derzeit keinen Endpunkt für den Import von Ergebnissen im Framework-Stil (z. B. JUnit/TestNG/Cucumber-Ingestion); die Automatisierungstools decken die in der Spezifikation offengelegten Abläufe für Regelausführungen und Regelverknüpfungen ab.

Entwicklung

Lokale Einrichtung, wenn Sie den Server ändern möchten:

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

Testen Sie Änderungen mit dem MCP Inspector:

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

Fehler und Beiträge

Einen Fehler gefunden oder möchten Sie ein Feature vorschlagen? Öffnen Sie ein Issue unter https://github.com/salehrifai42/qmetrymcp/issues. PRs sind willkommen.

Lizenz

MIT