QTM4J MCP-Server

Ein MCP-Server, der die QMetry Test Management for Jira Cloud (QTM4J) REST-API als Tools bereitstellt, die von Claude (oder jedem anderen MCP-kompatiblen Client) aufgerufen werden können.

Funktionen

Die Tools decken die gängigsten CRUD-Abläufe für die wichtigsten QTM4J-Entitäten ab:

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

Anforderungen

• Node.js 18+ (verwendet natives fetch)

• Ein QMetry API-Schlüssel (unter QMetry → API Keys)

Installation

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

Konfiguration

Der Server wird vollständig über Umgebungsvariablen konfiguriert:

Ausführung

QTM4J_API_KEY=your-key npm start

Der Server kommuniziert über stdio mittels MCP – normalerweise starten Sie ihn nicht direkt; Ihr MCP-Client (Claude Desktop, Claude Code usw.) startet ihn automatisch.

MCP-Client-Konfiguration

Alle Clients starten den Server direkt mit node. Ersetzen Sie /path/to/qmetrymcp durch den absoluten Pfad zu dem Verzeichnis, in das Sie das Repository geklont haben.

Claude Desktop

Bearbeiten Sie ~/Library/Application Support/Claude/claude_desktop_config.json unter macOS (oder das entsprechende Äquivalent auf Ihrer Plattform) und starten Sie Claude Desktop neu:

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

Verwenden Sie den Befehl 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

Dies schreibt in Ihre benutzerspezifische Konfiguration (~/.claude.json). Um die Konfiguration auf ein einzelnes Repository zu beschränken, legen Sie eine .mcp.json im Projektstammverzeichnis mit derselben mcpServers-Struktur wie im obigen Claude Desktop-Beispiel ab – Claude Code erkennt diese automatisch.

Überprüfen Sie die Registrierung:

claude mcp list

In einer Sitzung können Sie auch /mcp ausführen, um verbundene Server und deren Tools anzuzeigen.

GitHub Copilot (VS Code)

Der Agent-Modus von Copilot unterstützt MCP über eine .vscode/mcp.json-Datei in Ihrem Arbeitsbereich (oder den entsprechenden Block in der Benutzer-settings.json unter github.copilot.chat.mcp.servers). Hinweis: Das Schema von Copilot verwendet servers (nicht mcpServers) und erwartet einen expliziten 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"
      }
    }
  }
}

Nach dem Speichern öffnen Sie das Copilot Chat-Panel, wechseln Sie in den Agent-Modus, und die qtm4j-Tools erscheinen in der Tool-Auswahl. Wenn Sie Ihren API-Schlüssel nicht committen möchten, verwenden Sie die geheime Eingabe von 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"
      }
    }
  }
}

Ausprobieren

Sobald die Verbindung hergestellt ist, fragen Sie den Assistenten beispielsweise:

Suche im QMetry-Projekt 10011 nach Testfällen mit dem Status "Approved" und zeige mir die ersten 5 an.

Der Client ruft search_test_cases mit { projectId: 10011, status: ["Approved"], maxResults: 5 } auf und gibt die Antwort aus.

Beispiel-Tool-Aufrufe

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

Fehlerbehandlung

• Nicht-2xx-Antworten geben einen Tool-Fehler mit dem HTTP-Status und dem geparsten API-Body zurück.

• Netzwerkfehler geben eine beschreibende Fehlermeldung zurück.

• 429-Antworten werden automatisch mit exponentiellem Back-off wiederholt (bis zu insgesamt 3 Versuche).

Hinweise

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

• Such-Endpunkte verwenden POST /…/search — Filter werden im Body unter filter übergeben, Paginierung/Sortierung in der Query-Zeichenfolge. Die MCP-Handler kapseln dies automatisch für Sie.

• "Update"-Endpunkte, die 204 No Content zurückgeben, werden mit einem einfachen { message: "…" }-Payload aufgelöst.

• Die Swagger-Spezifikation dokumentiert derzeit keinen Framework-artigen Endpunkt für den Import von Automatisierungsergebnissen (z. B. JUnit/TestNG/Cucumber-Ingestion); die hier enthaltenen Automatisierungstools decken die in der Spezifikation aufgeführten Abläufe für das Ausführen von Regeln und das Verknüpfen von Regeln ab.