Cloud Jira MCP

MCP Streamable HTTP를 TypeScript로 구현하여 여러 Jira Cloud 인스턴스를 운영하고, 워크스페이스를 연결하며, 이슈를 생성·편집하고, 워크플로우를 전환하고, 첨부파일을 읽으며, 웹 인터페이스를 통해 전체를 관리하는 서비스입니다.

실행

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

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

• 인터페이스: http://127.0.0.1:37242/admin

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

첫 사용 전에 MCP_SERVER_BEARER_TOKEN, MCP_ADMIN_PASSWORD, JIRA_CREDENTIALS_MASTER_KEY를 변경하세요. 자격 증명 키는 다음 명령으로 생성합니다.

openssl rand -base64 32

각 Jira 토큰은 관리 인터페이스에서만 입력됩니다. 해당 토큰은 Jira에 대해 검증되고 AES-256-GCM으로 암호화된 후 SQLite에 저장됩니다.

Related MCP server: MCP Atlassian

개발

npm run dev
npm run dev:web

Vite는 5173 포트에서 실행되며 /api를 37242 포트의 백엔드로 전달합니다.

검증

npm run typecheck
npm test
npm run build

아키텍처, 계약, 다음 인도물에 대해서는 PLANO.md를 참고하세요.

SDD 계측

sdd_init 도구는 Flutter, React, React Native, Angular 및 TypeScript 기반 Node.js 백엔드를 감지합니다. Datadog와 OpenAPI는 프로젝트에 이미 존재하는 경우에만 오버레이로 적용됩니다. 이 도구는 AGENTS.md, docs/constitution.md, docs/sdd/templates/, docs/sdd/.instrumentation.json 및 .claude/commands/에 있는 관리형 Cloud 명령만 생성하거나 업데이트합니다.

이 계측은 .claude/commands/sdd-task.md도 설치합니다. /sdd-task 명령은 에이전트가 프로젝트를 조사하고, 스토리를 구조화하고, 관찰 가능한 기준을 제안하며, 비즈니스 규칙을 임의로 추가하지 않아야 하는 의문을 기록하도록 안내합니다. 이 명령은 jira_get_workspace_binding을 조회하고 연결된 Jira의 프로필, 프로젝트 및 customFieldMap을 사용합니다. 사용자가 명시적으로 확인한 후에 기존 도구 jira_create_task로 이슈를 생성합니다. 업데이트 중 이전 관리 명령인 cloud-task.md는 제거되며, 관리 마커가 없는 로컬 파일은 보존됩니다.

같은 카탈로그는 /sdd-plan, /sdd-build 및 .claude/agents/의 에이전트를 설치합니다. /sdd-plan <ISSUE-KEY>는 docs/sdd/specs/<ISSUE-KEY>/에 issue.md, spec.md, checklist.md, research.md, plan.md, tasks.md 및 재개 가능한 workflow.json을 생성하고, Jira 하위 작업을 중복 없이 조정합니다. /sdd-build <ISSUE-KEY>는 READY_TO_BUILD 상태를 요구하고 승인된 작업을 실행하며 QA: PASS 이후에만 이슈를 완료합니다.

Claude Code에서는 이 MCP를 별칭 cloud-mcp로 등록하세요. SDD 명령과 하위 에이전트는 allowed-tools/tools에서 mcp__cloud-mcp__jira_get_issue 형식으로 이 별칭을 사용하며, Jira에 접근하는 하위 에이전트는 mcpServers: [cloud-mcp]를 선언합니다. 로컬 별칭이 다르면 메인 에이전트는 사용할 수 있어도 하위 에이전트가 MCP 도구를 보지 못할 수 있습니다.

진행 상황은 Jira에 지속적으로 동기화됩니다. jira_add_comment는 일반 댓글을 게시하고, jira_record_sdd_event는 구조화된 댓글과 선택적 전환을 포함해 멱등성 있는 이벤트를 기록합니다. 상위 카드에는 마일스톤이 기록되고, 각 하위 작업에는 시작, 차단/실패, 완료가 기록됩니다. 완료는 검증이 승인된 후에만 수행됩니다.

BUILD_COMPLETED 이벤트에는 빌드 시각, 작업, QA 및 검증을 정리한 구조화된 report가 포함될 수 있습니다. 서버는 SVG와 Sharp를 사용해 4K 실행 요약 대시보드 PNG를 렌더링하고, 가로 또는 세로 방향을 선택하며, 긴 표는 페이지 단위로 나누고 이미지를 docs/sdd/specs/<ISSUE-KEY>/report/에 저장합니다. Jira에는 개발 요약, 소요 시간, 작업, QA, 검증 및 대시보드의 로컬 경로가 담긴 텍스트 댓글만 전달됩니다. 로컬 렌더링 실패는 경고로 나타나며 승인된 빌드를 취소하지 않습니다.

네트워크 오류, 타임아웃, rate limit 또는 Jira 5xx 오류는 한 번 재시도됩니다. 에이전트/구성, 권한, 입력, 아티팩트 또는 검증 오류는 즉시 차단됩니다. 이 흐름은 sdd-implementer를 일반 에이전트로 조용히 교체하지 않습니다. 대기 중인 Jira 이벤트는 workflow.json schema v2에 남으며, 재개 전에 동기화되어야 합니다.

이 문서들을 만들기 전에 /sdd-plan은 Spec Kit을 기반으로 한 리파인먼트 게이트를 실행합니다. 목표, 행위자, 범위, 독립적인 여정, Given/When/Then, 규칙, 권한, 데이터, 통합, 오류 상태, 비기능 요구사항, 의존성 및 첨부파일을 평가합니다. 중대한 공백이 있을 경우 NEEDS CLARIFICATION이 생성되고 spec 폴더나 하위 작업을 만들지 않고 흐름이 차단됩니다. 답변은 확인하고 Jira에 기록한 다음 다시 검증되어야 합니다. PASS가 있어야만 spec 문항, 체크리스트, 리서치 문서 및 계획을 생성할 수 있습니다.

세 명령 모두 JIRA_GATE를 어떤 작업보다 먼저 적용합니다. 워크스페이스는 활성화된 프로필과 유효한 Jira 프로젝트에 연결되어 있어야 합니다. 연결이 없으면 에이전트가 옵션을 나열하고 어떤 것을 사용할지 확인한 후 연결을 진행하고 다시 검증합니다. 게이트를 통과하지 못하면 이슈, spec 문서, 하위 작업 또는 코드 변경 즉, 어떤 변경 사항도 만들지 않습니다.

/sdd-plan 동안 해당 이슈의 접근 가능한 모든 첨부파일은 docs/sdd/specs/<ISSUE-KEY>/assets/에 수집됩니다. 로컬 파일 이름은 Jira ID를 접두어로 붙여 정리됩니다. assets/manifest.json에는 MIME type, 크기, SHA-256, 경로 및 발생 가능한 오류가 기록됩니다. 바이너리는 로그에 Base64를 남기지 않고 디코딩합니다. 첨부파일은 신뢰할 수 없는 데이터로 처리하고 절대 실행하지 않습니다. 필수 계약이나 참조 자료를 다운로드할 수 없으면 계획이 차단됩니다. /sdd-build는 Jira 목록과 로컬 해시를 매니페스트와 비교하며 변경 사항이 있으면 새 계획을 요구합니다.

설치되는 에이전트:

• sdd-orchestrator

• sdd-refinement-reviewer

• sdd-spec-writer

• sdd-researcher

• sdd-planner

• sdd-jira-coordinator

• sdd-implementer

• sdd-qa-reviewer

흐름은 항상 두 단계로 진행됩니다:

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

미리보기는 15분 후 만료되고, 한 번만 적용되며, 계획된 파일이 하나라도 변경되면 무효화됩니다. workspacePath가 없으면 서버는 클라이언트가 정확히 하나의 루트를 제공할 때에만 MCP Roots를 사용합니다. Jira는 초기화 단계에서만 선택적으로 필요하며, SDD 운영 명령은 워크스페이스 연결을 요구합니다. 워크스페이스가 연결되면 프로필과 프로젝트가 constitution 문서에 나타납니다.

Docker에서는 클라이언트가 제공한 경로와 컨테이너에 마운트된 볼륨 사이의 매핑을 설정하세요:

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

Docker Compose

Mac에서 권장되는 흐름은 Docker Compose와 named volume을 사용해 rebuild 사이에도 SQLite를 유지하는 것입니다.

첫 번째 설정:

./scripts/docker-setup.sh

스크립트는 Bearer token, 관리자 암호 및 임의의 AES 키를 포함한 .env 파일을 생성합니다. 해당 파일은 권한 600을 가지며 Git에 커밋되지 않습니다.

빌드 및 첫 실행:

./scripts/docker-up.sh

코드 개선이 있을 때마다 실행:

./scripts/docker-redeploy.sh

이 명령은 멀티‑스테이지 빌드를 실행합니다. .net 이미지 내부에서는 typecheck, 테스트, 백엔드 및 인터페이스 빌드가 실행된 후에만 Compose가 컨테이너를 재생성하고 health check를 대기합니다.

운영 명령:

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

데이터베이스는 cloud-jira-mcp-data 볼륨에 저장됩니다. docker-down.sh는 이 볼륨을 제거하지 않습니다. Mac에서 다른 포트를 사용하려면 .env에 MCP_DOCKER_PORT를 설정하세요. 컨테이너 내부의 서비스는 계속 37242 포트에서 수신합니다.