Servidor MCP QTM4J

Un servidor MCP que expone la API REST de QMetry Test Management para Jira Cloud (QTM4J) como herramientas que Claude (o cualquier cliente compatible con MCP) puede invocar.

Características

Las herramientas cubren los flujos CRUD más comunes en las principales entidades de QTM4J:

Todas las herramientas validan las entradas con Zod, paginan los endpoints de lista mediante startAt / maxResults y reintentan automáticamente las respuestas con limitación de tasa (HTTP 429) con retroceso exponencial hasta 3 intentos.

Requisitos

• Node.js 18+ (utiliza fetch nativo)

• Una clave de API de QMetry (desde QMetry → API Keys)

Instalación

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

Configuración

El servidor se configura completamente a través de variables de entorno:

Ejecución

QTM4J_API_KEY=your-key npm start

El servidor utiliza MCP sobre stdio; normalmente no lo ejecutas directamente; tu cliente MCP (Claude Desktop, Claude Code, etc.) lo inicia.

Configuración del cliente MCP

Todos los clientes ejecutan el servidor directamente con node. Reemplaza /path/to/qmetrymcp con la ruta absoluta donde clonaste el repositorio.

Claude Desktop

Edita ~/Library/Application Support/Claude/claude_desktop_config.json en macOS (o el equivalente de la plataforma) y reinicia Claude Desktop:

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

Usa el comando 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

Esto escribe en tu configuración de usuario (~/.claude.json). Para limitarlo a un solo repositorio, coloca un archivo .mcp.json en la raíz del proyecto con la misma estructura mcpServers que el ejemplo de Claude Desktop anterior: Claude Code lo detectará automáticamente.

Verifica que esté registrado:

claude mcp list

En una sesión también puedes ejecutar /mcp para ver los servidores conectados y sus herramientas.

GitHub Copilot (VS Code)

El modo agente de Copilot admite MCP a través de un archivo .vscode/mcp.json en tu espacio de trabajo (o el bloque equivalente en el settings.json del usuario bajo github.copilot.chat.mcp.servers). Nota: el esquema de Copilot usa servers (no mcpServers) y espera un type explícito:

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

Después de guardar, abre el panel de Copilot Chat, cambia al modo Agent y las herramientas qtm4j aparecerán en el selector de herramientas. Si no quieres confirmar tu clave de API, usa la entrada secreta de 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"
      }
    }
  }
}

Prueba

Una vez conectado, pregúntale al asistente algo como:

Busca en el proyecto 10011 de QMetry los casos de prueba con estado "Approved" y muéstrame los primeros 5.

El cliente llamará a search_test_cases con { projectId: 10011, status: ["Approved"], maxResults: 5 } y mostrará la respuesta.

Ejemplo de llamadas a herramientas

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

Manejo de errores

• Las respuestas que no son 2xx devuelven un error de herramienta con el estado HTTP y el cuerpo de la API analizado.

• Los errores de red devuelven un mensaje de error descriptivo.

• Las respuestas 429 se reintentan automáticamente con retroceso exponencial (hasta 3 intentos en total).

Notas

• projectId debe ser el ID numérico del proyecto de Jira (p. ej., 10011), no la clave del proyecto (p. ej., "FS"). Puedes encontrarlo en la URL del proyecto de Jira: …?projectId=10011&projectKey=FS.

• Los endpoints de búsqueda usan POST /…/search: los filtros van en el cuerpo bajo filter, la paginación/ordenación en la cadena de consulta. Los manejadores de MCP envuelven esto automáticamente por ti.

• Los endpoints de "actualización" que devuelven 204 No Content se resuelven con una carga útil simple { message: "…" }.

• La especificación Swagger no documenta actualmente un endpoint de importación de resultados de automatización estilo framework (p. ej., ingesta de JUnit/TestNG/Cucumber); las herramientas de automatización aquí cubren los flujos de ejecución de reglas y vinculación de reglas expuestos en la especificación.