MCP QA Client (TestRail + Jira)

Cliente MCP para Cursor que conecta con TestRail y Jira. Publicado como paquete npm para que los devs puedan instalarlo y configurarlo directamente en mcp.json sin pasos manuales con archivos .env. Compatible con Windows, macOS y Linux.

¿En qué carpeta lo hacen los devs?

Con un solo comando la config se escribe en el mcp.json global de Cursor; no hace falta copiar nada a mano (en cualquier SO).

| Paso | Dónde | |------|--------| | npm install @firstdue/mcp-qa-client | En la raíz del proyecto (o en cualquier carpeta). Al terminar, el postinstall escribe/actualiza el mcp.json global con la entrada jira_testrail. | | Sustituir en env usuario/key/token | Abre el mcp.json global: Windows %USERPROFILE%\.cursor\mcp.json · macOS / Linux ~/.cursor/mcp.json. Reemplaza PUT_YOUR_EMAIL, PUT_YOUR_TESTRAIL_API_KEY, PUT_YOUR_JIRA_API_TOKEN. | | Reiniciar Cursor | Reinicia Cursor para que cargue la config. |

Si prefieres config por proyecto, puedes usar npx mcp-qa-client-config, copiar la salida en raíz-del-proyecto/.cursor/mcp.json y editar ahí las credenciales.

Instalación como paquete npm

1. Instalar el paquete (config global automática)

Desde la raíz de tu proyecto (o cualquier carpeta):

npm install @firstdue/mcp-qa-client

Al terminar, el script postinstall escribe o actualiza el mcp.json global de Cursor con la entrada jira_testrail (mismo comportamiento en Windows, macOS y Linux). No hace falta ejecutar npx mcp-qa-client-config ni pegar nada a mano.

Solo tienes que abrir el mcp.json global (Windows: %USERPROFILE%\.cursor\mcp.json · macOS/Linux: ~/.cursor/mcp.json), sustituir en env los placeholders PUT_YOUR_EMAIL, PUT_YOUR_TESTRAIL_API_KEY y PUT_YOUR_JIRA_API_TOKEN por tus credenciales, y reiniciar Cursor.

Para usar el cliente sin instalar (Cursor puede usar npx):

npx -y @firstdue/mcp-qa-client

2. Config manual (opcional)

Si prefieres configurar por proyecto o no usar la config global, abre o crea:

• Global: ~/.cursor/mcp.json (ya lo rellena el postinstall; solo edita env)
• Por proyecto: raíz-del-proyecto/.cursor/mcp.json

Puedes usar como referencia este bloque (servidor y URLs ya definidos; solo cambia usuario y keys):

{
  "mcpServers": {
    "jira_testrail": {
      "command": "npx",
      "args": ["-y", "@firstdue/mcp-qa-client"],
      "env": {
        "MCP_TESTRAIL_SERVER_URL": "http://TU_SERVIDOR_MCP:3000/",
        "MCP_TESTRAIL_ENDPOINT": "/mcp",
        "MCP_TESTRAIL_TIMEOUT": "300000",
        "TESTRAIL_BASE_URL": "https://tu-instancia.testrail.io",
        "TESTRAIL_USERNAME": "[email protected]",
        "TESTRAIL_API_KEY": "tu_api_key_testrail",
        "JIRA_BASE_URL": "https://tu-dominio.atlassian.net",
        "JIRA_USERNAME": "[email protected]",
        "JIRA_API_TOKEN": "tu_token_api_jira",
        "DEFAULT_PROJECT_ID": "2",
        "DEFAULT_SUITE_ID": "1000",
        "DEFAULT_JIRA_PROJECT": "QA",
        "DEFAULT_JIRA_ISSUE_TYPE": "Bug"
      }
    }
  }
}

Guarda y reinicia Cursor.

3. Obtener el fragmento de configuración (opcional)

Si quieres el JSON para pegarlo en un mcp.json por proyecto:

npx mcp-qa-client-config

Sin tenerlo instalado: npx --package=@firstdue/mcp-qa-client mcp-qa-client-config. Desde la carpeta del paquete: npm run print-mcp-config.

Alternativa: usar archivo .env

Si prefieres no poner credenciales en mcp.json, puedes usar un .env en la raíz de tu proyecto:

1. Crea un .env en el directorio del proyecto desde el que abres Cursor.
2. Copia las variables desde .env.example (incluido en el paquete) y rellena los valores.
3. En mcp.json solo necesitas el comando (sin env):

{
  "mcpServers": {
    "jira_testrail": {
      "command": "npx",
      "args": ["-y", "@firstdue/mcp-qa-client"]
    }
  }
}

El cliente cargará primero .env del directorio actual (process.cwd()) y luego el del paquete.

Publicar el paquete en npm

Desde la carpeta MCP:

1. Iniciar sesión en npm (solo la primera vez):

   npm login

2. Publicar:

   npm publish

Si sale error 403 (Forbidden): npm exige autenticación de dos factores (2FA) o un token de acceso granular con "bypass 2FA" para publicar. Opciones:

• Activar 2FA en tu cuenta npm: npmjs.com → Account → Enable 2FA.
• O crear un token con permisos de publicación: npm website → Access Tokens → Generate New Token (Granular) y marcar "Bypass 2FA for publish".

El paquete usa el scope @firstdue. Para publicar, asegúrate de tener permiso en la org firstdue de npm (o crearla). Si publicas con otro scope, cambia "name" en package.json y usa el mismo nombre en los args de mcp.json.

Estructura del paquete

• client/mcp-client.js — Punto de entrada (bin)
• scripts/print-mcp-config.js — Genera el fragmento para mcp.json
• .env.example — Variables soportadas (sin valores reales)

Más información

• Utilidades y scripts de setup: client/utils/README.md
• Repositorio: mcp-testrail-qa-client