MCP GitHub Project Manager

MCP GitHub Project Manager

AI コーディングエージェント向けのエージェント型タスク基盤です。 GitHub Projects v2 を、AI エージェントが自ら作業を割り当て、進捗を追跡し、互いにレビューし、コードをリリースする、完全自律型のプロジェクト管理プラットフォームに変える MCP サーバーです。すべて GitHub ネイティブのストレージを利用します。

ユースケース：AI エージェント（Claude Code、Codex、Cursor、Windsurf、Roo）をお使いの場合、タスクの基盤が必要です。これがその基盤です。

概要

この MCP サーバーは、Model Context Protocol を実装し、GitHub Projects v2 上に完全なエージェント型プロジェクト管理レイヤーを提供します。AI エージェントは登録し、自らタスクを割り当て、ハートビートを通じて連携し、成果物をレビューに提出し、トークン予算の範囲内で動作します。これらすべてを、169 個のアクションを公開する 20 個の複合ツールを通じて実行できます。人間のプロジェクトマネージャーは、AI を活用した PRD の生成、スプリント計画、課題のトリアージ、ロードマップの作成を利用できます。すべて GitHub ネイティブのストレージ（課題、プロジェクトのフィールド、コメント）に保存されるため、外部インフラは不要です。

このプロジェクトが必要な理由

AI コーディングエージェントは強力ですが、ステートレスです。次に何に取り組むべきかが分からず、他のエージェントと連携できず、永続的なタスク記憶もありません。この MCP サーバーは、GitHub Projects をエージェント型の運用レイヤーに変えることで、これらの問題を解決します。

問題	解決策
エージェントが何に取り組むべきか分からない	優先度／スキル／期限の戦略に基づくタスクのチェックアウト
複数のエージェントが互いの作業を妨げる	TOCTOU ガードとレビューワークフローを備えたアトミックな割り当て
エージェントの作業状況が見えない	ハートビート監視＋アクティビティダッシュボード＋成果物の追跡
エージェントがトークンを無制限に消費する	警告しきい値とハードストップを備えたエージェントごとのトークン予算
アイデアがタスクにならない	AI を活用した分解によるPRD→タスク→課題のパイプライン
スプリント計画が手作業	キャパシティ分析とリスク評価を備えたAI スプリント計画
課題がトリアージされずに積み上がる	自動ラベル付けと優先度の割り当てを行うAI を活用したトリアージ
外部データベースが必要	インフラ不要 — すべての状態を GitHub の課題、プロジェクト、コメントに保存

対応環境

エージェント／クライアント	統合方法
Claude Desktop	ネイティブ MCP クライアント — claude_desktop_config.json に追加
Claude Code	stdio トランスポート経由の MCP サーバー
Codex	MCP 互換 — ツールプロバイダーとして登録
Cursor	MCP サーバー統合
Windsurf	MCP サーバー統合
Roo Code	MCP サーバー統合
VS Code + Copilot	MCP 拡張機能経由
カスタムハーネス	任意の MCP 互換クライアント — examples/basic/agent-loop.ts を参照
Oh My Pi / OpenCode	stdio トランスポート対応のネイティブ MCP ハーネス

MCP v2 プロトコルのサポート

ツールに加え、このサーバーは MCP v2 のすべての機能を実装しています。

機能	数	例
ツール	20 個の複合ツール（169 個のアクション）	manage_project、ai_generate、agent_work
リソース	6	github://projects、github://agents、github://config
プロンプト	6	review-prd、triage-issue、analyze-sprint-risk
サンプリング	✓	API キーがない場合、AI 機能にクライアント側の LLM を使用

このツールの特長

• エージェントファーストの設計：APIを後付けした人間向けのPMツールではなく、AIエージェント向けのタスク基盤として構築されています
• 20個の複合ツール（169のアクション）：段階的に詳細を表示するAPIです。エージェントには20個のツールが表示され、discover_toolsから169のアクションを呼び出せます
• マルチエージェントスウォーム：エージェントは登録し、タスクをアトミックに取得し、ハートビートを送信し、互いをレビューし、プロジェクトを収束させます
• PRDから本番環境までのパイプライン：アイデア → PRD → タスク → GitHubイシュー → マイルストーン → スプリントを完全に自動化します
• 外部インフラ不要：すべての状態はGitHub（イシュー、プロジェクト、コメント）に保存されます。データベース、Redis、S3は不要です
• あらゆる機能にAIを活用：トリアージ、スプリント計画、ロードマップ生成、複雑さの分析、重複検出など、すべてをAIで強化します
• トークン予算の適用：エージェントごとの支出上限により、AIコストの予期しない増加を防ぎます
• 自己修復機能：クラッシュしたエージェントのタスクを自動で再取得し、古いハートビートを検出して、レジストリをクリーンアップします

目次

• 概要
• クイックスタート
• 主な機能
• インストール
• 設定
• 使い方
  • コマンドラインツールとして
  • TypeScriptでソースから実行する
  • Node.jsモジュールとして
  • MCPクライアントとの連携
  • AIアシスタントへのインストール
    • Claude
    • Roocode
    • Windsurf
    • VS Code
    • Cursor
    • Dockerを使用する
  • トラブルシューティング
• エージェントのオーケストレーション
• アーキテクチャ
• コントリビューション
• ライセンス
• 参考資料
• 現在のステータス

クイックスタート

NPMを使用する

# Install the package globally
npm install -g mcp-github-project-manager

# Set up your environment variables
export GITHUB_TOKEN="your_github_token"
export GITHUB_OWNER="your_github_username_or_organization"
export GITHUB_REPO="your_repository_name"

# Run the MCP server
mcp-github-project-manager

Dockerを使用する

# Build the Docker image
docker build -t mcp-github-project-manager .

# Run with environment variables
docker run -it \
  -e GITHUB_TOKEN=your_github_token \
  -e GITHUB_OWNER=your_github_username_or_organization \
  -e GITHUB_REPO=your_repository_name \
  mcp-github-project-manager

主な機能

🤖 AIを活用したタスク管理

• PRDの生成（generate_prd）：プロジェクトのアイデアを包括的な製品要件定義書に変換します
• インテリジェントなタスク分解（parse_prd）：AIを活用してPRDを実行可能な開発タスクに解析します
• スマートな機能追加（add_feature）：影響分析とタスク生成を自動で行い、新機能を追加します
• タスクの複雑さ分析（analyze_task_complexity）：タスクの複雑さ、工数見積もり、リスク評価をAIで詳細に分析します
• 次のタスクの推奨（get_next_task）：最適なタスクの優先順位付けをAIで推奨します
• タスクの展開（expand_task）：複雑なタスクを管理しやすいサブタスクに自動で分解します
• PRDの強化（enhance_prd）：AIを活用したギャップ分析と改善により、既存のPRDを改善します
• タスクの具体化（materialize_tasks）：生成されたタスクを実際のGitHubイシューに変換し、依存関係に基づくフェーズ順にマイルストーンとスプリントにグループ化します

🎯 強化されたタスクコンテキストの生成

• トレーサビリティベースのコンテキスト（デフォルト）：AIに依存せず、要件トレーサビリティから豊富なコンテキストを取得します
• AIで強化されたコンテキスト（任意）：AIを使用して、ビジネス、技術、実装に関する包括的なコンテキストを提供します
• 設定可能なコンテキストレベル：最小、標準、完全からコンテキストの詳細度を選択できます
• ビジネスコンテキスト：ビジネス目標、ユーザーへの影響、成功指標を抽出します
• 技術コンテキスト：技術的制約、アーキテクチャ上の決定、統合ポイントを分析します
• 実装ガイダンス：AIが段階的な実装の推奨事項を生成します
• コンテキストに応じた参照情報：関連するPRDのセクション、機能、技術仕様へのリンクを提供します
• 強化された受け入れ基準：検証方法を含む、詳細でテスト可能な基準を提供します
• 柔軟な機能縮退：AIキーがなくても問題なく動作し、トレーサビリティベースのコンテキストに切り替わります

🔗 完全な要件トレーサビリティ

• エンドツーエンドの追跡（create_traceability_matrix）：PRD のビジネス要件 → 機能 → ユースケース → タスクを完全に追跡します
• 双方向リンク：影響分析を含む完全な双方向トレーサビリティ
• ユースケース管理：アクター・ゴール・シナリオに基づく、専門的なユースケースの生成と追跡
• カバレッジ分析：ギャップの特定を含む包括的なカバレッジ指標
• 孤立タスクの検出：要件とのリンクがないタスクを特定します
• 変更影響分析：要件の変更と、すべてのレベルにわたるその影響を追跡します

📊 マルチプロバイダー AI サポート

• Anthropic Claude：複雑な推論に対応する主要な AI プロバイダー
• OpenAI GPT：フォールバックに対応する代替プロバイダー
• Google Gemini：追加の AI 機能
• Perplexity：調査および分析タスク
• 自動フォールバック：プロバイダー間をシームレスに切り替えます

🏗️ コアプロジェクト管理

• プロジェクト管理：GitHub Projects（v2）を作成および管理します
• Issue とマイルストーン：高度なフィルタリングに対応した完全な CRUD 操作
• スプリント計画：AI の支援を受けて開発スプリントを計画および管理します
• カスタムフィールドとビュー：さまざまなビュー（ボード、テーブル、タイムライン、ロードマップ）を作成します
• リソースのバージョン管理：インテリジェントなキャッシュと楽観的ロック

⚡ 高度な機能

• MCP 実装：Zod 検証による MCP 仕様への完全準拠
• GitHub 統合：インテリジェントなレート制限に対応した GraphQL API 統合
• リアルタイム同期：GitHub との双方向同期
• Webhook 統合：GitHub Webhook によるリアルタイム更新
• 進捗追跡：包括的な指標と進捗レポート
• イベントシステム：プロジェクトイベントの追跡と再生

🔧 GitHub API 対応範囲

• GitHub Actions：ワークフローの一覧表示、ディスパッチの実行、実行状況の監視、ログのダウンロード、実行のキャンセル
• リリース：自動生成ノート付きのリリースの作成、更新、削除
• ブランチ保護：ブランチ保護ルールの取得、更新、削除、ブランチの一覧表示
• Projects v2：フィールド、ビュー、アイテム、テンプレート、リンクの完全な管理
• Issue と PR：CRUD、コメント、サブ Issue、高度な検索、ドラフト Issue
• マイルストーンとスプリント：計画、指標、ベロシティ追跡

エージェントのオーケストレーション

• 複合ツール API：action ルーティングを備えた 20 個のツールで 169 個の個別アクションを置き換え、AI エージェントにとってよりシンプルになります
• エージェントレジストリ：自律型 AI エージェントの登録、一覧表示、登録解除
• タスクのチェックアウト：設定可能な選択戦略（優先度、経過時間、スキル、期限）でタスクを取得します
• ハートビート監視：古いエージェントの検出機能を備えた、定期的な稼働状況と進捗のレポート
• 作業成果物の追跡：コード変更、PR、テスト結果、レビュー成果物を提出します
• 作業成果物の検証：レビュー担当者が受け入れ基準に照らして作業を確認します。形式的な承認ではありません
• 予算の適用：エージェントごとのトークン予算と、警告しきい値およびハードリミット
• アクティビティダッシュボード：すべてのエージェントのステータス、タスク、予算消費状況をリアルタイムで表示します
• サブエージェント階層：親子関係にあるエージェントと、連鎖的な登録解除
• 実行時の検出：利用可能なアクションとスキーマを探索するための discover_tools メタツール
• PM の調整：プロジェクトマネージャーは特定のタスクを割り当て、スウォームの状況を監視し、作業負荷を再調整できます
• 障害復旧：PM は却下されたタスクをサブタスクに分解し、エージェントに再割り当てします
• スマートタスクルーティング：能力に適合し、予算を考慮した割り当て（smart_assign）
• プロジェクトの収束：1 回の呼び出しで自動承認、却下、または分解します（converge_project）
• レジストリのクリーンアップ：古いエージェントを自動的に削除します
• タスクの具現化：PRD タスクをマイルストーン、スプリント、プロジェクトへの割り当てとともに GitHub Issue に連携します

インストール

オプション 1：npm からインストール（推奨）

# Install the package globally
npm install -g mcp-github-project-manager

# Or install in your project
npm install mcp-github-project-manager

オプション 2：ソースからインストール

# Clone the repository
git clone https://github.com/kunwarVivek/mcp-github-project-manager.git
cd mcp-github-project-manager

# Install dependencies (npm or pnpm - use whichever you have)
pnpm install

# Build the project
pnpm run build

環境変数の設定

# Copy the example environment file
cp .env.example .env

# Edit .env with your GitHub token and details

設定

必須の環境変数

GitHub の設定

GITHUB_TOKEN=your_github_token
GITHUB_OWNER=repository_owner
GITHUB_REPO=repository_name

GitHub トークンには、次の権限が必要です。

• repo（リポジトリへのフルアクセス）
• project（プロジェクトへのアクセス）
• write:org（組織へのアクセス）

AI プロバイダーの設定

AI キーは任意です。設定しなくても、AI を使用しないツール（プロジェクト管理、イシュー、スプリント、エージェント）は問題なく動作します。AI 搭載機能（ai_generate、ai_analyze、ai_plan）を使用するには、少なくとも 1 つのキーが必要です。

# Global AI provider keys (set the ones you have)
ANTHROPIC_API_KEY=your_anthropic_api_key_here
OPENAI_API_KEY=your_openai_api_key_here
GOOGLE_API_KEY=your_google_api_key_here
PERPLEXITY_API_KEY=your_perplexity_api_key_here

# AI Model Configuration (no defaults — configure what you want to use)
AI_MAIN_MODEL=claude-sonnet-4-20250514    # general tasks
AI_PRD_MODEL=claude-opus-5                # PRD generation
AI_RESEARCH_MODEL=sonar-pro               # research
AI_FALLBACK_MODEL=gpt-4o-mini             # fallback

ロールごとのプロバイダー設定（任意）

各モデルロールは、それぞれ異なるプロバイダー、API キー、エンドポイントを使用できます。 OpenRouter、Together、Groq、Ollama、または OpenAI プロトコルのエンドポイントを使用する場合は、openai-compatible を指定してください。

# OpenRouter for cheap daily tasks
AI_MAIN_PROVIDER=openai-compatible
AI_MAIN_BASE_URL=https://openrouter.ai/api/v1
AI_MAIN_API_KEY=sk-or-v1-your-key
AI_MAIN_MODEL=deepseek/deepseek-chat

# Direct Anthropic for PRD generation
AI_PRD_PROVIDER=anthropic
AI_PRD_API_KEY=sk-ant-your-key
AI_PRD_MODEL=claude-opus-5

# Local Ollama as fallback
AI_FALLBACK_PROVIDER=openai-compatible
AI_FALLBACK_BASE_URL=http://localhost:11434/v1
AI_FALLBACK_API_KEY=ollama
AI_FALLBACK_MODEL=llama3.1

ロールごとの設定の詳細は、設定ガイドをご覧ください。

AI プロバイダーのセットアップ

Anthropic Claude

1. Anthropic Console に登録します
2. API キーを作成します
3. 環境に ANTHROPIC_API_KEY を設定します

OpenAI

1. OpenAI Platform に登録します
2. API キーを作成します
3. 環境に OPENAI_API_KEY を設定します

Google Gemini

1. Google AI Studio に登録します
2. API キーを作成します
3. 環境に GOOGLE_API_KEY を設定します

Perplexity

1. Perplexity API に登録します
2. API キーを作成します
3. 環境に PERPLEXITY_API_KEY を設定します

使用方法

コマンドラインツールとして

グローバルにインストールした場合：

# Start the MCP server using stdio transport
mcp-github-project-manager

# Start with environment variables
GITHUB_TOKEN=your_token mcp-github-project-manager

# Start with command line arguments
mcp-github-project-manager --token=your_token --owner=your_username --repo=your_repo

# Use a specific .env file
mcp-github-project-manager --env-file=.env.production

# Show verbose output
mcp-github-project-manager --verbose

# Display help information
mcp-github-project-manager --help

TypeScript でソースから実行する

開発中、またはソースから実行する場合：

# Use the npm dev script (watches for changes) — recommended
pnpm run dev

# Run directly with tsx
pnpm exec tsx src/index.ts

# Run with command line arguments
pnpm exec tsx src/index.ts --token=your_token --owner=your_username --repo=your_repo

# Display help information
pnpm exec tsx src/index.ts --help

コマンドラインオプション

オプション	短縮形	説明
--token <token>	-t	GitHub 個人アクセストークン
--owner <owner>	-o	GitHub リポジトリの所有者（ユーザー名または組織）
--repo <repo>	-r	GitHub リポジトリ名
--env-file <path>	-e	.env ファイルのパス（デフォルト：プロジェクトルートの .env）
--verbose	-v	詳細ログを有効にします
--help	-h	ヘルプ情報を表示します
--version		バージョン情報を表示します

コマンドライン引数は環境変数より優先されます。

Node.js モジュールとして

import { Server } from "mcp-github-project-manager";

// Create and start an MCP server instance
const server = new Server({
  transport: "stdio", // or "http" for HTTP server
  config: {
    githubToken: process.env.GITHUB_TOKEN,
    githubOwner: process.env.GITHUB_OWNER,
    githubRepo: process.env.GITHUB_REPO
  }
});

server.start();

MCP クライアントとの連携

// Example using an MCP client library
import { McpClient } from "@modelcontextprotocol/client";
import { spawn } from "child_process";

// Create a child process running the MCP server
const serverProcess = spawn("mcp-github-project-manager", [], {
  env: { ...process.env, GITHUB_TOKEN: "your_token" }
});

// Connect the MCP client to the server
const client = new McpClient({
  transport: {
    type: "process",
    process: serverProcess
  }
});

// Call MCP tools (compound API)
const result = await client.callTool("manage_project", {
  action: "create",
  title: "My Project",
  owner: "myorg"
});

その他の例については、ユーザーガイドとexamples/ ディレクトリをご覧ください。

複合ツール API の使用例

MCP サーバーは 20 個の複合ツール（169 個のアクション）を公開します。各ツールは、基盤となる操作に振り分ける action パラメーターを受け取ります。実行時に機能を確認するには、discover_tools を使用してください。

クイックスタートのワークフロー

// 1. Create a project
{"tool": "manage_project", "arguments": {"action": "create", "title": "My Project", "owner": "myorg"}}

// 2. Create an issue
{"tool": "manage_issues", "arguments": {"action": "create", "title": "First Issue", "body": "Description here"}}

// 3. Register an AI agent
{"tool": "agent_work", "arguments": {"action": "register", "name": "claude-eng-1", "role": "engineer"}}

// 4. Agent checks out a task
{"tool": "agent_work", "arguments": {"action": "checkout_task", "agentId": "agent-abc123", "strategy": "highest_priority"}}

// 5. Discover available tools at runtime
{"tool": "discover_tools", "arguments": {}}
{"tool": "discover_tools", "arguments": {"group": "manage_issues", "action": "create", "includeSchemas": true}}

AI を活用したプロジェクトのワークフロー

// 1. Generate PRD from project idea
{"tool": "ai_generate", "arguments": {"action": "generate_prd", "projectIdea": "AI-powered task management with real-time collaboration", "projectName": "TaskAI Pro", "complexity": "high"}}

// 2. Parse PRD into tasks with traceability
{"tool": "ai_generate", "arguments": {"action": "parse_prd", "prdContent": "<generated PRD>", "maxTasks": 30, "createTraceabilityMatrix": true}}

// 3. Get next task recommendations
{"tool": "ai_generate", "arguments": {"action": "get_next_task", "sprintCapacity": 40, "teamSkills": ["react", "node.js", "typescript"]}}

// 4. Analyze task complexity
{"tool": "ai_generate", "arguments": {"action": "analyze_complexity", "taskTitle": "Implement real-time collaboration", "includeRisks": true}}

// 5. Break down complex tasks
{"tool": "ai_generate", "arguments": {"action": "expand_task", "taskTitle": "Build analytics dashboard", "currentComplexity": 8, "targetComplexity": 3}}

機能追加のワークフロー

// Add new feature with complete lifecycle
{"tool": "ai_generate", "arguments": {"action": "add_feature", "featureIdea": "Advanced Analytics Dashboard", "description": "Real-time analytics with AI insights", "expandToTasks": true}}
// Automatically creates: business requirements, use cases, tasks with traceability, lifecycle tracking

// Create traceability matrix
{"tool": "ai_generate", "arguments": {"action": "create_traceability_matrix", "projectId": "task-ai-pro", "validateCompleteness": true}}

ツールの検出

// List all compound tools
{"tool": "discover_tools", "arguments": {}}

// Explore a specific tool's actions
{"tool": "discover_tools", "arguments": {"group": "ai_generate"}}

// Get full schema for a specific action
{"tool": "discover_tools", "arguments": {"group": "ai_generate", "action": "generate_prd", "includeSchemas": true}}

MCP_TOOL_GROUPS の設定

MCP クライアントに公開する複合ツールを制御します。

# Default: all tools exposed
MCP_TOOL_GROUPS=all

# Expose only project management tools
MCP_TOOL_GROUPS=core

# Add AI tools
MCP_TOOL_GROUPS=core,ai

この設定にかかわらず、discover_tools は常に利用できます。

コンテキスト生成レベル：

• 最小：基本的なトレーサビリティコンテキストのみ（最速）
• 標準：トレーサビリティと基本的なビジネスコンテキスト（デフォルト）
• 完全：実装ガイダンスを含む、AI で強化された包括的なコンテキスト

🧪 強化されたコンテキスト生成のテスト

強化されたコンテキスト生成機能には、包括的なテストカバレッジが含まれています。

作成されたテストファイル：

• src/__tests__/TaskContextGenerationService.test.ts - 中核となるコンテキスト生成サービスのテスト
• src/__tests__/TaskGenerationService.enhanced.test.ts - 強化されたタスク生成の統合テスト
• src/__tests__/ParsePRDTool.enhanced.test.ts - ツールレベルのコンテキスト生成テスト

テストカバレッジ：

• トレーサビリティに基づくコンテキスト生成（デフォルトの動作）
• AI で強化されたコンテキスト生成（AI が利用可能な場合）
• AI サービスが利用できない場合のフォールバック
• 設定の検証と環境変数の処理
• エラー処理と堅牢性のテスト
• 既存のタスク生成パイプラインとの統合テスト

コンテキスト生成テストの実行：

# Run all AI-related tests (includes context generation)
pnpm run test:ai

# Run specific context generation tests
pnpm test TaskContextGeneration
pnpm test enhanced

# Run all tests
pnpm test

🧪 包括的な E2E テストスイート

MCP GitHub Project Manager には、モック API 呼び出しと実際の API 呼び出しの両方を使用し、実際の MCP インターフェースを通じてすべての MCP ツールをテストする、包括的なエンドツーエンドテストスイートが含まれています。

テスト対象:

• ✅ 20 個の複合ツール（169 個のアクション） - プロジェクト、マイルストーン、Issue、スプリント、ラベルなどに対する CRUD 操作一式
• ✅ 9 個の AI 搭載アクション - PRD の生成、タスクの解析、複雑さの分析、機能管理、トレーサビリティ
• ✅ 複雑なワークフローの統合 - 複数ツールを使用するワークフローと実際のプロジェクト管理シナリオ
• ✅ 実際の API テスト - 実際の GitHub API と AI API を使用した任意のテスト
• ✅ スキーマ検証 - すべてのツールの引数を包括的に検証
• ✅ エラー処理 - エラー処理と復旧を適切にテスト

クイックスタート:

# Run comprehensive E2E tests (mocked APIs)
pnpm run test:e2e:tools

# Run with real APIs (requires credentials)
pnpm run test:e2e:tools:real

# Use the interactive test runner
pnpm run test:e2e:runner

# Run specific test categories
pnpm run test:e2e:tools:github     # GitHub tools only
pnpm run test:e2e:tools:ai         # AI tools only
pnpm run test:e2e:tools:workflows  # Integration workflows

テストランナーのオプション:

# Interactive test runner with options
node scripts/run-e2e-tests.js --help

# Examples:
node scripts/run-e2e-tests.js --real-api --github-only
node scripts/run-e2e-tests.js --build --verbose --timeout 120
node scripts/run-e2e-tests.js --ai-only --real-api

実際の API テスト用の環境設定:

GitHub API（GitHub ツールに必要）:

GITHUB_TOKEN=ghp_your_github_token
GITHUB_OWNER=your-github-username
GITHUB_REPO=your-test-repository

AI API（AI ツールに必要）:

# At least one AI API key required
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key
OPENAI_API_KEY=sk-your-openai-key
GOOGLE_API_KEY=your-google-ai-key
PERPLEXITY_API_KEY=pplx-your-perplexity-key

実際の API テストを有効にする:

E2E_REAL_API=true pnpm run test:e2e:tools:real

テスト機能:

• ツール登録の検証 - すべてのツールが正しいスキーマで適切に登録されていることを確認
• MCP プロトコルへの準拠 - すべてのツールが MCP 仕様に従っていることを確認
• レスポンス形式の検証 - ツールのレスポンスが想定される形式に一致することを検証
• ワークフロー統合テスト - 複雑な複数ツールのワークフローをテスト
• 認証情報の管理 - 認証情報が不足している場合に適切に処理
• パフォーマンスの監視 - ツールの実行パフォーマンスを追跡
• 包括的なエラーテスト - エラー処理と復旧を検証

ドキュメント:

• 📖 包括的な E2E テストガイド - 詳細なテストドキュメント
• 🔧 テスト設定 - E2E テスト用の Jest 設定
• 🛠️ テストユーティリティ - 再利用可能なテストユーティリティ

E2E テストスイートでは、すべての MCP ツールを個別に、また複雑なワークフロー内で正しく動作することを確認し、システム全体の信頼性と統合に対する確信を高めます。

対象となるテストシナリオ:

• ✅ デフォルトのトレーサビリティベースのコンテキスト（AI 不要）
• ✅ AI によって強化されたビジネスコンテキストの生成
• ✅ AI によって強化された技術コンテキストの生成
• ✅ 実装ガイダンスの生成
• ✅ コンテキストの統合と競合の解決
• ✅ エラー処理と適切な機能縮退
• ✅ 設定の検証とデフォルト値
• ✅ ツールレベルのパラメーター検証
• ✅ 既存のトレーサビリティシステムとの統合

AI アシスタントへのインストール

Claude へのインストール

Claude Desktop に MCP サーバーをインストールするには：

{
  "mcpServers": {
    "github-project-manager": {
      "command": "npx",
      "args": ["-y", "mcp-github-project-manager"],
      "env": {
        "GITHUB_TOKEN": "your_github_token",
        "GITHUB_OWNER": "your_username",
        "GITHUB_REPO": "your_repo",
        "AI_MAIN_PROVIDER": "openai-compatible",
        "AI_MAIN_BASE_URL": "https://openrouter.ai/api/v1",
        "AI_MAIN_API_KEY": "sk-or-v1-your-key",
        "AI_MAIN_MODEL": "deepseek/deepseek-chat"
      }
    }
  }
}

または、プロバイダーキーを直接指定する方法もあります（より簡単です）：

{
  "mcpServers": {
    "github-project-manager": {
      "command": "npx",
      "args": ["-y", "mcp-github-project-manager"],
      "env": {
        "GITHUB_TOKEN": "your_github_token",
        "GITHUB_OWNER": "your_username",
        "GITHUB_REPO": "your_repo",
        "ANTHROPIC_API_KEY": "your_anthropic_api_key"
      }
    }
  }
}

Claude Code CLI の場合は、次を実行します：

claude mcp add github-project-manager -- pnpm dlx mcp-github-project-manager

Roocode へのインストール

Roocode の設定に次を追加します：

{
  "mcpServers": {
    "github-project-manager": {
      "command": "npx",
      "args": ["-y", "mcp-github-project-manager"],
      "env": {
        "GITHUB_TOKEN": "your_github_token",
        "GITHUB_OWNER": "your_username",
        "GITHUB_REPO": "your_repo"
      }
    }
  }
}

Windsurf へのインストール

Windsurf の MCP 設定ファイルに次を追加します：

{
  "mcpServers": {
    "github-project-manager": {
      "command": "npx",
      "args": ["-y", "mcp-github-project-manager"],
      "env": {
        "GITHUB_TOKEN": "your_github_token",
        "GITHUB_OWNER": "your_username",
        "GITHUB_REPO": "your_repo"
      }
    }
  }
}

詳しくは Windsurf MCP ドキュメントをご覧ください。

VS Code へのインストール

VS Code の MCP 設定ファイルに次を追加します：

{
  "servers": {
    "github-project-manager": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-github-project-manager"],
      "env": {
        "GITHUB_TOKEN": "your_github_token",
        "GITHUB_OWNER": "your_username",
        "GITHUB_REPO": "your_repo"
      }
    }
  }
}

詳しくは VS Code MCP ドキュメントをご覧ください。

Cursor へのインストール

Cursor の MCP 設定ファイルに次を追加します：

{
  "mcpServers": {
    "github-project-manager": {
      "command": "npx",
      "args": ["-y", "mcp-github-project-manager"],
      "env": {
        "GITHUB_TOKEN": "your_github_token",
        "GITHUB_OWNER": "your_username",
        "GITHUB_REPO": "your_repo"
      }
    }
  }
}

詳しくは Cursor MCP ドキュメントをご覧ください。

Docker を使用する

MCP サーバーを Docker コンテナーで実行する場合は、次の手順に従います。

1. Docker イメージをビルドします：

docker build -t mcp-gh-project .

2. コンテナーを実行します：

docker run -d \
  -e GITHUB_TOKEN=your_github_token \
  -e GITHUB_OWNER=your_github_owner \
  -e GITHUB_REPO=your_repository_name \
  mcp-gh-project:latest

または、CLI 引数を指定して実行します：

docker run -d mcp-gh-project:latest \
  --github_token your_github_token \
  --github_owner your_owner \
  --github_repo your_repo

3. MCP クライアントを設定します：

{
  "mcpServers": {
    "github-project-manager": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "GITHUB_TOKEN", "-e", "GITHUB_OWNER", "-e", "GITHUB_REPO", "mcp-gh-project:latest"],
      "env": {
        "GITHUB_TOKEN": "your_token",
        "GITHUB_OWNER": "your_owner",
        "GITHUB_REPO": "your_repo"
      }
    }
  }
}

     "env": {
       "GITHUB_TOKEN": "your_github_token",
       "GITHUB_OWNER": "your_username",
       "GITHUB_REPO": "your_repo"
     }
   }
 }

}

### Troubleshooting

#### Common Issues

1. **Module Not Found Errors**

If you encounter module resolution issues, try using `bunx` instead of `npx`:

```json
{
  "mcpServers": {
    "github-project-manager": {
      "command": "bunx",
      "args": ["-y", "mcp-github-project-manager"]
    }
  }
}

2. Windows 固有の設定

   Windows では、コマンドの実行に cmd を使用する必要がある場合があります：

   {
     "mcpServers": {
       "github-project-manager": {
         "command": "cmd",
         "args": [
           "/c",
           "npx",
           "-y",
           "mcp-github-project-manager"
         ]
       }
     }
   }
   

3. 権限に関する問題

   権限に関する問題が発生した場合は、GitHub トークンに「Configuration」セクションに記載されている必要な権限が付与されていることを確認してください。

エージェントのオーケストレーション

エージェントのオーケストレーションレイヤーにより、自律型 AI エージェント（Claude Code、Codex、Cursor など）は、GitHub ネイティブのストレージを基盤として、タスクを自動で割り当て、進捗を報告し、成果物を提出し、トークン予算の範囲内で動作できます。

仕組み

エージェントは、2 つの複合ツール、agent_work（タスクのライフサイクル）と agent_manage（管理）を通じて、オーケストレーションレイヤーと連携します：

┌─────────────────────────────────────────────────────────────────────┐
│                    Agent Orchestration Layer                        │
│                                                                     │
│  ┌───────────┐  ┌──────────────┐  ┌─────────────┐  ┌────────────┐  │
│  │  Agent     │  │  Task        │  │  Work       │  │  Budget    │  │
│  │  Registry  │  │  Checkout    │  │  Products   │  │  Manager   │  │
│  └───────────┘  └──────────────┘  └─────────────┘  └────────────┘  │
│         │              │                │                │          │
│         ▼              ▼                ▼                ▼          │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │           GitHub-Native Storage (Issues + Projects)         │    │
│  │  • Agent registry → pinned issue (label: agent-registry)   │    │
│  │  • Task claims   → project custom fields                   │    │
│  │  • Work products → structured issue comments               │    │
│  │  • Budgets       → agent registry metadata                 │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

エージェントの複合ツール

ツール	アクション	目的
agent_work	register	役割、ランタイム、機能を指定して AI エージェントを登録します
agent_work	checkout_task	選択戦略を使用して、次に利用可能なタスクを取得します
agent_work	release_task	タスクをプールに戻します（ブロックされた場合、必要なスキルがない場合など）
agent_work	complete_task	概要を添えてタスクを完了としてマークします
agent_work	heartbeat	稼働状況、進捗率、ブランチ、ブロッカーを報告します
agent_work	check_work_status	提出した作業のレビュー／マージ状況を確認します
agent_work	get_task_context	タスクの詳細なコンテキストを取得します
agent_manage	list	登録済みエージェントを一覧表示し、役割またはステータスで絞り込みます
agent_manage	deregister	エージェントをレジストリから削除します
agent_manage	get_activity	すべてのエージェントのダッシュボードを表示します：タスク、進捗、ハートビート、予算
agent_manage	submit_work_product	ブランチ、PR、ファイル、テスト結果を添えてコード変更を提出します
agent_manage	get_budget	エージェントのトークン予算（使用済み、残り、警告）を確認します
agent_manage	set_budget	トークン予算、警告しきい値、ハードストップ、リセット期間を設定します

クイックスタート：自律型エージェントのループ

// 1. Register the agent
{"tool": "agent_work", "arguments": {"action": "register", "name": "claude-eng-1", "role": "engineer", "runtime": "claude-code", "capabilities": ["typescript", "react", "testing"]}}
// → { id: "agent-abc123", status: "idle", ... }

// 2. Check out a task
{"tool": "agent_work", "arguments": {"action": "checkout_task", "agentId": "agent-abc123", "strategy": "highest_priority"}}
// → { success: true, issueNumber: 42, issueTitle: "Add login form", branchSuggestion: "feat/42-add-login-form" }

// 3. Get full context
{"tool": "agent_work", "arguments": {"action": "get_task_context", "issueNumber": 42}}
// → { issue: {...}, milestone: {...}, acceptanceCriteria: [...], codingStandards: "..." }

// 4. Work on the task, sending heartbeats periodically
{"tool": "agent_work", "arguments": {"action": "heartbeat", "agentId": "agent-abc123", "status": "working", "taskId": "issue-42", "progress": 60, "progressSummary": "Tests passing, working on edge cases", "currentBranch": "feat/42-add-login-form"}}

// 5. Submit the work product
{"tool": "agent_manage", "arguments": {"action": "submit_work_product", "agentId": "agent-abc123", "taskId": "issue-42", "issueNumber": 42, "branch": "feat/42-add-login-form", "prNumber": 99, "summary": "Added login form with email/password validation"}}

// 6. Complete the task
{"tool": "agent_work", "arguments": {"action": "complete_task", "agentId": "agent-abc123", "taskId": "issue-42", "summary": "Implemented login form with validation and tests"}}

// 7. Repeat: checkout next task
{"tool": "agent_work", "arguments": {"action": "checkout_task", "agentId": "agent-abc123", "strategy": "highest_priority"}}

サブエージェント階層

エージェントは parentAgentId を使用して子エージェントを登録できます。これにより、マルチエージェントアーキテクチャを実現できます：

// Parent agent registers itself
{"tool": "agent_work", "arguments": {"action": "register", "name": "lead-agent", "role": "pm", "runtime": "claude-code"}}
// → { id: "agent-lead" }

// Parent spawns a sub-agent
{"tool": "agent_work", "arguments": {"action": "register", "name": "worker-1", "role": "engineer", "runtime": "claude-code", "parentAgentId": "agent-lead", "capabilities": ["typescript", "testing"]}}

// Deregistering the parent cascades to all children
{"tool": "agent_manage", "arguments": {"action": "deregister", "agentId": "agent-lead"}}
// → Removes lead-agent and worker-1

予算の適用

トークン予算により、AI のコストが際限なく膨らむのを防ぎます：

// Set a daily budget with 80% warning
{"tool": "agent_manage", "arguments": {"action": "set_budget", "agentId": "agent-abc123", "totalTokens": 500000, "warningThreshold": 0.8, "hardStop": true, "resetPeriod": "daily"}}

// Check budget status before expensive operations
{"tool": "agent_manage", "arguments": {"action": "get_budget", "agentId": "agent-abc123"}}
// → { usedTokens: 350000, remainingTokens: 150000, usagePercent: 70, isWarning: false, isExhausted: false }

GitHub ネイティブのデータモデル

オーケストレーションの状態はすべて GitHub リポジトリ内に保存されるため、外部データベースは必要ありません：

データ	ストレージ	詳細
エージェントレジストリ	固定された Issue	agent-registry ラベルが付いた Issue の JSON 本文
タスクの取得状況	Project のカスタムフィールド	agent_claimed_by、agent_claimed_at、agent_status、agent_work_branch、agent_pr_number
成果物	Issue のコメント	`` マーカーを含む構造化コメント
予算	エージェントのメタデータ	エージェントレコードごとに、エージェントレジストリ内に保存されます
ハートビート	エージェントのメタデータ	エージェントレコードの lastHeartbeat タイムスタンプ

設定

定数	デフォルト	説明
ハートビートのタイムアウト	30 minutes	この期間が経過すると、エージェントは応答なしと見なされます
デフォルトの予算	500,000 tokens	エージェントごとの初期トークン予算
レジストリのラベル	agent-registry	エージェントレジストリ用の GitHub Issue ラベル

パラメーターの詳細については、ツールリファレンスを参照してください。

アーキテクチャ

このサーバーは、明確に分離されたレイヤーを持つクリーンアーキテクチャの原則に従っています。

• ドメインレイヤー：コアエンティティ、リポジトリーインターフェース、Zod スキーマ
• インフラストラクチャレイヤー：GitHub API との連携と実装
• サービスレイヤー：ビジネスロジックの調整
• MCP レイヤー：ツール定義とリクエスト処理

貢献

貢献を歓迎します！ガイドラインについては、CONTRIBUTING.md をご覧ください。

1. リポジトリーをフォークします
2. フィーチャーブランチを作成します：git checkout -b feature/amazing-feature
3. 変更をコミットします：git commit -m 'Add some amazing feature'
4. ブランチにプッシュします：git push origin feature/amazing-feature
5. プルリクエストを作成します

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細は LICENSE ファイルをご覧ください。

参考資料

• Model Context Protocol
• GitHub Projects API

現在の状況

コア機能

機能	状況	備考
プロジェクト作成	✅ 完了	v2 プロジェクトを全面的にサポート
マイルストーン管理	✅ 完了	CRUD 操作を実装
スプリント計画	✅ 完了	メトリクスの追跡を含む
イシュー管理	✅ 完了	カスタムフィールドをサポート
リソースのバージョン管理	✅ 完了	楽観的ロックとスキーマ検証を使用
Webhook 連携	✅ 完了	リアルタイム更新；フェイルクローズ方式の HMAC 署名検証と SSE ストリーミング

AI を活用した機能

機能	状況	備考
PRD 生成	✅ 完了	包括的な PRD 作成を含む、複数プロバイダーの AI をサポート
タスク生成	✅ 完了	PRD を実行可能なタスクに解析する AI 機能
機能追加	✅ 完了	影響分析を伴うスマートな機能追加
タスクの複雑さ分析	✅ 完了	リスク評価を含む詳細な AI 分析
タスクの推奨	✅ 完了	次のタスクを AI が推奨
タスクの細分化	✅ 完了	複雑なタスクをサブタスクに分解
PRD の強化	✅ 完了	AI による PRD の改善とギャップ分析
要件のトレーサビリティ	✅ 完了	カバレッジ分析を含むエンドツーエンドのトレーサビリティマトリクス

要件のトレーサビリティ

機能	状況	備考
ビジネス要件の抽出	✅ 完了	PRD の目標と成功指標から抽出
ユースケースの生成	✅ 完了	代替案を含むアクター・目標・シナリオ構成
トレーサビリティリンク	✅ 完了	影響分析を伴う双方向リンク
カバレッジ分析	✅ 完了	ギャップの特定と孤立したタスクの検出
変更の追跡	✅ 完了	要件変更の影響分析
検証の追跡	✅ 完了	テストケースのマッピングと検証状況

MCP 実装

コンポーネント	状況	備考
ツール定義	✅ 完了	Zod 検証を備えたすべてのコアツールを実装
リソース管理	✅ 完了	バージョン管理を含む完全な CRUD 操作
セキュリティ	✅ 完了	トークン検証、フェイルクローズ方式の Webhook 署名、ファイルマウントされたシークレット（SECRETS_DIR）
エラー処理	✅ 完了	MCP 仕様に準拠
トランスポート	✅ 完了	Stdio と HTTP をサポート

詳細な実装状況については、.planning/STATUS.md をご覧ください。 | リソース管理 | ✅ 完了 | 楽観的ロックとリレーションシップ追跡を使用 | | レスポンス処理 | ✅ 完了 | 複数のコンテンツタイプに対応したリッチなコンテンツ形式 | | エラー処理 | ✅ 完了 | MCP エラーコードへの包括的なエラーマッピング | | 状態管理 | ✅ 完了 | 競合解決とレート制限に対応 |

最近の改善

• 依存関係と SDK の最新化（2026-07-15）：

  • Vercel AI SDK v7 と Zod v4 に移行しました（連動するアップグレードです。MCP SDK 1.29 は Zod 4 を受け入れます）
  • Octokit の型パッケージを @octokit/rest 22 に合わせました
  • Handlebars の重大な脆弱性と、すべての高深刻度の勧告に対処しました

• アーキテクチャと信頼性（2026-07-15）：

  • ProjectManagementService ファサードを分割しました（IssueService と RoadmapService を抽出し、自動化を ProjectAutomationService に委譲しました）
  • 循環依存を解消し、ヘルスチェックで実際の GitHub レート制限プローブを実行するようにしました
  • Webhook 署名検証をフェイルクローズ方式に変更し、ローテーションに対応したファイルマウント型シークレット（SECRETS_DIR）を導入しました
  • サイズ上限付きのキャッシュ削除（MAX_CACHE_ENTRIES）と、名前空間インデックスのクリーンアップに関する修正を実施しました

• リソースシステムの強化：

  • すべてのリソースタイプに Zod スキーマ検証を追加しました
  • リソース間の関係性追跡を実装しました
  • 一貫したリソースアクセスのため、ResourceFactory を一元化しました

• GitHub API 統合の改善：

  • 自動スロットリングを備えたインテリジェントなレート制限を追加しました
  • REST API と GraphQL API のページネーションを実装しました
  • エラータイプを明確化し、エラーハンドリングを強化しました

• 高度なツールシステム：

  • Zod 検証を備えたツール定義レジストリを作成しました
  • 標準化されたツール応答形式を実装しました
  • すべてのツールに例を用いたドキュメントを追加しました

• 豊富な応答形式：

  • 複数のコンテンツタイプ（JSON、Markdown、HTML、Text）に対応しました
  • 長時間実行される処理に進捗更新を実装しました
  • 大規模な結果セットのページネーションを追加しました

特定された機能上の不足

今後の開発に向けて優先順位を付けた残りの不足項目です（2026-07-15 更新）。実際のコードで検証された最新状況は、docs/remediation/GAP-TRACKER.md に記載されています。

1. 分散キャッシュ：

   • ResourceCache は永続化（CachePersistence）と、古い項目から削除するサイズ上限付きの削除（MAX_CACHE_ENTRIES）に対応しました。現在も単一インスタンスのみで、複数インスタンスのデプロイメント向けの分散／共有キャッシュはありません。

2. パフォーマンスの最適化：

   • 関連リソースに対するクエリのバッチ処理がありません
   • 頻繁にアクセスされるリソースのバックグラウンド更新がありません
   • 関連リソースのプリフェッチが不完全です

3. データの可視化とレポート（ロードマップのフェーズ 11。未実装）：

   • メトリクス用の組み込み可視化ジェネレーターがありません
   • レポート生成機能がありません
   • 時系列データ分析が限定的です

以前のスナップショットから解決済みの項目：リアルタイムの Webhook 統合と SSE ストリーミング、自動化ルール管理、キャッシュの永続化と削除、フェイルクローズ方式の Webhook 署名チェック。

ドキュメント

はじめに

• デプロイガイド - インストール、Docker、MCP クライアントのセットアップ
• 設定ガイド - すべての設定オプション
• トラブルシューティングガイド - よくある問題と解決策

リファレンス

• ツールリファレンス - 20 個の複合ツール（169 個のアクション）を記載
• アーキテクチャ - システム設計とパターン
• API リファレンス - サービスとインフラストラクチャの API

ガイド

• チュートリアル - 手順を追ったガイド
• ユーザーガイド - 詳細な使用手順
• テストガイド - テストスイートのドキュメント

開発

• コントリビューション - 開発ガイドライン
• MCP 統合 - MCP 固有の詳細

インタラクティブドキュメント

API をインタラクティブに確認するには、ブラウザーで API Explorer を開いてください。

開発

テスト

# Unit tests
pnpm test

# AI service/tool tests
pnpm run test:ai

# End-to-end tests
pnpm run test:e2e

# E2E MCP tool suite (mocked GitHub/AI)
pnpm run test:e2e:tools

コード品質

# Lint code
pnpm run lint

# Type check
pnpm exec tsc --noEmit

# Format code
pnpm run format

貢献

GitHub Project Manager MCP Server への貢献を歓迎します。詳しくは、貢献ガイドをご覧ください。

• 開発ワークフロー
• コード規約
• テストガイドライン
• ドキュメント作成ガイドライン

ライセンス

MIT