Cloud Jira MCP

MCP Streamable HTTP en TypeScript para operar múltiples instancias de Jira Cloud, vincular workspaces, crear y editar issues, transicionar workflows, leer adjuntos y administrar todo por interfaz web.

Para ejecutar

cp .env.example .env
npm install
npm run build
npm start

• MCP: http://127.0.0.1:37242/mcp

• Interfaz: http://127.0.0.1:37242/admin

• Health: http://127.0.0.1:37242/health/ready

Antes del primer uso, cambie MCP_SERVER_BEARER_TOKEN, MCP_ADMIN_PASSWORD y JIRA_CREDENTIALS_MASTER_KEY. Genere la clave de credenciales con:

openssl rand -base64 32

El token de cada Jira se informa únicamente mediante la interfaz administrativa. Se valida contra el Jira y se cifra con AES-256-GCM antes de guardarse en SQLite.

Related MCP server: Jira MCP Server

Desarrollo

npm run dev
npm run dev:web

Vite ejecuta en el puerto 5173 y reenvía /api al backend en el puerto 37242.

Verificación

npm run typecheck
npm test
npm run build

Consulte PLANO.md para la arquitectura, los contratos y las próximas entregas.

Instrumentación SDD

La herramienta sdd_init detecta Flutter, React, React Native, Angular y backends Node.js con TypeScript. Datadog y OpenAPI se aplican como overlays solo cuando ya existen en el servidor. Crea/actualiza únicamente AGENTS.md, docs/constitution.md, docs/sdd/templates/, docs/sdd/.instrumentation.json y los comandos Cloud gestionados en .claude/commands/.

La instrumentación también instala .claude/commands/sdd-task.md. El comando /sdd-task orienta al agente para inspeccionar el proyecto, estructurar la historia, proponer criterios observables y registrar dudas sin inventar reglas de negocio. Consulta jira_get_workspace_binding y usa el perfil, el proyecto y el customFieldMap del Jira conectado. Después de la confirmación explícita del usuario, crea la issue mediante la herramienta existente jira_create_task. El antiguo comando gestionado cloud-task.md se elimina durante la actualización; los archivos locales sin los marcadores gestionados se preservan.

El mismo catálogo instala /sdd-plan, /sdd-build y los agentes en .claude/agents/. /sdd-plan <ISSUE-KEY> genera issue.md, spec.md, checklist.md, research.md, plan.md, tasks.md y un workflow.json reanudable en docs/sdd/specs/<ISSUE-KEY>/, además de reconciliar subtareas Jira sin duplicación. /sdd-build <ISSUE-KEY> exige el estado READY_TO_BUILD, ejecuta las tareas aprobadas y solo completa la issue después de QA: PASS.

En Claude Code, registre este MCP con el alias cloud-mcp. Los comandos y los subagentes SDD usan ese alias en allowed-tools/tools, como mcp__cloud-mcp__jira_get_issue, y los subagentes que acceden a Jira declaran mcpServers: [cloud-mcp]. Si el alias local es diferente, los subagentes pueden no ver las tools MCP aunque el agente principal sí pueda usarlas.

El progreso se sincroniza continuamente en Jira. jira_add_comment publica comentarios generales y jira_record_sdd_event registra eventos idempotentes con mentario estructurado y transición opcional. La tarjeta padre recibe hitos; cada subtarea recibe inicio, bloqueo/fallo y conclusión. La conclusión solo ocurre después de validaciones aprobadas.

En BUILD_COMPLETED, el evento puede incluir un report estructurado con los horarios del build, las tareas, el QA y las validaciones. El servidor renderiza un dashboard ejecutivo PNG en 4K usando niveles y Sharp, elige oversisión horizontal o vertical, pagina tablas largas y guarda la imagen en docs/sdd/specs/<ISSUE-KEY>/report/. Jira recibe únicamente un comentario textual con el resumen del desarrollo, tiempos, tareas, QA, validaciones y la ruta local del dashboard. Un fallo de renderización local aparece como aviso y no deshace un build aprobado.

Los fallos de red, timeout, rate limit o Jira error 5xx se reintentan una vez. Los errores de agente/configuración, de permiso, de entrada, de artefacto o de validación bloquean la ejecución. El flujo nunca reemplaza silenciosamente a sdd-implementer por un agente genérico. Los eventos Jira pendientes quedan en el workflow.json schema v2 y deben sincronizarse antes de la reanudación.

Antes de crear esos documentos, /sdd-plan ejecuta un refinement gate inspirado en Spec Kit. Evalúa objetivo, actor, alcance, jónadas independientes, Given/When/Then, reglas, permisos, datos, integraciones, estados de error, requisitos no funcionales, dependencias y archivos adjuntos. Las brechas materiales producen NEEDS CLARIFICATION y detienen el flujo sin crear la carpeta de spec ni subtareas. Las respuestas deben confirmarse, registrarse en Jira y evaluarse de nuevo. Solo PASS permite generar spec, checklist, investigación y plano.

Los tres comandos aplican JIRA_GATE antes de cualquier trabajo: el proyecto o workspace debe estar vinculado a un perfil habilitado y D de cada Jira válido. Cuando no existe el vínculo, el agente lista las opciones, pregunta cuál usar, vincula y valida de nuevo. Si el gate no pasa, no se asigna issue, no se crean documentos de spec, ni na minuciosidades ni alteraciones de código.

Durante /sdd-plan, todos los adjuntos accesibles de la issue se incorporan en docs/sdd/specs/<ISSUE-KEY>/assets/. Los nombres locales reciben el ID de Jira como prefijo y se sane; assets/manifest.json registra el tipo MIME, los tamaños, SHA-256, la ruta y los posibles fallos. Los binarios se decodifican sin regar una huella; se registra el hash en los registros. Los adjuntos se tratan como datos no confiables y nunca se ejecutan. Si un descarga obligatoria o una referencia obligada no se puede descargar, la planificación queda bloqueada. /sdd-build compara la lista de Jira y los hashes locales con el manifiesto y exige una nueva planificación si cambia algún elemento.

Agentes instalados:

• sdd-orchestrator

• sdd-refinement-reviewer

• sdd-spec-writer

• sdd-researcher

• sdd-planner

• sdd-jira-coordinator

• sdd-implementer

• sdd-qa-reviewer

El flujo siempre contiene dos fases:

sdd_init({ workspacePath: "/caminho/do/projeto", action: "preview" })
sdd_init({ action: "apply", previewId: "id-retornado-na-previa" })

La vista previa expira en 15 minutos, solo se puede aplicar una vez y se invalida si cambia cualquiera de los archivos planificados. Sin workspacePath, el servidor utiliza MCP Roots cuando el cliente aporta exactamente una root. Jira es opcional solo para la instrumentación; los comandos operativos de SDD requieren el vínculo. Cuando el workspace está vinculado, el perfil y el proyecto aparecen en la configuración.

En Docker, configure la correspondencia entre las rutas proporcionadas por el cliente y el volumen montado en el contenedor:

MCP_WORKSPACES_HOST_ROOT=/Volumes/External HD/Projetos
MCP_WORKSPACES_CONTAINER_ROOT=/workspaces
SDD_CATALOG_PATH=./resources/sdd

Docker Composable

El flujo recomendado en Mac usa Docker Compose y un volumen con nombre para preservar la base de datos SQLite entre rebuilds.

Primera configuración:

./scripts/docker-setup.sh

El script crea .env con Bearer Token, contraseña administrativa y clave AES aleatorios. El archivo queda con permiso 600 y no se sube al git.

Build y primera subida:

./scripts/docker-up.sh

Después de cualquier mejora en el código, ejecute:

./scripts/docker-redeploy.sh

Este comando ejecuta el build multi-stage. Dentro de la imagen se realizan typecheck, las pruebas y build del backend y del frontend; solo después del Compose se crea el contenedor y espera el healthtest del health.

Comandos operativos:

./scripts/docker-build.sh       # valida e gera a imagem
./scripts/docker-up.sh          # build + up + health check
./scripts/docker-redeploy.sh    # ciclo completo apos uma alteracao
./scripts/docker-status.sh      # estado e health do container
./scripts/docker-logs.sh        # acompanha logs
./scripts/docker-down.sh        # encerra sem apagar o banco

La base de datos está en el volumen cloud-jira-mcp-data. docker-down.sh no elimina ese volumen. Para se una conseguir otro puerto en Mac, ajuste MCP_DOCKER_PORT en .env; el servicio sigue escuchando en el puerto 37242 dentro del contenedor.