Mcp Github Advanced Search

MCP Server for GitHub Advanced Search (G.A.S.)

DeepSeek との連携に最適化された、インテリジェントなフィルタリングとコンテンツ取得機能を備え、LLM が高度な GitHub コード検索を実行できる強力な Model Context Protocol（MCP）サーバーです。

🔍 概要

GitHub Advanced Search（G.A.S.）MCP サーバーは、標準 API の制限を超える高度な GitHub 検索機能を LLM に提供します。Playwright によるウェブ自動化を利用して、GitHub エコシステム全体からコードを深く検索し、パターンを分析して、コンテンツを取得できます。このバージョンでは DeepSeek モデルのサポートを強化し、用途に合わせた検索結果と構造化 JSON 出力を提供します。

デモ

vscode + cline + openrouter:deepseek/deepseek-r1-0528:free を使用してテスト済み

デモの YouTube リンク

例1

# step1: init gas
gas_entrypoint

# step2: feed model
gas_search_code
file_name: clinerules

# step3: make your wish
You are now have better knowledge of `clinerules`
please keep the current file format and deep level
enhance the `<file-path-to-clinerules>`

主な機能

• 🔍 高度な GitHub 検索：キーワード、ファイル名、複雑なフィルターで検索
• 📁 コンテンツ取得：ファイルの内容を自動的に取得して返します
• 🤖 LLM 連携：Claude、GPT、その他の MCP 対応 LLM とシームレスに連携
• 🔄 ページネーション対応：インテリジェントなページネーションで大量の検索結果を処理
• 🌐 ウェブ自動化：堅牢な GitHub 操作に Playwright を使用
• 📊 構造化された結果：リポジトリへのリンク、ファイルへのリンク、コンテンツを含む整理された JSON データを返します
• ⚡ 高性能：非同期処理と並行ファイルダウンロード
• 🔐 認証対応：GitHub ログインを使用してプライベートリポジトリを利用できます
• 🤖 DeepSeek 連携：DeepSeek モデルでの使用に最適化され、用途に合わせた検索結果と構造化 JSON 出力を提供します

🏗️ アーキテクチャ

graph TB
    subgraph "MCP Client (LLM)"
        A[Claude/GPT/Other LLM]
    end

    subgraph "MCP Server (G.A.S.)"
        B[MCP Server]
        C[Search Engine]
        D[Playwright Browser]
        E[Content Fetcher]
        F[Result Processor]
    end

    subgraph "GitHub"
        G[GitHub Search]
        H[Repository Files]
        I[Raw Content]
    end

    A -->|MCP Protocol| B
    B --> C
    C --> D
    D -->|Web Automation| G
    G -->|Search Results| D
    D --> E
    E -->|HTTP Requests| I
    I -->|File Content| E
    E --> F
    F -->|Structured Data| B
    B -->|JSON Response| A

    classDef client fill:#e1f5fe,stroke:#01579b,color:#01579b
    classDef server fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
    classDef github fill:#f3e5f5,stroke:#4a148c,color:#4a148c

    class A client
    class B,C,D,E,F server
    class G,H,I github

🔄 検索ワークフロー

sequenceDiagram
    participant LLM as LLM Client
    participant MCP as MCP Server
    participant PW as Playwright Browser
    participant GH as GitHub Search
    participant API as GitHub Raw API

    LLM->>MCP: gas_search_code(keyword, file_name)
    MCP->>PW: Launch browser session
    PW->>GH: Navigate to search URL
    GH-->>PW: Search results page
    PW->>PW: Extract repository & file links

    loop For each page
        PW->>GH: Navigate to page N
        GH-->>PW: Results for page N
        PW->>PW: Extract links from page
    end

    MCP->>API: Fetch file contents (async)
    API-->>MCP: Raw file content
    MCP->>MCP: Structure response data
    MCP-->>LLM: JSON with repositories, files & content

    alt More results available
        LLM->>MCP: get_remaining_result(start_id)
        MCP-->>LLM: Next batch of results
    end

🚀 クイックスタート

前提条件

• Python 3.10 以降
• Node.js（Playwright によるブラウザー自動化用）
• GitHub アカウント（最適な機能を利用するため推奨）

インストール

1. パッケージをインストールします：

   pip install mcp-server-git-gas
   

2. Playwright ブラウザーをインストールします：

   playwright install chromium
   

3. 💀未テスト MCP クライアントを設定します（例：claude desktop）：

   claude_desktop_config.json に追加します：

   # not tested !!!
   {
     "mcpServers": {
       "github-advanced-search": {
         "command": "mcp-server-git-gas",
         "args": []
       }
     }
   }
   

最初の検索

設定が完了したら、LLM を通じて GitHub の検索を開始できます：

Search GitHub for Python files containing "async def" functions

LLM は G.A.S. ツールを自動的に使用して検索を実行し、構造化された結果を返します。

📦 ソースからのインストール方法

ステップ1（ソースをクローン）

$ cd ~
$ git clone --depth=1 https://github.com/louiscklaw/mcp-github-advanced-search ~/mcp/mcp-git-gas

ステップ2（残りの依存関係と Playwright をインストール）

# Install Playwright browsers
$ playwright install chrome
$ playwright install --deps

ステップ3 Chrome ユーザー認証情報を登録

# this will create the user_data_dir for chromium
# go login google or any other service you want

$ cd ~/mcp/mcp-git-gas
$ ./seedChromeUserDataDir.sh

⚙️ 設定

MCP 拡張機能を使用した VS Code

{
  "mcp": {
    "servers": {
      "git-gas": {
        "autoApprove": [
          "get_remaining_result",
          "gas_readme",
          "gas_search_code"
        ],
        "disabled": false,
        "timeout": 300,
        "type": "stdio",
        "command": "uv",
        "args": [
          "--directory",
          "<USER_HOME_DIR>/mcp/mcp-git-gas/src/mcp_server_git_gas",
          "run",
          "mcp-server-git-gas"
        ]
      }
    }
  }
}

🛠️ 利用可能なツール

gas_entrypoint

GitHub Advanced Search サーバーを初期化し、情報を取得します。

パラメーター： なし

戻り値： ワークフロー図を含むサーバー情報と使用方法の説明。

graph TD
  a((start))
  d((end))
  b("search code with filter (gas_search_code)")
  c("return search result")
  c1("is the result finished ?")
  c2("use get_remaining_result to list remaining result")
  a --> b --> c --> c1 -- Yes --> d
  c1 -- No --> c2
  c2 --> c1

gas_search_code

高度なフィルターを使用して GitHub リポジトリを検索します。

パラメーター：

• keyword（文字列、任意）：検索キーワード（単語1つを推奨）
• file_name（文字列、任意）：検索する特定のファイル名（例：「.clinerules」、「README.md」）

戻り値： 次の情報を含む検索結果の配列：

[
  {
    "REPOSITORY_LINK": "https://github.com/owner/repo",
    "FILE_LINK": "https://github.com/owner/repo/blob/main/file.py",
    "RAW_UESR_CONTENT_LINK": "https://raw.githubusercontent.com/owner/repo/main/file.py",
    "FILE_CONTENT": "actual file content..."
  }
]

get_remaining_result

前回の検索結果から追加の結果を取得します（ページネーション）。

パラメーター：

• start_id（整数）：次の結果バッチの開始インデックス

戻り値： gas_search_code と同じ構造の次の検索結果バッチ。

💡 使用例

ステップ1

call `gas_entrypoint` to initialize yourself

ステップ2

Hi,

please use `gas_search_code` with below json

{
  "keyword": "mcp mermaid",
  "file_name": "README.md"
}

and understand the content returned, i will send you the task afterwards.

ステップ3

i am working on a python project,
please task a look to the source code of the project.

with the help from files in former results.
please help to and update the README file.

🔧 設定と環境

ブラウザーの設定

このサーバーでは、永続的なブラウザーコンテキストを使用する Playwright を利用し、以下を実現します。

• セッション管理
• 認証状態の保持
• パフォーマンスの向上

ブラウザーデータの保存先：~/mcp/mcp-git-gas/_user_data_dir

🏃‍♂️ 開発

ローカル開発環境のセットアップ

# Clone the repository
git clone <repository-url>
cd mcp-server-git-gas

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts/activate

# Install dependencies
pip install -e .

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

プロジェクト構成

src/mcp_server_git_gas/
├── __init__.py              # CLI entry point
├── server.py                # Main MCP server implementation
├── CONST.py                 # Configuration constants
├── fetch_data.py            # Async HTTP client
├── fetchFileContent.py      # File content retrieval
├── convertFileLinkToRaw...  # URL conversion utilities
├── url_util.py              # URL building helpers
└── git_dump_screen.py       # Debug utilities

主要コンポーネント

• MCP サーバー：Model Context Protocol インターフェースを実装します
• 検索エンジン：GitHub の検索ロジックとページネーションを処理します
• コンテンツ取得機能：ファイルの内容を非同期で取得します
• ブラウザー自動化：Playwright ベースで GitHub を操作します

MCP Inspector を使ったテスト

# Test the server with MCP inspector
npx @modelcontextprotocol/inspector uvx mcp-server-git-gas

Docker での開発

# Build development image
docker build -t mcp/git-gas:dev .

# Run with volume mount for development
docker run --rm -i \
  -v $(pwd):/app \
  mcp/git-gas:dev

🔍 仕組み

1. 検索の開始：LLM が検索パラメーターを指定して gas_search_code を呼び出します
2. クエリの構築：サーバーがフィルターを含む GitHub 検索 URL を構築します
3. ウェブの自動操作：Playwright が GitHub の検索ページに移動します
4. 結果の抽出：JavaScript の実行によってリポジトリとファイルのリンクを抽出します
5. コンテンツの取得：並列 HTTP リクエストでファイルの内容を取得します
6. レスポンスの整形：LLM が利用できるよう、結果を JSON として構造化します

🐛 トラブルシューティング

よくある問題

1. 「Not logged in」エラー

   • 解決策：seedChromeUserDataDir.sh を実行してブラウザーを起動し、ログインします

2. 結果が見つからない

   • 検索の keywords に誤字がないか確認します
   • より広い検索条件を試します
   • GitHub にアクセスできることを確認します

3. ブラウザーの起動に失敗する

   • 実行します：playwright install chromium
   • Playwright のシステム要件を確認します

4. レート制限

   • GitHub によってリクエストがレート制限される場合があります
   • サーバーには遅延と再試行のロジックが含まれています
   • より高い制限を利用するには、認証済みセッションの使用を検討してください

デバッグモード

デバッグ用スクリーンショットの保存先：~/mcp_github_advanced_search/debug.png

📊 パフォーマンス

• 検索速度：検索ページあたり約 2～5 秒
• 同時リクエスト：最大 10 件のファイルを並列ダウンロード
• 結果の上限：検索あたり 20 件（設定可能）
• ページネーション：最大 2 ページ（100 件以上の結果）に対応

🚨 重要な注意事項

• GitHub 認証：最適な結果を得るには、ブラウザーで GitHub にログインしてください
• レート制限：GitHub の利用ポリシーを遵守します
• ブラウザーの要件：Chromium ブラウザーが必要です（Playwright 経由でインストール）
• ネットワークの要件：GitHub にアクセスするにはインターネット接続が必要です

🤝 コントリビューション

コントリビューションを歓迎します！詳細については、コントリビューションガイドラインをご覧ください。

開発ワークフロー

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更を加えます
4. 新しい機能のテストを追加します
5. テストスイートを実行します
6. プルリクエストを送信します

📄 ライセンス

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

🙏 謝辞

• Anthropic による Model Context Protocol を基盤に構築されています
• ブラウザー自動化に Playwright を使用しています
• LLM のワークフローで高度な GitHub 検索機能が必要とされていることから着想を得ています
• フィードバックやコントリビューションを寄せてくださった MCP コミュニティに感謝します

🔗 関連プロジェクト

• Model Context Protocol
• Anthropic MCP Servers
• Playwright
• MCP Mermaid Image Gen
• MCP Governance SDK

📞 サポート

• 課題：GitHub Issues
• ディスカッション：GitHub Discussions
• ドキュメント：Wiki

---

注意：このサーバーを最適に機能させるには、GitHub アカウントが必要です。認証なしで使用する場合、一部の機能が制限されることがあります。