使用说明

🚀 GitHub RAG MCP服务器

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

📋 项目概要

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

关键能力：

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

🆚 GitHub MCP比较

功能	官方GitHub MCP	此GitHub RAG MCP
数据访问	通过GitHub API的原始文件内容	已处理、分块和摘要内容
搜索	文件路径和名称搜索	基于AI嵌入的语义搜索
理解	基本文件读取	AI为每个代码块生成摘要
演出	API速率受限	缓存处理，速度提高90%
脱机访问	需要GitHub API	具有离线搜索功能的本地数据库
用例	快速文件访问	深入代码分析和理解

何时在官方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

数据库设置

创建Supabase项目
- 首选 supabase.com 并创建一个新项目
- 等待项目准备就绪（通常1-2分钟）
运行数据库架构
- 在Supabase仪表板中打开SQL编辑器
- 复制并粘贴以下内容 sql/github_rag_schema.sql
- 执行SQL以创建所需的表和函数
获取凭据
- 转到“设置”→ 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的使用
智能恢复：自动缓存损坏处理

处理速度

小型仓库 （<100个文件）：约30秒
中等存储库 （100-1000个文件）：约2-5分钟
大休息 （1000+个文件）：约10-30分钟
启用缓存的重播：快80%

🎬 实时处理示例

当您处理存储库时，您将看到实时进度：

📊 Step 1/4: Cloning repository...
   ✅ Cloned avijeett007/kno2gether-webrtc-agent (develop branch)

🔄 Step 2/4: Processing 156 files...
   📝 Code chunks: 128
   📚 Doc chunks: 28

🔄 Step 3/4: Generating summaries...
   ✅ Generated 10/128 code summaries
   ✅ Generated 50/128 code summaries
   📡 Creating 15 new embeddings (found 113 in cache)
   ✅ All summaries complete!

🔄 Step 4/4: Storing in database...
   💾 Stored 128 code chunks
   💾 Stored 28 documentation chunks
   ✅ Processing complete!

🛠️ 可用工具

存储库处理

clone_and_process_repository：将任何GitHub仓库转换为可搜索的RAG数据
get_available_repositories：列出所有已处理的存储库及其统计信息

智能搜索

search_code_chunks：使用AI生成的摘要查找相关代码
search_documentation_chunks：搜索具有语义相似性评分的文档

库管理

get_repository_details：详细统计数据和元数据
delete_repository：通过级联删除进行彻底删除
update_repository_metadata：更新描述和标签

🔍 支持的内容

代码文件（40+种语言）

Python、JavaScript、TypeScript、Java、C/C++、C#、PHP、Ruby、Go、Rust、Swift、Kotlin、Scala、Shell脚本、SQL、R、Lua、Dart等等。..

文档文件

Markdown(.md），重构文本（.rst)，纯文本(.txt)，AsciiDoc(.adoc)、README文件、CHANGELOG、许可证等。

自动跳过

依赖项: node_modules, __pycache__, venv, vendor
版本控制: .git, .svn, .hg
构建工件: build, dist, target, .next
二进制文件：图像、可执行文件、存档
大文件：>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

🤝 贡献

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

📄 许可证

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

🙏 致谢

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