Cloud Jira MCP

MCP Streamable HTTP em TypeScript para operar múltiplas instâncias Jira Cloud, vincular workspaces, criar e editar issues, transicionar workflows, ler anexos e administrar tudo por uma interface web.

Ausführung

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

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

• Interface: http://127.0.0.1:37242/admin

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

Antes do primeiro uso, altere MCP_SERVER_BEARER_TOKEN, MCP_ADMIN_PASSWORD e JIRA_CREDENTIALS_MASTER_KEY. Gere a chave de credenciais com:

openssl rand -base64 32

O token de cada Jira é informado somente pela interface administrativa. Ele é validado contra o Jira e cifrado com AES-256-GCM antes de ser salvo no SQLite.

Related MCP server: MCP Atlassian

Desenvolvimento

npm run dev
npm run dev:web

O Vite roda na porta 5173 e encaminha /api para o backend na porta 37242.

Verificação

npm run typecheck
npm test
npm run build

Consulte PLANO.md para arquitetura, contratos e próximas entregas.

Instrumentações SDD

Die Tool sdd_init erkennt Flutter, React, React Native, Angular und Node.js-Backends mit TypeScript. Datadog und OpenAPI werden nur dann als Overlays angewendet, when they were already in the project. Ela cria ou atualiza apenas AGENTS.md, docs/constitution.md, docs/sdd/templates/, docs/sdd/.instrumentation.json e os comandos Cloud gerenciados em .claude/commands/.

A instrumentação también instala .claude/commands/sdd-task.md. O comando /sdd-task orienta o agente a inspecionar o projeto, estruturar a história, propor critérios observáveis e registrar dúvidas sem inventar regras de negócio. Ele consulta jira_get_workspace_binding e usa o perfil, o projeto e o customFieldMap do Jira conectado. Depois da confirmação explícita do usuário, cria a issue pela tool existente jira_create_task. O antigo comando gerenciado cloud-task.md é removido durante a atualização; arquivos locais sem os marcadores gerenciados são preservados.

O mesmo catálogo instala /sdd-plan, /sdd-build e os agentes em .claude/agents/. /sdd-plan <ISSUE-KEY> gera issue.md, spec.md, checklist.md, research.md, plan.md, tasks.md e um workflow.json retomável em docs/sdd/specs/<ISSUE-KEY>/, além de reconciliar subtarefas Jira sem duplicação. /sdd-build <ISSUE-KEY> exige o estado READY_TO_BUILD, executa as tarefas aprovadas e só conclui a issue depois de QA: PASS.

No Claude Code, registre este MCP com o alias cloud-mcp. Os comandos e subagentes SSDD usam esse alias nos allowed-tools/tools como mcp__cloud-mcp__jira_get_issue, e os subagentes que acessam Jira declaram mcpServers: [cloud-mcp]. Se o alias local for diferente, os subagentes podem não enxergar as tools MCP mesmo quando o agente principal consegue usá-las.

O progresso é sincronizado continuamente no Jira. jira_add_comment publica comentários gerais e jira_record_sdd_event registra eventos idempotentes com comentário estruturado e transição opcional. O card pai recebe marcos; cada subtask recebe início, bloqueio/falha e conclusão. A conclusão só ocorre após validações aprovadas.

No BUILD_COMPLETED, o evento pode incluir um report estruturado com os horários do build, tarefas, QA e validações. O servidor renderiza um dashboard executivo PNG em 4K usando SVG e Sharp, escolhe orientação horizontal ou vertical, pagina tabelas longas e salva a imagem em docs/sdd/specs/<ISSUE-KEY>/report/. O Jira recebe apenas um comentário textual com resumo do desenvolvimento, tempos, tarefas, QA, validações e o path local do dashboard. Falha de renderização local aparece como aviso e não desfaz um build aprovado.

Falhas de rede, timeout, rate limit ou Jira 5xx são repetidas uma vez. Erros de agente/configuração, permissão, input, artefato ou validação bloqueiam imediatamente. O fluxo nunca troca silenciosamente sdd-implementer por um agente genérico. Eventos Jira pendentes ficam no workflow.json schema v2 e precisam ser sincronizados antes da retomada.

Antes de criar esses documentos, /sdd-plan executa um refinement gate inspirado no Spec Kit. Ele avalia objetivo, ator, escopo, jornadas independentes, Given/When/Then, regras, permissões, dados, integrações, estados de erro, requisitos não funcionais, dependências e anexos. Gaps materiais geram NEEDS_CLARIFICATION e bloqueiam o fluxo sem criar a pasta da spec ou subtasks. As respostas precisam ser confirmadas, gravadas no Jira e avaliadas novamente. Somente PASS permite gerar spec, checklist, pesquisa e plano.

Os três comandos aplicam JIRA_GATE antes de qualquer trabalho: o workspace precisa estar vinculado a um perfil habilitado e projeto Jira válido. Quando a vinculação não exist , o agente lista as opções, pergunta qual usar, vincula e valida novamente. Sem sucesso no gate, não cria issue, documentos de spec, subtasks nem alterações de código.

Durante /sdd-plan, todos os anexos disponíveis da issue são ingeridos em docs/sdd/specs/<ISSUE-KEY>/assets/. The names are assume the Jira ID as prefix and are sanitized; assets/manifest.json records MIME type, sizes, SHA-256, path and potential failures. Binaries are decoded without logging the Base64. Attachments are treated as untrusted data and never executed. If a contract or required reference cannot be downloaded, planning is blocked. /sdd-build compares the Jira list and local hashes with the manifest and demands replanning when there are changes.

Agentes instalados:

• sdd-orchestrator

• sdd-refinement-reviewer

• sdd-spec-writer

• sdd-researcher

• sdd-planner

• sdd-jira-coordinator

• sdd-implementer

• sdd-qa-reviewer

O fluxo sempre possui duas etapas:

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

A prévia expira em 15 minutos, só pode ser aplicada uma vez e é invalidada se algum arquivo planejado mudar. Sem workspacePath, o servidor usa MCP Roots quando o cliente fornecer exatamente um root. O Jira é opcional apenas para a instrumentação; os comandos operacionais SDD exigem vinculação. Quando o workspace estiver vinculado, perfil e projeto aparecem na constituição.

No Docker, configure o mapeamento entre os caminhos informados pelo cliente e o volume montado no container:

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

Docker Compose

O fluxo recomendado no Mac usa Docker Compose e um volume nomeado para preservar o SQLite entre rebuilds.

Primeira configuração:

./scripts/docker-setup.sh

O script cria .env com Bearer token, senha administrativa e chave AES aleatórios. O arquivo fica com permissão 600 e não vai para o Git.

Build e primeira subida:

./scripts/docker-up.sh

Depois de qualquer melhoria no código, execute:

./scripts/docker-redeploy.sh

Esse comando roda o build multi-stage. Inside the image, typecheck, tests and builds backend and frontend are executed; only then does Compose rebuild the container and wait for the health check.

Comandos operacionais:

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

O banco fica no volume cloud-jira-mcp-data. docker-down.sh não remove esse volume. Para usar outra porta no Mac, configure MCP_DOCKER_PORT no .env; o serviço continua ouvindo na porta 37242 dentro do container.