Skip to main content
Glama
deenesjakoruzh
jersonmartinez

github-project-management

by jersonmartinez
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

GitHub Project Management MCP Server

MCP CI

AIアシスタントがModel Context Protocolを介してGitHub Project V2ボードをプログラム的に管理できるようにするカスタムMCP（Model Context Protocol）サーバーです。Python 3.12とFastMCPで構築され、stdioトランスポートで通信し、スタンドアロンのDockerコンテナ内で実行されます。

場所

project/
├── mcp/                    ← This directory (root-level, independent of the app)
│   ├── Dockerfile
│   ├── requirements.txt
│   ├── server.py           # FastMCP entry point
│   ├── config.py
│   ├── auth.py
│   ├── capabilities.py     # Tool → permission mapping
│   ├── profiles.py         # Multi-target profile system
│   ├── tools/              # MCP tool definitions
│   ├── services/           # Business logic
│   ├── clients/            # GraphQL + gh CLI clients
│   ├── models/             # Pydantic models
│   ├── graphql/            # Query/mutation strings
│   ├── tests/              # Unit + contract tests
│   ├── scripts/            # Validation, preflight, secret scanning
│   │   ├── validate.sh     # ← Run before every push
│   │   ├── preflight.sh    # Environment prerequisites
│   │   ├── scan_secrets.sh # Token pattern detection
│   │   └── smoke_build.sh  # Minimal build verification
│   ├── profiles/           # Target config (.env files, no secrets)
│   ├── docs/               # Detailed documentation
│   ├── LICENSE             # MIT
│   ├── CONTRIBUTING.md
│   └── SECURITY.md

注記: このMCPサーバーは、独自のDockerfile、依存関係、ライフサイクルを持つスタンドアロンコンポーネントです。

Related MCP server: GitHub Projects MCP Server

仕組み

MCP Client → docker run --rm -i github-project-mcp:latest → stdin/stdout JSON-RPC → GitHub API

  1. MCPクライアントがツール（例: create_project_item）を呼び出します

  2. docker run --rm -i github-project-mcp:latest python server.py が実行されます

  3. サーバーは認証を検証し、stdinでコマンドを待ち受けます

  4. クライアントはstdin経由でJSON-RPCを送信し、stdoutで応答を受け取ります

  5. 終了時にコンテナは自動的に破棄されます（--rm）

Docker — ビルドと管理

イメージのビルド

# Desde la raíz del proyecto
docker build -t github-project-mcp:latest ./mcp

Docker Compose（ローカル開発）

MCPをローカルでセットアップして実行する最も簡単な方法:

# 1. Crear tu configuración local (una sola vez)
cp mcp/.env.example mcp/.env
# Editar mcp/.env con tu GITHUB_TOKEN y target (org/repo/project)

# 2. Construir y verificar
cd mcp/
make build
make verify

Makefileターゲット

すべてのターゲットはDocker内で実行されます — ホストの依存関係は不要です。

cd mcp/
make help         # Mostrar todos los targets disponibles
make build        # Construir imagen Docker
make verify       # Validar auth + scopes + config
make test         # Ejecutar unit tests
make validate     # CI completo (build + syntax + tests + tools + secrets)
make tools        # Contar herramientas registradas (>= 100)
make syntax       # Verificar sintaxis Python
make secrets      # Escanear credenciales en código
make shell        # Shell interactivo dentro del contenedor
make clean        # Eliminar imágenes

注記: ホストで make が利用できない場合、ターゲットはDockerで直接呼び出すことができます。例: docker run --rm --env-file .env github-project-mcp:latest python3 scripts/verify_setup.py

各コントリビューターはリポジトリをクローンし、自分の .env を作成するだけで、Docker以外は何もインストールせずにMCPが動作します。

イメージが存在することを確認

docker images | grep github-project-mcp

手動テスト（スモークテスト）

docker run --rm -i \
  -e GITHUB_TOKEN="<your_token>" \
  github-project-mcp:latest \
  python server.py

サーバーはstderrに github-project-management MCP server ready. Authentication validated successfully. を出力します。 その後、stdinからのJSON-RPCを待ち受けます。終了するにはCtrl+Cを押します。

変更後の再ビルド

docker build -t github-project-mcp:latest ./mcp --no-cache

管理スクリプト

./scripts/dev/start.sh スクリプトは、イメージを管理するための mcp 引数をサポートしています:

./scripts/dev/start.sh mcp build      # Construir/reconstruir la imagen
./scripts/dev/start.sh mcp test       # Ejecutar smoke test
./scripts/dev/start.sh mcp status     # Verificar si la imagen existe

注記: MCPは永続的なサービスではありません。up/down/restart は不要です。クライアントがツールを使用するたびにオンデマンドで起動されます。

IDE統合

MCPは、stdio上でMCPプロトコルをサポートする任意のクライアントと互換性があります。 設定はIDEによって異なります — 一般的なパターンは次のとおりです:

{
  "mcpServers": {
    "github-project-management": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "GITHUB_TOKEN",
        "--env-file", "mcp/.env",
        "github-project-mcp:latest",
        "python", "server.py"
      ]
    }
  }
}

IDE固有の設定については、docs/SETUP.md を参照してください。

登録済みツール（100）

コア操作

ツール

説明

discover_ids

プロジェクト/フィールドIDを検出

list_project_items

フィルター付きでアイテムを一覧表示

create_project_item

Issueを作成してプロジェクトに追加

update_project_item_fields

ステータス、優先度、期限を更新

set_estimate

ストーリーポイント見積もりを設定

archive_project_item

ボードからアイテムをアーカイブ

Issue管理

ツール

説明

close_issue

Issueをクローズ

reopen_issue

クローズしたIssueを再オープン

comment_issue

Issueにコメントを追加

edit_issue

タイトル、本文、ラベル、マイルストーン、担当者を編集

add_sub_issue

サブIssueとしてリンク

remove_sub_issue

サブIssueのリンクを解除

get_issue_detail

Issueの完全な詳細

search_issues

クエリで検索

ボード操作

ツール

説明

move_to_status

任意のステータス列に移動

move_to_done

Doneとしてマーク

move_to_trash

Trashに移動

bulk_update_items

複数アイテムを一括更新

bulk_close_issues

複数のIssueを一括クローズ

bulk_assign

複数のIssueを一括割り当て

計画とワークフロー

ツール

説明

sprint_planning

スプリント計画を生成

generate_release_notes

リリースノートを自動生成

complete_issue

完了ワークフロー全体を実行

daily_standup

スタンドアップレポートを生成

sprint_review

スプリントレビュー概要

triage_new_issues

提案を自動トリアージ

escalate_overdue

期限超過アイテムにフラグ

create_epic

親+子を作成

close_sprint

スプリントをクローズしてアイテムを移動

メタデータ

ツール

説明

create_milestone

GitHubマイルストーンを作成

close_milestone

マイルストーンをクローズ

list_milestones

マイルストーンを一覧表示

create_label

ラベルを作成

list_labels

ラベルを一覧表示

get_project_stats

ボード統計

get_sprint_summary

現在のスプリント指標

アーキテクチャ

Tool Layer (FastMCP tool definitions)
    ↓
Service Layer (business logic, orchestration)
    ↓
Client Layer (GraphQL + gh CLI + caching)
    ↓
GitHub APIs (GraphQL v4 + REST v3)

委任戦略

メソッド

使用タイミング

gh CLI

Issue CRUD、コメント、プロジェクトアイテム追加、クローズ

カスタムGraphQL

フィールド更新、アーカイブ、検出、サブIssue

環境変数

変数

必須

説明

GITHUB_TOKEN

はい

GitHub PAT（fine-grainedまたはclassic）

GH_PROJECT_ORG_NAME

はい

GitHubオーナー（組織またはユーザーログイン）

GH_PROJECT_REPO_NAME

はい

リポジトリ名

GH_PROJECT_PROJECT_NUMBER

はい

Project V2ボード番号（1〜100000）

トラブルシューティング

MCPが接続しない

# Verificar que la imagen existe
docker images | grep github-project-mcp

# Si no existe, construir
docker build -t github-project-mcp:latest ./mcp

# Verificar token
echo $GITHUB_TOKEN | head -c 20

MCPの再接続

MCPがIDEから切断された場合は、対応するMCPクライアントの再接続オプションを使用してください。

認証エラー

  • コンテナ環境で GITHUB_TOKEN が利用可能であることを確認

  • github_pat_*（fine-grained）トークンには権限が必要: Issues（RW）、Projects（RW）、Metadata（R）

  • クラシックトークンにはスコープが必要: repo、project、read:org

関連ドキュメント

ドキュメント

目的

docs/SETUP.md

トークン設定と権限

docs/USAGE.md

ツールの入出力例

docs/PARAMETERS.md

パラメータリファレンス

docs/TROUBLESHOOTING.md

一般的なエラー

ソースの場所と同期

このディレクトリ（mcp/）はMCPパッケージの正規のソースです。

リポジトリには同期されたコピーが次の場所にあります:

  • app/backend/app/mcp/github_project/ — Dockerビルド用にバックエンドに埋め込まれています

同期ワークフロー

  1. すべての変更はここ mcp/ で行います。

  2. 変更したファイルを埋め込みパスにコピーします:

    cp mcp/<file> app/backend/app/mcp/github_project/<file>

  3. 自動チェックで検証します:

    ./mcp/scripts/check_sync.sh

同期スクリプトは、共有されているすべての .py ファイルを比較します（バックエンドのコピーで意図的に異なる __init__.py、および Dockerfile や requirements.txt などのインフラ専用ファイルは除外）。CIはプッシュのたびにこのチェックを実行します — 差分があるとビルドが失敗します。

バックエンドのコピーで意図的に異なるファイル

ファイル

理由

__init__.py

バックエンド固有のインポート+同期ソースのドキュメント

README.md

ここを参照; コピーポリシーを文書化

バックエンドのテストスイートは埋め込みコピーを実行します。構文検証は両方のツリーをコンパイルする必要があります。

強化されたランタイム動作

すべての設定は GH_PROJECT_ プレフィックスを使用し、起動時に検証されます:

設定

デフォルト

範囲/動作

GH_PROJECT_TIMEOUT_SECONDS

10

1〜120秒

GH_PROJECT_RETRY_ATTEMPTS

1

0〜5; 読み取りのみ、変更操作は再試行しない

GH_PROJECT_RETRY_DELAY_SECONDS

2.0

0〜60秒、指数バックオフ

GH_PROJECT_CACHE_TTL_HOURS

24

1〜720時間

GH_PROJECT_CACHE_PATH

.github_project_cache.json

設定可能なローカルパス

GH_PROJECT_PAGE_SIZE

100

1〜100

GH_PROJECT_MAX_ITEMS

200

1〜1,000

GH_PROJECT_MAX_CLI_OUTPUT_CHARS

1,000,000

10,000〜10,000,000

メタデータキャッシュはアトミックに書き込まれ、オーナーのみの権限（0600）を使用し、未来のタイムスタンプを拒否し、組織またはプロジェクト番号が異なる場合は再利用されません。CLIおよびGraphQLの診断はトークンに似た値をマスクし、MCPクライアントに返す前にサイズ制限されます。

Dockerのみでの検証

ホストのPythonツールなしで検証を実行:

# Compile both source copies through a Python container
tar -C . -cf - mcp app/backend/app/mcp \
  | docker run --rm -i python:3.12-slim sh -c \
    'mkdir -p /tmp/factib && tar -xf - -C /tmp/factib && \
     python -m compileall -q /tmp/factib/mcp /tmp/factib/app/backend/app/mcp'

# Run the backend MCP tests using the existing backend image
tar -C . -cf - app/backend/app app/backend/tests/mcp \
  | docker run --rm -i -e PYTHONPATH=/tmp/factib/app/backend backend:latest sh -c \
    'mkdir -p /tmp/factib && tar -xf - -C /tmp/factib && cd /tmp/factib/app/backend && \
     pytest -q --confcutdir=/tmp/factib/app/backend/tests/mcp tests/mcp'

ローカル検証（プッシュ前）

PRを作成する前、または変更をプッシュする前に必ず実行してください。 これはCIパイプラインをローカルでミラーリングし、GitHub Actionsに到達する前に問題を検出します。

クイックスタート

# Full validation (builds image + runs all checks):
./mcp/scripts/validate.sh

# Quick mode (reuses cached image, skips rebuild):
./mcp/scripts/validate.sh --quick

# Auto-fix known issues (e.g., BOM characters):
./mcp/scripts/validate.sh --fix

チェック内容

ステップ

内容

CIステップと同じ

1. BOM

Pythonファイル内のUTF-8 BOMバイトを検出

N/A（構文エラーを防止）

2. ビルド

docker build -t github-project-mcp:validate ./mcp

"Build MCP image"

3. 構文

イメージ内のすべての.pyファイルで ast.parse を実行

"Syntax check"

4. テスト

tests/ 内のテストモジュールを実行

"Run unit tests"

5. ツール

登録済みツール数をカウント（100以上である必要あり）

"Verify tool count"

6. シークレット

追跡対象ファイル内のトークンパターンをスキャン

N/A（公開前）

利用可能なスクリプト

スクリプト

目的

使用タイミング

scripts/validate.sh

完全なCIミラー

すべてのプッシュ/PRの前

scripts/preflight.sh

前提条件チェック（Docker、トークン、設定）

初回セットアップまたは環境変更時

scripts/scan_secrets.sh

シークレットパターン検出

リポジトリ公開前

scripts/smoke_build.sh

最小ビルド+ツール数

クイック健全性チェック

scripts/run_contract_tests.sh

マルチターゲット契約スイート

構造変更後

一般的な問題と修正

問題

症状

修正

BOM文字

SyntaxError: invalid non-printable character U+FEFF

./mcp/scripts/validate.sh --fix

イメージが未ビルド

Dockerコマンドで「Image not found」

docker build -t github-project-mcp:latest ./mcp

トークン未設定

事前チェックで「No GitHub token found」

export GITHUB_TOKEN=ghp_...

ツール数が100未満

新しいツールがserver.pyに登録されていない

server.py内にmcp.tool()(your_tool)を追加

実装済みおよび計画中の作業を含む完全な200項目のレジスタは、docs/HARDENING_200.mdにあります。

拡張機能スイート: 追加ツール60個

このサーバーは合計100以上のツールを公開しています。元の運用ツール40個に加え、tools/capability_suite.pyからの60個の特化機能です。

グループ

目的

例

IssueとMarkdown品質

Issueの検証、正規化、要約、テンプレート化、バンドル、レビュー

validate_issue_markdown, build_issue_template, build_issue_review_checklist

コメントシステム

進捗、計画、ブロッカー、解決コメントの作成、一覧表示、検索、編集

comment_issue_progress, comment_issue_blocker, list_issue_comments

プロジェクトレポート

健全性、ステータス、優先度、担当者、期限、フィールドのレポート

project_health_report, project_due_date_risk, project_field_options_report

プロジェクト計画

Markdownのエクスポート/インポート、メタデータ同期計画、フィルタ一括計画

project_export_markdown, project_sync_issue_metadata, project_bulk_status_by_filter

戦略的自動化

スプリント計画、バックログ優先順位付け、リスク/依存関係レポート、ステークホルダー更新

plan_next_sprint, prioritize_backlog, generate_risk_register

ロードマップと意思決定

チェンジログ、リリースチェックリスト、ロードマップ、レトロスペクティブ、自動化の意思決定

generate_changelog_from_issues, build_roadmap_markdown, build_sprint_retrospective

広範囲にわたる変更を引き起こす可能性のあるツールは、デフォルトでdry_runプランを返します。直接コメント操作を行うツールは、呼び出しごとに1回の可視コメント操作を実行します。機能カタログはインポート時に60個の一意な追加を検証し、Docker検証では両方のソースコピーで100個の登録済みFastMCPツールを確認します。

配布

Dockerイメージ

MCPサーバーはスタンドアロンのDockerイメージとして配布されます。ローカルでビルドするには:

docker build -t github-project-mcp:latest ./mcp

CI/CDパイプライン

mcp-ci.yamlワークフローは、以下の場合に自動的に実行されます:

  • mcp/配下のファイルが変更されたmainへのプッシュ

  • mcp/パスに影響するプルリクエスト

パイプラインのステージ:

  1. ビルド — Dockerイメージのビルド検証

  2. 構文チェック — すべてのPythonファイルのAST解析

  3. ユニットテスト — pytestスイートの実行

  4. ツール数検証 — 登録済みツールが100以上であることを確認

バージョニング

このMCPサーバーはセマンティックバージョニングに従います。リリース履歴はCHANGELOG.mdを参照してください。

This server cannot be deployed

Pay for results, not tokens.Fund a bounty. Let AI agents compete and collaborate to solve your problems.agentbounties.appAd

Maintenance

ActivityActive
ResponsivenessResponsive

Resources

Related MCP Connectors

Related MCP Servers