GitHub Issue Searcher MCP 🚀

GitHub Issue Searcher MCP 🚀

https://github.com/user-attachments/assets/a983cf5f-8888-4592-b3c8-0bd152e95722

FAISS（Facebook AI Similarity Search）とOpenAI の埋め込みを組み合わせ、GitHub リポジトリの Issue をセマンティック検索できる、強力な Model Context Protocol（MCP）サーバーです。GitHub の Issue トラッキングに特化した RAG（検索拡張生成）システムやナレッジベースの構築に最適です。

✨ 特長

• 🔍 セマンティック検索：OpenAI を使用して埋め込みを生成し、FAISS で検索します
• 📚 ドキュメントの保存：整理して検索できるよう、豊富なメタデータとともにテキストを保存します
• 🐙 GitHub との連携：GitHub リポジトリの Issue を自動的に同期して検索します
• ⚡ 高速な類似検索：Facebook の FAISS ライブラリを活用します
• 🔧 MCP 互換：Claude やその他の MCP クライアントとシームレスに連携します
• 💾 永続ストレージ：インデックスとメタデータを自動的に保存・読み込みします

🛠️ インストール

前提条件

• Python 3.8 以降
• OpenAI API キー
• （任意）GitHub 連携用の GitHub Personal Access Token

クイックセットアップ

1. リポジトリをクローンします

   git clone https://github.com/calumjs/github-issue-searcher-mcp.git
   cd github-issue-searcher-mcp
   

2. 仮想環境をセットアップします（推奨）

   cd faiss_mcp_server
   python -m venv .venv
   
   # Activate virtual environment
   # On Windows:
   .venv\Scripts\activate
   # On macOS/Linux:
   source .venv/bin/activate
   

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

   pip install -r requirements.txt
   

4. 環境変数を設定します faiss_mcp_server ディレクトリに .env ファイルを作成します：

   OPENAI_API_KEY=your_openai_api_key_here
   GITHUB_PERSONAL_ACCESS_TOKEN=your_github_token_here  # Optional
   

5. GitHub リポジトリを同期します（最初に必ず実行）

   # Sync your first repository to populate the search index
   python sync_github.py owner/repo --clear
   
   # Examples:
   python sync_github.py microsoft/vscode --clear
   python sync_github.py facebook/react --clear
   python sync_github.py SSWConsulting/SSW.YakShaver --clear
   

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

   MCP クライアントの設定にサーバーを追加します。Claude Desktop の場合は、MCP 設定に次の内容を追加します：

   {
     "mcpServers": {
       "github-issue-searcher": {
         "command": "python",
         "args": ["/path/to/your/faiss_mcp_server/main.py"],
         "env": {
           "OPENAI_API_KEY": "your-openai-api-key-here"
         }
       }
     }
   }
   

   注：/path/to/your/faiss_mcp_server/main.py をインストール先の実際のパスに置き換えてください。

   別の方法：テストのためにサーバーを直接実行することもできます：

   python main.py
   

🚀 使い方

ステップ 1：GitHub リポジトリのデータを同期する

最初に必ず実行してください！ GitHub Issue Searcher MCP で検索するには、リポジトリのデータが必要です。次の 2 つの方法があります：

方法 1：スタンドアロンの同期スクリプト（推奨）

cd faiss_mcp_server

# Sync a single repository (clears existing data)
python sync_github.py owner/repo --clear

# Add multiple repositories (append to existing data)
python sync_github.py microsoft/vscode
python sync_github.py facebook/react
python sync_github.py vercel/next.js

方法 2：サーバーの起動時に同期する

cd faiss_mcp_server

# Start server and sync repository
python main.py --sync-repo owner/repo --clear

重要な注意事項：

• --clear フラグを使うと、既存のデータを新しいリポジトリのデータで置き換えます
• --clear フラグを省略すると、既存のインデックスにリポジトリのデータを追加します
• 同期には、リポジトリのサイズによって数分かかることがあります
• スタンドアロンの同期処理中も、サーバーは応答を続けます

ステップ 2：Issue を検索する

リポジトリのデータを同期すると、MCP ツールを使用できます：

search_embeddings

自然言語を使って類似したコンテンツを検索します：

search_embeddings(
    query_text="How to fix memory leaks in React components?",
    k=5  # Number of results to return
)

get_index_status

現在インデックス化されているデータを確認します：

get_index_status()
# Returns: {"initialized": true, "dimension": 1536, "vector_count": 4490, ...}

データの管理

リポジトリを追加する：

# Add additional repositories without clearing existing data
python sync_github.py tensorflow/tensorflow
python sync_github.py pytorch/pytorch

すべてのデータを置き換える：

# Clear everything and sync a new repository
python sync_github.py new-owner/new-repo --clear

現在のデータを確認する： get_index_status ツールを使って、現在インデックス化されている Issue の数と、その Issue がどのリポジトリのものかを確認します。

🏗️ アーキテクチャ

faiss_mcp_server/
├── main.py              # Entry point and argument parsing
├── sync_github.py       # Standalone GitHub sync script
├── server.py            # MCP server initialization
├── requirements.txt     # Python dependencies
├── pyproject.toml       # Project configuration
├── tools/
│   ├── faiss_tools.py   # FAISS search tools
│   └── github_tools.py  # GitHub integration utilities
└── utils/
    ├── faiss_handler.py # Core FAISS operations
    └── github_syncer.py # GitHub API integration

🔧 設定

環境変数

変数	説明	必須
OPENAI_API_KEY	埋め込み生成用の OpenAI API キー	✅ はい
GITHUB_PERSONAL_ACCESS_TOKEN	リポジトリへのアクセス用の GitHub トークン	❌ 任意

データの保存

• FAISS インデックス：faiss_index.bin として保存されます
• メタデータ：metadata.json として保存されます
• 場所：data/ ディレクトリ（自動的に作成されます）

📊 使用例

• 🐛 GitHub Issue の検索：GitHub リポジトリの Issue をセマンティック検索します
• 📖 Issue ナレッジベース：GitHub の Issue から検索可能なナレッジベースを構築します
• 🤖 RAG システム：関連する GitHub Issue のコンテキストを使って AI の応答を強化します
• 📚 調査：類似する Issue、バグ報告、機能リクエストを見つけます
• 💬 開発者サポート：トラブルシューティングのために Issue の履歴を検索します
• 🔍 プロジェクト管理：関連する Issue を見つけ、パターンを追跡します

🛡️ エラー処理

サーバーには包括的なエラー処理が備わっています。

• API の失敗時に自動で再試行します
• サービスを利用できない場合は、適切に機能を縮退します
• デバッグ用に詳細なログを記録します
• 入力の検証とサニタイズを行います

🤝 コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを送信してください。大きな変更を行う場合は、まずイシューを作成して、変更内容についてご相談ください。

開発環境のセットアップ

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更を加えます
4. 該当する場合はテストを追加します
5. 変更をコミットします（git commit -m 'Add amazing feature'）
6. ブランチにプッシュします（git push origin feature/amazing-feature）
7. プルリクエストを作成します

📝 ライセンス

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

🙏 謝辞

• 優れた FAISS ライブラリを提供してくれた Facebook Research
• 埋め込みモデルを提供してくれた OpenAI
• Model Context Protocol を提供してくれた Anthropic
• 優れた API を提供してくれた GitHub

📞 サポート

問題が発生した場合やご質問がある場合は、以下をご確認ください。

1. Issues ページを確認します
2. 詳細な情報を添えて新しいイシューを作成します
3. 可能であれば、ログとエラーメッセージを含めてください

---

GitHub コミュニティのために ❤️ を込めて作成

イシュー検索をお楽しみください！ 🔍✨