rtm-mcp

Un servidor MCP (Model Context Protocol) de código abierto para la Requirements and Test Management for Jira API REST v2. Expone Requisitos, Casos de Prueba, Planes de Prueba, Ejecuciones de Prueba, Ejecuciones de Casos de Prueba, Defectos, Estructura de Árbol y Automatización como herramientas MCP, de modo que cualquier cliente compatible con MCP (Claude Desktop, extensiones de IDE, agentes personalizados) pueda manejar RTM directamente.

Ejecútalo con NPX — sin instalación, sin clonar:

npx rtm-mcp

Enlaces

• 📦 paquete npm: https://www.npmjs.com/package/rtm-mcp

• 🐙 repositorio de GitHub: https://github.com/ngocdd/rtm-mcp

• 🐛 seguimiento de incidencias: https://github.com/ngocdd/rtm-mcp/issues

• 📚 documentación de la API de RTM: https://deviniti.com/support/addon/cloud/requirements-test-management/latest/rest-api/

Características

• 32 herramientas MCP que cubren CRUD, gestión de enlaces, adjuntos e importación de resultados de CI para cada recurso de RTM.

• Autenticación mediante token Bearer a través de RTM_API_TOKEN. Genera un token en Jira: Apps → Requirements and Test Management → ⋯ → Rest API authentication → Generate Token.

• Regiones US + EU — cambia mediante RTM_BASE_URL.

• Reintentos + tiempos de espera + jitter integrados en el cliente HTTP (maneja 429/5xx/errores de red).

• Errores tipados mapeados a mensajes de error MCP amigables — nunca filtra trazas de pila.

• Carga de adjuntos acepta cargas útiles en base64 (seguro para clientes MCP en sandbox).

• Registro solo en stderr — stdout permanece limpio para JSON-RPC.

Related MCP server: Jira QMetry MCP Server

Inicio rápido

1. Genera un token de API de RTM

1. Abre Jira.

2. Ve a Apps → Requirements and Test Management.

3. Haz clic en el menú de tres puntos (⋯) → Rest API authentication.

4. Haz clic en Generate Token, elige un usuario, añade una etiqueta, haz clic en Generate.

5. Copia el token inmediatamente — RTM nunca lo vuelve a mostrar.

2. Ejecuta el servidor

RTM_API_TOKEN=your-token-here npx rtm-mcp

El servidor habla MCP sobre stdio — apunta tu cliente MCP hacia él.

Configuración de Claude Desktop

Añade a claude_desktop_config.json:

US / Global (URL por defecto):

{
  "mcpServers": {
    "rtm": {
      "command": "npx",
      "args": ["-y", "rtm-mcp"],
      "env": {
        "RTM_API_TOKEN": "<your-token-here>",
        "RTM_BASE_URL": "https://rtm-us.deviniti.com/api"
      }
    }
  }
}

Región EU:

{
  "mcpServers": {
    "rtm": {
      "command": "npx",
      "args": ["-y", "rtm-mcp"],
      "env": {
        "RTM_API_TOKEN": "<your-token-here>",
        "RTM_BASE_URL": "https://rtm-eu-api.hexygen.com/api"
      }
    }
  }
}

Configuración de Claude Code CLI

Usa el comando claude mcp add para registrar el servidor con Claude Code.

Ámbito de usuario (recomendado — disponible en todos tus proyectos)

claude mcp add --scope user --transport stdio rtm \
  -e RTM_API_TOKEN=<your-token-here> \
  -e RTM_BASE_URL=https://rtm-us.deviniti.com/api \
  -- npx -y rtm-mcp

Región EU:

claude mcp add --scope user --transport stdio rtm \
  -e RTM_API_TOKEN=<your-token-here> \
  -e RTM_BASE_URL=https://rtm-eu-api.hexygen.com/api \
  -- npx -y rtm-mcp

--scope user escribe la entrada en ~/.claude.json para que cada proyecto de Claude Code en esta máquina pueda ver el servidor rtm.

Ámbito de proyecto (solo este proyecto)

claude mcp add --scope project --transport stdio rtm \
  -e RTM_API_TOKEN=<your-token-here> \
  -e RTM_BASE_URL=https://rtm-us.deviniti.com/api \
  -- npx -y rtm-mcp

Escribe en .mcp.json en el directorio actual (se confirma en git).

Verifica el registro

claude mcp list           # see all configured servers
claude mcp get rtm        # inspect the rtm entry

Elimina el servidor

claude mcp remove rtm

Configuración

Un RTM_API_TOKEN ausente o vacío aborta el inicio con una pista amigable.

Herramientas disponibles

Todas las herramientas devuelven contenido de texto MCP con JSON bien formateado. 32 herramientas en total, organizadas por recurso de RTM a continuación. Usa el comando de listado de herramientas del host MCP para enumerarlas en tiempo de ejecución.

Requisitos (REQUIREMENTS)

• rtm_get_requirement — obtener por requirementKey

• rtm_create_requirement — crear

• rtm_update_requirement — actualización parcial

• rtm_delete_requirement — eliminar permanentemente

RTM no tiene un endpoint de listado para requisitos — usa rtm_get_tree_structure para enumerarlos por proyecto.

Casos de Prueba (TEST_CASES)

• rtm_get_test_case — obtener por testCaseKey

• rtm_create_test_case — crear (pasa stepGroups para definir pasos)

• rtm_update_test_case — actualización parcial

• rtm_update_test_case_covered_requirements — gestionar enlaces de requisitos cubiertos. Pasa exactamente uno de set / add / remove. Llamada subyacente: PUT /api/v2/test-case/{key}/covered-requirements con cuerpo { coveredRequirements: { <op>: [...] } }.

rtm_delete_test_case no se expone intencionadamente — realiza las eliminaciones a través de la interfaz de Jira. RTM no tiene endpoint de listado — usa rtm_get_tree_structure.

Planes de Prueba (TEST_PLANS)

Refleja los 8 endpoints documentados en la API REST pública de RTM:

• rtm_get_test_plan — GET /api/test-plan/{testKey}

• rtm_create_test_plan — POST /api/test-plan

• rtm_update_test_plan — PUT /api/test-plan/{testKey}

• rtm_delete_test_plan — DELETE /api/test-plan/{testKey}

• rtm_update_test_plan_tc_order — PUT /api/test-plan/{testKey}/tc-order con cuerpo { order: [...] }

• rtm_create_test_plan_folder — POST /api/test-plan/{testKey}/tree/folders

• rtm_add_test_case_to_test_plan — POST /api/test-plan/{testKey}/testcases con cuerpo { testKey: "..." }

• rtm_remove_test_case_from_test_plan — DELETE /api/test-plan/{testKey}/testcases/{tcKey}

RTM no tiene endpoint de listado — usa rtm_get_tree_structure.

Ejecuciones de Prueba (TEST_EXECUTIONS)

• rtm_get_test_execution — obtener por testExecutionKey

• rtm_create_test_execution — crear ejecutando un Plan de Prueba (pasa testPlanTestKey)

• rtm_update_test_execution — actualización parcial (acepta status, summary, description, priority, owner, customFields)

• rtm_delete_test_execution — eliminar permanentemente

RTM no tiene endpoint de listado — usa rtm_get_tree_structure.

Ejecuciones de Casos de Prueba (TCE)

TCE = una fila en una Ejecución de Prueba que registra el resultado de ejecutar un Caso de Prueba.

• rtm_get_test_case_execution — obtener un TCE (resultado, ejecutor, comentario, defectos, pasos)

• rtm_update_test_case_execution — actualización parcial. Pasa result: "Fail" (o "Pass", "Blocked", …) para cambiar el estado de aprobado/fallido. Llamada subyacente: PUT /api/v2/test-case-execution/{key} con cuerpo { result: { name: "Fail" } }.

• rtm_link_defect_to_test_case_execution — enlazar un defecto a todo el TCE

• rtm_link_defect_to_test_case_execution_step — enlazar un defecto a un paso específico

• rtm_list_test_case_execution_attachments — listar adjuntos en el TCE

• rtm_upload_test_case_execution_attachment (entrada base64) — subir un archivo al TCE

• rtm_get_test_case_execution_attachment — obtener metadatos de un adjunto (devuelve URL de descarga)

• rtm_list_test_case_execution_step_attachments — listar adjuntos en un solo paso

• rtm_upload_test_case_execution_step_attachment (entrada base64) — subir un archivo a un paso específico

Los endpoints DELETE en TCE (unlink defect, delete attachment) no se exponen intencionadamente — realiza esas acciones a través de la interfaz de Jira o llama directamente a la API REST subyacente. Los endpoints existen; solo se eliminaron los envoltorios MCP de un solo disparo porque las operaciones destructivas deben estar detrás de un flujo de confirmación.

Defectos

• rtm_get_defect — obtener por defectKey

• rtm_create_defect — crear (pasa identifyingTestCases para enlazar a casos de prueba)

• rtm_update_defect — actualización parcial

• rtm_delete_defect — eliminar permanentemente

RTM no tiene endpoint de listado — usa rtm_get_tree_structure o jira_search a través del MCP de Atlassian.

Árbol

• rtm_get_tree_structure — obtener el árbol de carpetas de un proyecto. Requiere projectId numérico (resuélvelo desde projectKey mediante la API REST de Jira) y treeType ∈ REQUIREMENTS / TEST_CASES / TEST_PLANS / TEST_EXECUTIONS.

Automatización

• rtm_import_test_results — subir un archivo ZIP/TAR.GZ de informes JUnit / NUnit / Cucumber JSON; devuelve un taskId

• rtm_get_import_status — consultar un taskId anterior hasta que status salga de IMPORTING

Convenciones usadas en todos los recursos

Ejemplos

"Enumera los requisitos en el proyecto ACME."

> // No list endpoint — fetch the tree and walk it.
> rtm_get_tree_structure { projectId: 10000, treeType: "REQUIREMENTS" }

"Crea un Caso de Prueba llamado 'Login with valid credentials' bajo la carpeta /Smoke y enlázalo al requisito ACME-42."

> rtm_create_test_case { projectKey: "ACME", summary: "Login with valid credentials", folder: "/Smoke", stepGroups: [...] }
> rtm_update_test_case_covered_requirements { testCaseKey: "<new>", set: ["ACME-42"] }

"Añade 3 casos de prueba al plan KAN-52 sin reemplazar el conjunto existente."

> rtm_update_test_plan_included_test_cases {
    testPlanKey: "KAN-52",
    add: ["KAN-30", "KAN-31", "KAN-32"]
  }

"Enlaza el defecto KAN-100 a la ejecución de caso de prueba KAN-53-KAN-46 en el paso 8517443."

> rtm_link_defect_to_test_case_execution_step {
    testCaseExecutionKey: "KAN-53-KAN-46",
    stepId: "8517443",
    defectTestKey: "KAN-100"
  }

"Marca el TCE KAN-53-KAN-46 como Fallido y añade un comentario."

> rtm_update_test_case_execution {
    testCaseExecutionKey: "KAN-53-KAN-46",
    result: "Fail",
    comment: "Login button did not respond after 3 retries"
  }

"Adjunta una captura de pantalla al paso 2 del TCE KAN-53-KAN-46."

> rtm_upload_test_case_execution_step_attachment {
    testCaseExecutionKey: "KAN-53-KAN-46",
    stepId: "8517444",
    filename: "evidence.png",
    contentBase64: "<base64 bytes>",
    mimeType: "image/png"
  }

"Importa el JUnit XML de anoche."

> rtm_import_test_results {
    projectKey: "ACME",
    filename: "junit.zip",
    contentBase64: "<base64>",
    reportType: "JUNIT",
    jobUrl: "https://ci/job/123"
  }
> rtm_get_import_status { taskId: "<returned>" }

Solución de problemas

Desarrollo

git clone <repo>
cd rtm-mcp
npm install
npm run build         # compile to dist/
npm test              # unit tests
npm run dev           # run from src/ via tsx
npm run typecheck     # tsc --noEmit

Estructura del proyecto

src/
├── index.ts                  # entry point (shebang)
├── server.ts                 # McpServer wiring
├── config/                   # env validation + constants
├── client/
│   ├── http.ts               # fetch wrapper w/ retry + timeout
│   ├── errors.ts             # RTMError hierarchy
│   └── rtm-client.ts         # facade composing all resources
├── resources/                # one file per RTM resource
├── tools/                    # MCP tool registrations
├── schemas/                  # zod input schemas per tool group
└── utils/                    # logger, MCP response helpers
tests/
├── unit/                     # mocked fetch tests
└── integration/              # opt-in live tests (gated by RTM_LIVE=1)

Pruebas de integración en vivo

RTM_API_TOKEN=xxx \
RTM_BASE_URL=https://rtm-us.deviniti.com/api \
RTM_LIVE=1 \
RTM_TEST_PROJECT=ACME \
npm run test:integration

Use un proyecto Jira de prueba. La prueba de humo crea un Requisito, lo obtiene, lista los cercanos y limpia.

Publicación

npm login
npm version patch   # or minor / major
npm publish --access public

prepublishOnly ejecuta typecheck, test, build automáticamente.

Contribuciones

Este es un proyecto de código abierto: ¡los issues y PRs son bienvenidos!

1. Haz un fork del repositorio: https://github.com/ngocdd/rtm-mcp

2. Crea una rama de características: git checkout -b feat/my-tool

3. Instala y ejecuta las pruebas localmente:

   npm install
   npm run typecheck
   npm test

4. Añade pruebas para cualquier nuevo método de recurso o herramienta.

5. Abre un Pull Request contra main: https://github.com/ngocdd/rtm-mcp/compare

Añadir un nuevo endpoint de RTM

1. Añade un método tipado al módulo src/resources/<resource>.ts correspondiente.

2. Añade un esquema de entrada zod a src/schemas/<resource>.schema.ts.

3. Registra una herramienta MCP en src/tools/<resource>.ts.

4. Añade una prueba unitaria en tests/unit/.

5. Ejecuta npm run typecheck && npm test.

Reportar errores

Usa https://github.com/ngocdd/rtm-mcp/issues — incluye el tipo de recurso RTM, la ruta del endpoint, la respuesta esperada vs. real y el cuerpo de la solicitud (redactado).

Licencia

MIT — ver LICENSE.

Copyright (c) 2026 contribuyentes de rtm-mcp. Publicado bajo la Licencia MIT; eres libre de usar, modificar y distribuir este proyecto tanto en software de código abierto como propietario, siempre que se conserve el aviso de copyright.