PyGithub MCP Server

PyGithub MCP サーバー

PyGithub を介して GitHub API と連携するためのツールを提供する Model Context Protocol サーバーです。このサーバーを使用すると、AI アシスタントが issue、リポジトリ、プルリクエストの管理などの GitHub 操作を実行できます。

機能

• モジュール式のツールアーキテクチャ：

  • 有効化／無効化できる設定可能なツールグループ
  • ドメインごとの整理（issue、リポジトリなど）
  • ファイルまたは環境変数による柔軟な設定
  • モジュール設計による明確な関心事の分離
  • 一貫したパターンによる容易な拡張

• GitHub issue の包括的な管理：

  • issue の作成と更新
  • issue の詳細取得とリポジトリの issue の一覧表示
  • コメントの追加、一覧表示、更新、削除
  • issue のラベル管理
  • 担当者とマイルストーンの管理

• スマートなパラメーター処理：

  • オプションのパラメーターを動的に構築する kwargs
  • GitHub オブジェクトへの適切な型変換
  • すべての入力パラメーターの検証
  • 無効な入力に対する明確なエラーメッセージ

• 堅牢な実装：

  • PyGithub を介したオブジェクト指向の GitHub API 連携
  • GitHub クライアント管理の一元化
  • 適切なエラー処理とレート制限
  • MCP ツールによる明確な API 抽象化
  • 包括的なページネーション対応
  • デバッグ用の詳細なログ記録

ドキュメント

包括的なガイドは docs/guides ディレクトリにあります。

• error-handling.md：エラーの種類、処理パターン、ベストプラクティス
• security.md：認証、アクセス制御、コンテンツセキュリティ
• tool-reference.md：例を含む詳細なツールドキュメント

PyGithub MCP サーバーの使用方法について詳しくは、これらのガイドをご覧ください。

使用例

issue の操作

1. issue の作成

{
  "owner": "username",
  "repo": "repository",
  "title": "Issue Title",
  "body": "Issue description",
  "assignees": ["username1", "username2"],
  "labels": ["bug", "help wanted"],
  "milestone": 1
}

2. issue の詳細取得

{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1
}

3. issue の更新

{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1,
  "title": "Updated Title",
  "body": "Updated description",
  "state": "closed",
  "labels": ["bug", "wontfix"]
}

コメントの操作

1. コメントの追加

{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1,
  "body": "This is a comment"
}

2. コメントの一覧表示

{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1,
  "per_page": 10
}

3. コメントの更新

{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1,
  "comment_id": 123456789,
  "body": "Updated comment text"
}

ラベルの操作

1. ラベルの追加

{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1,
  "labels": ["enhancement", "help wanted"]
}

2. ラベルの削除

{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1,
  "label": "enhancement"
}

すべての操作では、オプションのパラメーターが適切に処理されます。

• 指定されたパラメーターのみを API 呼び出しに含めます
• プリミティブ型を GitHub オブジェクトに変換します（例：マイルストーン番号を Milestone オブジェクトに変換）
• 無効なパラメーターに対して明確なエラーメッセージを表示します
• 該当する場合はページネーションを自動的に処理します

インストール

1. 仮想環境を作成して有効化します。

uv venv
source .venv/bin/activate

2. 依存関係をインストールします。

uv pip install -e .

設定

基本設定

MCP 設定（例：claude_desktop_config.json または cline_mcp_settings.json）にサーバーを追加します。

{
  "mcpServers": {
    "github": {
      "command": "/path/to/repo/.venv/bin/python",
      "args": ["-m", "pygithub_mcp_server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

ツールグループの設定

このサーバーでは、設定によってツールグループを選択的に有効化または無効化できます。設定方法は次の 2 通りです。

1. 設定ファイル

JSON 設定ファイル（例：pygithub_mcp_config.json）を作成します。

{
  "tool_groups": {
    "issues": {"enabled": true},
    "repositories": {"enabled": true},
    "pull_requests": {"enabled": false},
    "discussions": {"enabled": false},
    "search": {"enabled": true}
  }
}

次に、このファイルを環境内で指定します。

export PYGITHUB_MCP_CONFIG=/path/to/pygithub_mcp_config.json

2. 環境変数

または、環境変数を使用してツールグループを設定します。

export PYGITHUB_ENABLE_ISSUES=true
export PYGITHUB_ENABLE_REPOSITORIES=true
export PYGITHUB_ENABLE_PULL_REQUESTS=false

デフォルトでは、issues ツールグループのみが有効です。設定オプションの詳細については、README.config.md をご覧ください。

開発

テスト

このプロジェクトには包括的なテストスイートが含まれています。

# Run all tests
pytest

# Run tests with coverage report
pytest --cov

# Run specific test file
pytest tests/test_operations/test_issues.py

# Run tests matching a pattern
pytest -k "test_create_issue"

注：現在、多くのテストが失敗しており、原因を調査中です。これは既知の問題で、現在積極的に対応しています。

MCP Inspector によるテスト

開発中に MCP Inspector を使用して MCP ツールをテストします。

source .venv/bin/activate  # Ensure venv is activated
npx @modelcontextprotocol/inspector -e GITHUB_PERSONAL_ACCESS_TOKEN=your-token-here uv run pygithub-mcp-server

MCP Inspector の Web UI では、次の操作を行えます。

• 利用可能なツールを試す
• 実際の GitHub リポジトリでテストする
• 成功ケースとエラーケースを検証する
• 動作するペイロードを記録する

プロジェクト構成

tests/
├── unit/                # Fast tests without external dependencies
│   ├── config/          # Configuration tests
│   ├── tools/           # Tool registration tests
│   └── ...              # Other unit tests
└── integration/         # Tests with real GitHub API
    ├── issues/          # Issue tools tests
    └── ...              # Other integration tests

src/
└── pygithub_mcp_server/
    ├── __init__.py
    ├── __main__.py
    ├── server.py        # Server factory (create_server)
    ├── version.py
    ├── config/          # Configuration system
    │   ├── __init__.py
    │   └── settings.py  # Configuration management
    ├── tools/           # Modular tool system
    │   ├── __init__.py  # Tool registration framework
    │   └── issues/      # Issue tools
    │       ├── __init__.py
    │       └── tools.py # Issue tool implementations
    ├── client/          # GitHub client functionality
    │   ├── __init__.py
    │   ├── client.py    # Core GitHub client
    │   └── rate_limit.py # Rate limit handling
    ├── converters/      # Data transformation
    │   ├── __init__.py
    │   ├── parameters.py # Parameter formatting
    │   ├── responses.py # Response formatting
    │   ├── common/      # Common converters
    │   ├── issues/      # Issue-related converters
    │   ├── repositories/ # Repository converters
    │   └── users/       # User-related converters
    ├── errors/          # Error handling
    │   ├── __init__.py
    │   └── exceptions.py # Custom exceptions
    ├── operations/      # GitHub operations
    │   ├── __init__.py
    │   └── issues.py
    ├── schemas/         # Data models
    │   ├── __init__.py
    │   ├── base.py
    │   ├── issues.py
    │   └── ...
    └── utils/           # General utilities
        ├── __init__.py
        └── environment.py # Environment utilities

トラブルシューティング

1. サーバーが起動しない場合：

   • MCP 設定で venv の Python パスを確認します
   • すべての要件が venv にインストールされていることを確認します
   • GITHUB_PERSONAL_ACCESS_TOKEN が設定され、有効であることを確認します

2. ビルドエラー：

   • uv build で --no-build-isolation フラグを使用します
   • Python 3.10+ が使用されていることを確認します
   • すべての依存関係がインストールされていることを確認します

3. GitHub API エラー：

   • トークンの権限と有効性を確認します
   • 詳細なエラートレースについては pygithub_mcp_server.log を確認します
   • レート制限を超過していないことを確認します

依存関係

• Python 3.10+
• MCP Python SDK
• Pydantic
• PyGithub
• UV パッケージマネージャー

ライセンス

MIT