Skip to main content
Glama
deenesjakoruzh
jersonmartinez

github-project-management

by jersonmartinez
OverviewSchemaRelated ServersScoreDiscussions
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: my_pm_tools

仕組み

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 installed

A
license - permissive license
Not graded
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

View all related MCP servers

Related MCP Connectors

  • GitHub

    Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.

  • ToolAPI

    Free public MCP for AI agents — 193 tools, 44 workflows. No API key.

  • LTD MCP

    Project management MCP for AI agents with safe task reads and writes.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jersonmartinez/mcp-github-projects'

If you have feedback or need assistance with the MCP directory API, please join our Discord server