GitHub Rag MCP

🚀 GitHub RAG MCP服务器

通过智能缓存和实时进度跟踪，将任何GitHub存储库转换为功能强大、可搜索的知识库。

📋 项目概要

这个MCP（模型上下文协议）服务器将GitHub存储库转换为结构化的RAG（检索增强生成）系统，人工智能助手可以智能地查询。与简单的文件访问不同，该工具使用AI生成的摘要和向量嵌入将存储库处理成语义块，从而实现了深入的代码理解和高效的搜索功能。

关键能力：

• 🔄 直接存储库处理：克隆、分析和转换任何GitHub仓库
• 🧠 人工智能驱动的理解：每个代码块的GPT-4摘要
• 🔍 语义搜索：按含义查找代码，而不仅仅是关键字
• 💾 智能缓存：使用智能缓存系统，后续运行速度提高90%
• 📊 实时进度：处理过程中的实时更新

🆚 GitHub MCP比较

何时在官方GitHub MCP上使用此功能：

• ✅ 分析大型复杂的代码库
• ✅ 按功能查找代码，而不仅仅是文件名
• ✅ 利用人工智能深入了解存储库结构
• ✅ 重复使用存储库（缓存优势）
• ✅ 语义代码搜索和发现

🛠️ 安装

先决条件

• Python 3.12+
• OpenAI API密钥 （用于嵌入和总结）
• Supabase账户 （免费版作品）

方法1：使用紫外线（推荐）

紫外线 是最快的Python包管理器（比pip快10-100倍），并提供更好的依赖解析。

第一步：安装uv

还没有紫外线吗？为您的系统选择最佳方法：

🚀 选项A：独立安装程序（推荐-不需要Python）

# Linux/Mac
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

🐍 选项B：使用pip（如果你已经有Python）

pip install uv

📦 选项C：使用pipx（如果你有pipx）

pipx install uv

🍺 选项D：包管理器

# macOS (Homebrew)
brew install uv

# Windows (Scoop)
scoop install uv

# Windows (Chocolatey)
choco install uv

步骤2：设置项目

# 1. Clone the repository
git clone https://github.com/raviteja7748/github-rag-mcp.git
cd github-rag-mcp

# 2. Install dependencies (uv automatically creates virtual environment)
uv sync

# 3. Activate the environment (optional - uv run works without activation)
source .venv/bin/activate  # Linux/Mac
# or
.venv\Scripts\activate     # Windows

方法2：使用pip

# 1. Clone the repository
git clone https://github.com/raviteja7748/github-rag-mcp.git
cd github-rag-mcp

# 2. Create virtual environment
python -m venv .venv

# 3. Activate virtual environment
source .venv/bin/activate  # Linux/Mac
# or
.venv\Scripts\activate     # Windows

# 4. Install dependencies
pip install -r requirements.txt

数据库设置

1. 创建Supabase项目

- 首选 supabase.com 并创建一个新项目 - 等待项目准备就绪（通常1-2分钟）

1. 运行数据库架构

- 在Supabase仪表板中打开SQL编辑器 - 复制并粘贴以下内容 sql/github_rag_schema.sql - 执行SQL以创建所需的表和函数

1. 获取凭据

- 转到“设置”→ Suabase仪表板中的API - 复制您的项目URL和service_role API密钥

环境配置

创建一个 .env 项目根目录中的文件：

# OpenAI Configuration
OPENAI_API_KEY=your_openai_api_key_here
SUMMARY_MODEL=gpt-4o-mini
EMBEDDING_MODEL=text-embedding-3-small

# Supabase Configuration  
SUPABASE_URL=your_supabase_project_url_here
SUPABASE_SERVICE_KEY=your_supabase_service_key_here

# Performance Features (Optional)
CACHE_ENABLED=true
USE_CONTEXTUAL_EMBEDDINGS=true
USE_HYBRID_SEARCH=true
USE_RERANKING=true

启动服务器

# Using uv
uv run python src/github_rag_mcp.py

# Using pip (with activated environment)
python src/github_rag_mcp.py

服务器将于启动 http://localhost:8052

配置您的AI助手

对于游标IDE：

添加到MCP设置(.cursor/mcp.json):

{
  "mcpServers": {
    "github-rag": {
      "transport": "sse",
      "url": "http://localhost:8052/sse"
    }
  }
}

对于Claude Desktop：

添加到您的Claude配置中：

{
  "mcpServers": {
    "github-rag": {
      "command": "python",
      "args": ["path/to/github-rag-mcp/src/github_rag_mcp.py"]
    }
  }
}

✨ 主要特点

• 🔄 直接GitHub集成：克隆和处理任何公共存储库
• 🧠 AI驱动的分析：每个代码块的GPT-4摘要
• 🔍 语义搜索：用于智能代码发现的OpenAI嵌入
• 💾 智能缓存：后续运行速度提高90%，大幅节省API成本
• 📊 实时进度：使用表情符号指示器处理过程中的实时更新
• 🏗️ 智能分块：按函数/类编码，按标题文档
• 🔒 安全处理：临时目录，自动清理
• 🎯 光标集成：原生MCP支持无缝工作流

🔥 性能优势

缓存系统

• 首次运行：使用OpenAI API调用进行完全处理
• 后续运行：约90%的缓存命中率=处理速度提高10倍
• 成本节约：大大减少了OpenAI API的使用
• 智能恢复：自动缓存损坏处理

处理速度

• 小型仓库 （\10MB（智能处理重要代码文件）

🔒 隐私和安全

• 🗂️ 临时处理：存储库克隆到临时目录，处理后自动删除
• 🔐 无文件存储：仅存储在数据库中的已处理块和元数据
• 🛡️ 安全凭据：通过环境变量的所有API键
• 🏠 本地处理：所有文件分析都在您的计算机上进行
• 🧹 自动清理：您的系统上没有留下任何痕迹

📊 数据库模式

核心表

• repositories：存储库元数据、统计信息和处理信息
• code_chunks：带有嵌入和AI摘要的代码段
• doc_chunks：具有语义嵌入的文档块

搜索功能

• match_code_chunks()：代码的向量相似性搜索
• match_doc_chunks()：文档的矢量相似性搜索

⚙️ 配置选项

缓存控制

CACHE_ENABLED=true          # Enable/disable intelligent caching

AI模型选择

SUMMARY_MODEL=gpt-4o-mini              # For generating code summaries
EMBEDDING_MODEL=text-embedding-3-small # For creating vector embeddings

高级RAG功能

USE_CONTEXTUAL_EMBEDDINGS=true    # Better search accuracy
USE_HYBRID_SEARCH=true            # Vector + keyword search
USE_RERANKING=true                # Improved result ordering

🎯 用例

• 📚 代码文档：理解大型、不熟悉的代码库
• 🔍 代码搜索：查找特定的函数、模式或实现
• 🤖 AI助手增强：让你的AI深入了解任何存储库
• 📖 学习：用AI驱动的见解研究开源项目
• 🔧 发展：开发过程中的快速参考和代码发现

🏗️ 建筑

GitHub Repo → Clone → Process → Chunk → Summarize → Embed → Store → Search
     ↓           ↓        ↓        ↓         ↓        ↓       ↓
   Public     Temp     Smart   AI-Gen    OpenAI   Supabase  MCP
   Repos      Dir    Chunking Summary  Embeddings Database Tools

🤝 贡献

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🙏 致谢

• 建立在 模型上下文协议（MCP）
• 由...驱动 OpenAI 嵌入和GPT模型
• 用途 Supabase 用于矢量存储和搜索
• 受现代RAG架构和智能缓存策略的启发

______________________________________________________________________

准备好将任何GitHub存储库转换为强大的、可搜索的知识库了吗？现在就开始吧！ 🚀