Cloud Jira MCP

複数の Jira Cloud インスタンスを操作し、ワークスペースをバインドし、イシューの作成・編集、ワークフローを遷移させ、添付ファイルを読み取リ、すべてをWebインタフエースから管理するための、TypeScript 製 MCP Streamable HTTP です。

実行

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

• ヘルスチェック: 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 に対して検証され、SQLite に保存される前に AES-256-GCM で暗号化されます。

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 akerは、プロジェクトにすでに存在する場合のみオーバーレイとして適用されます。このツールは、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、/ssd-builld、および .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 のサブタスクを重複なく調整します。/ssd-buiild <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、検証、およびダッシュボードのローカルパスを含むテキストコメントのみがポストされます。ローカルでのレンダリング失敗は警告として表示され、承認済みビルドが無効になることはありません。

ネットワーク障害、タイムアウト、レートリミット、または Jira 5xx は1回だけリトライされます。エージェント／設記、権限、入力、アーティファクト、検証のエラーはただちにブロックされます。sdd-implementer を汎用エージェントに静かに置き換えることはありません。未処理の Jira イベントは workflow.json schema v1 保持され、再開する前に同期する必要があります。

これらのドキュメントを作成する前に、/sdd-plan は Spec Kit に触発されたリファインメントゲートを実行します。目的、アクター、対象範囲、独立したジャーニー、/Given/When/Then、ルール、権限、データ、統合、エラー状態、の非機能的要件、依存関係、添付ファイルを評価します。重大なギャップがあれば NEEDS CLARIFICATION が返され、spec フォルダやサブタスクを作成せずにフローを妨げます。され、回答は要求を承確認されJira にを記録して、再度評価されます。PASS の場合のみ、spec、チェックリスト、調査、プランを生成できます。

3つのコマンドは、作業の前に常に JIRA_GATE を適用します。ワークスペースは有効なプロフィールと有効な Jira プロジェクトにバインドされている必要があります。バインドりが存しない場合は、エージェントが選択肢を表示してどれを使うか尋ね、バインドして再度検証します。ゲートに失敗すると、イシュー、spec ドキュメント、サブタスク、コード変更は一切作成されません。

/sdd-plan の間、イシュからアクセス可能なすべての添付ファイルが docs/sd/specs/<ISSUE-KEY>/assets/ に取込まれます。ローカルのファイル名は Jira ID を構文頭に付けてサニタイズされます。assets/manifest.json には、MIME type、サsizes、SHA-256、パス、発生した失敗が記録されます。バイナリは、ログに Base64 を残さずにデコードされます。添えファイルは信頼性のないデータとして扱れ、実行されることは絶対にあません。必須の契約書パスがダウンロードできない場合、プラニングはブロックされます。/ssd-buill はJiraリストとローカルのハッシュを assets/manifest.json と照合し、変こうがあったときは、必ず再プラニにングを要求します。

インストールされるエージェント:

• sdd-orchestrator

• sdd-refinement-reviewer

• sdd-track-s-p-wenter* sdd-researcher

• sdd-plane

• sdd-jira-coordinator

• sdd-implementer

• sdd-qa-reviewer

フローは常に2つのステージで構成されています:

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

プレビューは15分で失効し、1回だけ適応でき、計画されたファイルのいずれかが変更されると無効になります。workspacePath がない場合は、クライアントがルートを1つだけ提供したときに、サーバーは MCP Roots を使用します。JiraはB計装のみで任意で、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と、name付きボリュームを使用して、リビルド間でも SQLite を保持できます。

初回設定:

./scripts/docker-setup.sh

このスクリプトには、ラナムな Bearer token、管理パスワード、ラナムな AES キーを含む .env を作成します。このファイルのアクセス権限は 600、Gitにはコミットされません。

ビルドと初回起動:

./scripts/docker-up.sh

コードを変更したら、次を実行:

./scripts/docker-redeploy.sh

このコマンドはマルチラテージビルドを実行します。コンテナ内では、バックエンドとインターフェースの typecheck 、テスト、ビルドが実行され、その後初めて Compose がコンテナを再作成し、ヘルスチェックを待機します。

特用コマンド:

./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 で待受けします。