Cloud Jira MCP

MCP Streamable HTTP in TypeScript to operate multiple Jira Cloud instances, bind workspaces, create and edit issues, transition workflows, read attachments, and manage everything through a web interface.

Running

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

Before first use, change MCP_SERVER_BEARER_TOKEN, MCP_ADMIN_PASSWORD, and JIRA_CREDENTIALS_MASTER_KEY. Generate the credentials key with:

openssl rand -base64 32

The token for each Jira is provided only through the admin interface. It is validated against Jira and encrypted with AES-256-GCM before being stored in SQLite.

Related MCP server: MCP Atlassian

Development

npm run dev
npm run dev:web

Vite runs on port 5173 and forwards /api to the backend on port 37242.

Verification

npm run typecheck
npm test
npm run build

See PLANO.md for architecture, contracts, and upcoming deliverables.

SDD Instrumentation

The tool sdd_init detects Flutter, React, React Native, Angular, and Node.js backends with TypeScript. Datadog and OpenAPI are applied as overlays only when they already exist in the project. It creates or updates only AGENTS.md, docs/constitution.md, docs/sdd/templates/, docs/sdd/.instrumentation.json, and the managed Cloud commands in .claude/commands/.

The instrumentation also installs .claude/commands/sdd-task.md. The /sdd-task command guides the agent to inspect the project, structure the story, propose observable criteria, and register doubts without inventing business rules. It queries jira_get_workspace_binding and uses the profile, project, and customFieldMap of the connected Jira. After explicit user confirmation, it creates the issue through the existing tool jira_create_task. The old managed command cloud-task.md is removed during the update; local files without the managed markers are preserved.

The same catalog installs /sdd-plan, /sdd-build, and the agents in .claude/agents/. /sdd-plan <ISSUE-KEY> generates issue.md, spec.md, checklist.md, research.md, plan.md, tasks.md, and a resumable workflow.json in docs/sdd/specs/<ISSUE-KEY>/, in addition to reconciling Jira subtasks without duplication. /sdd-build <ISSUE-KEY> requires the READY_TO_BUILD state, runs the approved tasks, and only finishes the issue after QA: PASS.

In Claude Code, register this MCP with the alias cloud-mcp. The SDD commands and subagents use this alias in allowed-tools/tools as mcp__cloud-mcp__jira_get_issue, and the subagents that access Jira declare mcpServers: [cloud-mcp]. If the local alias is different, subagents may not see the MCP tools even when the main agent can use them.

Progress is continuously synced to Jira. jira_add_comment publishes general comments, and jira_record_sdd_event records idempotent events with a structured comment and optional transition. The parent card receives milestones; each subtask receives start, bloc when it fails. Completion occurs only after validations are approved.

On BUILD_COMPLETED, the event may include a structured report with build timings, tasks, QA, and validations. The server renders an executive 4K PNG dashboard using SVG and Sharp, chooses horizontal or vertical orientation, paginates long tables, and saves the image to docs/sdd/specs/<ISSUE-KEY>/report/. Jira receives only a textual comment with a summary of the development, timings, tasks, QA, validations, and the local dashboard path. Local rendering failure appears as a warning and does not undo an approved build.

Network failures, timeouts, rate limits, or Jira 5xx errors are retried once. Agent/config, permission, input, artifact, or validation errors block immediately. The flow never silently swaps the sdd-implementer.

By waiting on pending Jira events, workflow.json at schema v2, it needs sync before it is resumed.

Before creating documents, /sdd-plan runs a refinement gate inspired by Spec Kit. It evaluates the objective, actor, scope, independent journeys, Given/When/Then, rules, permissions, data, integrations, error states, non-functional requirements, and attachments. Material gaps generate NEEDS CLARIFICATION and block the flow, or create the spec folder without subtasks. The responses must be confirmed, recorded in Jira, and evaluated again. Only PASS generates spec, checklist, research, and plan.

The three commands apply JIRA_GATE before any work: the workspace must be bound to an enabled profile and a valid Jira project. When the binding does not exist, the agent lists the options, asks which to use, binds, and validates again. If the gate does not pass, it does not create the issue, spec documents, subtasks, or code changes.

During /sdd-plan, all accessible attachments of the issue are ingested into docs/sdd/specs/<ISSUE-KEY>/assets/. The local files receive the Jira ID as a prefix and are stored; assets/manifest.json records MIME type, sizes, SHA-256, path, and any failures. Binaries are decoded without writing the Base64 to logs. Attachments are treated as untrusted data and never executed. If an attachment or referenced item cannot be downloaded, planning is blocked. /sd-build compares the Jira list and local hashes against the manifest and requires new staging when it changes.

Installed agents:

• sdd-orchestrator

• sdd-refinement-reviewer

• sdd-spec-writer

• sdd-researcher

• sdd-planner

• sdd-jira-coordinator

• sdd-implementer

• sdd-qa-reviewer

The flow always has two stages:

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

The preview expires in 15 minutes, can only be applied once, and is invalidated if any input file changes. Jira is optional only for the instrumentation; the operational SDD workflows require the binding. When the workspace is bound, profile, and project appear in the constitution.

In Docker, configure the mapping between the paths reported by the client and the volume mounted in the container:

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

Docker Compose

The recommended workflow on Mac uses Docker Compose and a named volume to preserve the SQLite between rebuilds.

First setup:

• ./scripts/docker-setup.sh

The script creates .env with a random bearer token, admin password, and AES key. The file is 600 and is not in Git.

Build and first start:

./scripts/docker-up.sh

After any code change, run:

./scripts/docker-redeploy.sh

This command runs the multi-stage build. Inside the image, typecheck, tests, and builds of the backend and frontend are executed; only then does Compose recreate the container and wait for the health check.

Operational commands:

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

The data is stored in the cloud-jira-mcp-data volume. docker-down.sh does not remove that volume. To use another port on Mac, set MCP_DOCKER_PORT in .env; the service still listens on port 37242 inside the container.