GitHub Issue Searcher MCP 🚀

GitHub Issue Searcher MCP 🚀

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

一个功能强大的 Model Context Protocol (MCP) 服务，结合 FAISS（Facebook AI Similarity Search）和 OpenAI 嵌入，为 GitHub 仓库 Issue 提供语义搜索能力。非常适合构建专注于 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 需要仓库数据才能进行搜索。你有两种选择：

选项 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 请求失败时自动重试
• 服务不可用时优雅降级
• 记录详细日志以便调试
• 验证并清理输入

🤝 参与贡献

欢迎参与贡献！欢迎提交 Pull Request。对于重大更改，请先创建 issue，讨论你想进行的更改。

开发环境设置

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 进行更改
4. 视情况添加测试
5. 提交更改（git commit -m 'Add amazing feature'）
6. 推送到该分支（git push origin feature/amazing-feature）
7. 创建 Pull Request

📝 许可证

本项目采用 MIT License 许可，详情请参阅 LICENSE 文件。

🙏 致谢

• 感谢 Facebook Research 提供出色的 FAISS 库
• 感谢 OpenAI 提供嵌入模型
• 感谢 Anthropic 提供 Model Context Protocol
• 感谢 GitHub 提供出色的 API

📞 支持

如果你遇到问题或有疑问：

1. 查看 Issues 页面
2. 创建新的 issue，并提供详细信息
3. 尽可能附上日志和错误消息

---

为 GitHub 社区倾心打造 ❤️

祝你搜索 issue 愉快！🔍✨