Servidor MCP QTM4J

Un servidor MCP con 42 herramientas para QMetry Test Management for Jira (QTM4J). Busca y gestiona casos de prueba, ciclos, ejecuciones, planes, carpetas, reglas de automatización y metadatos de proyectos desde Claude Desktop, Claude Code, VS Code Copilot, Cursor o cualquier cliente compatible con MCP.

Distribución:

• npm: qtm4j-mcp-server

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

• GitHub: salehrifai42/qmetrymcp

Inicio rápido (no requiere clonar)

Necesitas una clave de API de QMetry (QMetry → API Keys) y Node.js 18+.

Claude Desktop

Edita tu archivo de configuración y reinicia Claude:

• 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 (modo Agente de GitHub Copilot)

Crea .vscode/mcp.json en tu espacio de trabajo:

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

Cambia el chat de Copilot al modo Agente y las herramientas qtm4j_* aparecerán automáticamente.

Cursor

Añádelo a ~/.cursor/mcp.json (o <project>/.cursor/mcp.json para el nivel de proyecto):

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

Las configuraciones de ejemplo anteriores fijan el paquete a ^0.1 para que una futura versión con cambios incompatibles no te actualice automáticamente. Elimina el sufijo @^0.1 si prefieres ejecutar siempre la última versión.

Instalación global (inicio más rápido)

npx vuelve a resolver el paquete en cada lanzamiento, lo que añade unos segundos de latencia al inicio. Si utilizas el servidor con frecuencia, instálalo globalmente y apunta tu cliente directamente al binario:

npm install -g qtm4j-mcp-server

Luego, en la configuración de tu cliente, reemplaza el comando npx:

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

Compromiso: inicio instantáneo y funciona sin conexión, pero tendrás que ejecutar npm update -g qtm4j-mcp-server para obtener nuevas versiones.

Related MCP server: qtm4j-mcp-server

Configuración

💡 Establece QTM4J_REGION=AU si tu instancia de QMetry está en el clúster de Sídney.

Herramientas

Todas las herramientas tienen el prefijo qtm4j_ para evitar colisiones con otros servidores MCP.

Consulta docs/TOOLS.md para la referencia completa y docs/COOKBOOK.md para ejemplos de prompts que los colegas pueden pegar en cualquier cliente MCP.

Cada herramienta incluye anotaciones (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) para que los clientes puedan decidir si solicitar confirmación. Las herramientas de lectura aceptan un parámetro response_format (json por defecto, o markdown para una salida legible por humanos). Las respuestas grandes se truncan automáticamente a 25k caracteres con una sugerencia para acotar la consulta.

Todas las herramientas validan las entradas con Zod, paginan mediante startAt/maxResults y reintentan automáticamente las respuestas limitadas por tasa (HTTP 429) con retroceso exponencial (hasta 3 intentos).

Pruébalo

Una vez conectado, pregúntale a tu asistente algo como:

Busca en el proyecto de QMetry <tu ID de proyecto> los casos de prueba con estado "To Do" y muéstrame los 5 primeros.

El cliente llamará a qtm4j_search_test_cases y mostrará la respuesta.

Obtén todas las ejecuciones en el ciclo de prueba FS-TR-747 y marca como "Pass" las que no se hayan ejecutado.

Ejemplos de llamadas a herramientas

Reemplaza 10011 a continuación con tu ID numérico de proyecto de Jira. Encuéntralo en la URL del proyecto: …?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"
  }
}

Solución de problemas

• Las herramientas no aparecen en mi cliente. Reinicia el cliente después de editar la configuración. Comprueba claude mcp list (Claude Code) o el panel MCP de VS Code para ver el estado de la conexión. En la primera ejecución, npx -y qtm4j-mcp-server puede tardar unos segundos en descargar el paquete.

• 401 Unauthorized. Tu QTM4J_API_KEY no es válida o ha caducado. Genera una nueva en QMetry → API Keys.

• 404 en endpoints de ejecución o búsqueda. Muchos endpoints requieren el id numérico interno, no la clave legible como FS-TR-747. Llama primero a qtm4j_get_test_cycle para traducir la clave al id interno.

• Respuesta de carpeta vacía o demasiado grande. Pasa folderId a qtm4j_list_folders para limitar el alcance a un subárbol; los árboles de proyecto completos en proyectos grandes pueden exceder el límite de tamaño de respuesta.

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

Notas

• 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 herramientas envuelven esto por ti.

• Las respuestas 204 No Content se resuelven como { message: "…" }.

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

Desarrollo

Configuración local si deseas modificar el servidor:

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

Prueba los cambios con el Inspector MCP:

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

Errores y contribuciones

¿Encontraste un error o quieres sugerir una función? Abre un issue en https://github.com/salehrifai42/qmetrymcp/issues. Las PR son bienvenidas.

Licencia

MIT