AI导哈

GitHub问题语义搜索工具

一个结合FAISS和OpenAI嵌入的GitHub仓库问题语义搜索工具，适用于构建RAG系统和知识库。

  • by calumjs
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 calumjs/github.issue.searcher.mcp

使用说明

GitHub问题搜索器MCP🚀

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

一个强大的 模型上下文协议（MCP）服务器 这结合了 费斯 （脸书人工智能相似性搜索） OpenAI嵌入 为GitHub存储库问题提供语义搜索功能。非常适合构建专注于GitHub问题跟踪的RAG（检索增强生成）系统和知识库！

✨ 特性

  • 🔍 语义搜索：使用OpenAI生成嵌入并使用FAISS搜索
  • 📚 文档存储：存储具有丰富元数据的文本，以便进行有组织的检索
  • 🐙 GitHub集成：自动同步和搜索GitHub存储库问题
  • ⚡ 快速相似性搜索：由Facebook的FAISS库提供支持
  • 🔧 MCP兼容：与Claude和其他MCP客户无缝协作
  • 💾 永久存储：自动保存和加载索引和元数据

🛠️ 安装

先决条件

  • Python 3.8或更高版本
  • OpenAI API密钥
  • （可选）用于GitHub集成的GitHub个人访问令牌

快速设置

  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. 设置环境变量 创建一个 .env 文件在 faiss_mcp_server 目录：

    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客户端配置中。对于 克劳德桌面，将此添加到您的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 将存储库数据添加到现有索引的标志
  • 同步可能需要几分钟，具体取决于存储库的大小
  • 服务器在独立同步操作期间保持响应

第二步：搜索问题

同步存储库数据后，您可以使用MCP工具：

搜索嵌入

使用自然语言搜索类似内容：

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 工具，查看当前有多少问题被索引以及来自哪些存储库。

🏗️ 建筑

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问题搜索：语义搜索GitHub存储库问题
  • 📖 问题知识库：从GitHub问题构建可搜索的知识库
  • 🤖 RAG系统：通过相关的GitHub问题上下文增强人工智能响应
  • 📚 研究：查找类似的问题、错误报告或功能请求
  • 💬 开发者支持：搜索问题历史记录以进行故障排除
  • 🔍 项目管理：发现相关问题并跟踪模式

🛡️ 错误处理

服务器包括全面的错误处理：

  • 自动重试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许可证获得许可-请参阅 许可证 文件以获取详细信息。

🙏 致谢

  • Facebook研究 对于令人惊叹的FAISS图书馆
  • OpenAI 对于嵌入模型
  • Anthropic 对于模型上下文协议
  • GitHub 为优秀的API

📞 支持

如果您遇到任何问题或有疑问：

  1. 检查 问题 页
  2. 创建包含详细信息的新问题
  3. 尽可能包括日志和错误消息

由以下材料制成❤️ GitHub社区

快乐的问题搜索！ 🔍✨

相关 MCP