使用说明

Git存储库上下文检索服务器（MCP服务器）

该项目提供了一个自包含的Docker API服务器，该服务器克隆Git存储库，使用嵌入模型对其进行索引，并公开一个端点以检索自然语言问题的相关代码和文档片段。

这是RAG（检索增强生成）系统的“检索”部分，旨在为外部AI代理（如n8n工作流）提供必要的上下文，以回答有关代码库的问题。

✨ 特性

柔性嵌入： 支持免费的本地嵌入（句子转换器）或OpenAI（付费）
零配置： 在没有API密钥的情况下工作-默认情况下为本地嵌入
🔐 私人存储库： 完全支持GitHub、Bitbucket和GitLab（PAT或SSH）
多提供商支持： GitHub、Bitbucket、GitLab-从URL自动检测
可通过环境变量配置： 指向任何公共或私有Git存储库，无需更改代码
持久缓存： 矢量数据库在首次运行时创建并重用
简单API： 用于搜索和监视的REST端点
生产就绪： 使用非root用户优化Docker容器
成本估算： 显示不同提供商的估计成本

🚀 如何使用

先决条件

码头工人 已安装并在您的计算机上运行。
（可选）A OpenAI API密钥 用于付费嵌入。你可以在 platform.openai.com/api-keys.

使用Docker运行

自由模式（默认-本地嵌入）：

docker run -p 8000:8000 \
  -e REPO_URL="https://github.com/n8n-io/n8n.git" \
  -e REPO_BRANCH="master" \
  -v ./mcp_data/chroma_db:/app/chroma_db \
  --name mcp-server \
  flaviomagacho/mcp-git-server:latest

OpenAI模式（付费-高质量）：

docker run -p 8000:8000 \
  -e REPO_URL="https://github.com/n8n-io/n8n.git" \
  -e REPO_BRANCH="master" \
  -e EMBEDDING_PROVIDER="openai" \
  -e OPENAI_API_KEY="YOUR_SECURE_API_KEY" \
  -v ./mcp_data/chroma_db:/app/chroma_db \
  --name mcp-server \
  flaviomagacho/mcp-git-server:latest

🔐 私有GitHub仓库：

docker run -p 8000:8000 \
  -e REPO_URL="https://github.com/your-username/private-repo.git" \
  -e REPO_BRANCH="main" \
  -e GITHUB_TOKEN="ghp_your_personal_token_here" \
  -v ./mcp_data/chroma_db:/app/chroma_db \
  --name mcp-server \
  flaviomagacho/mcp-git-server:latest

🔐 私有比特桶存储库：

docker run -p 8000:8000 \
  -e REPO_URL="https://bitbucket.org/workspace/private-repo.git" \
  -e REPO_BRANCH="main" \
  -e BITBUCKET_USERNAME="your_username" \
  -e BITBUCKET_APP_PASSWORD="your_app_password" \
  -v ./mcp_data/chroma_db:/app/chroma_db \
  --name mcp-server \
  flaviomagacho/mcp-git-server:latest

📖 文档：

github： PRIVATE_REPOS.md

比特桶：比特币.md

构建和本地测试

# Clone the repository
git clone https://github.com/magacho/mcp-git-server.git
cd mcp-git-server

# Build the image
docker build -t mcp-git-server .

# Run locally
docker run -p 8000:8000 \
  -e REPO_URL="https://github.com/n8n-io/n8n.git" \
  -e REPO_BRANCH="master" \
  -v ./chroma_db:/app/chroma_db \
  mcp-git-server

📡 API终点

健康检查

GET /health

返回服务器状态：

{
  "status": "ready"
}

检索上下文

POST /retrieve
Content-Type: application/json

{
  "query": "How does authentication work in the application?",
  "top_k": 5
}

返回相关代码片段：

{
  "results": [
    {
      "content": "Code snippet content...",
      "metadata": {
        "source": "path/to/file.py"
      },
      "relevance_score": 0.95
    }
  ],
  "total_results": 5
}

嵌入提供者信息

GET /embedding-info

返回有关当前嵌入提供程序的信息：

{
  "provider": "sentence-transformers",
  "available_providers": {
    "sentence-transformers": {
      "available": true,
      "cost": "Free",
      "quality": "Good"
    },
    "openai": {
      "available": true,
      "cost": "$0.0001 per 1K tokens",
      "quality": "Excellent"
    }
  }
}

⚙️ 环境变量

变量	描述	默认值	必填
`REPO_URL`	Git存储库URL（HTTPS或SSH）	-	✅ 是的
`REPO_BRANCH`	要克隆的分支	`main`	没有
`GITHUB_TOKEN`	GitHub PAT用于私有仓库	-	否
`EMBEDDING_PROVIDER`	嵌入提供者(`sentence-transformers`, `openai`, `huggingface`, `auto`)	`sentence-transformers`	没有
`OPENAI_API_KEY`	OpenAI API密钥（如果提供程序是OpenAI，则为必需）	-	有条件
`TOKEN_COUNT_METHOD`	令牌计数方法(`local`, `tiktoken`, `auto`)	`auto`	没有

🔐 私有存储库支持

支持两种身份验证方法：

GitHub个人访问令牌（PAT） -HTTPS

export GITHUB_TOKEN=ghp_your_token
export REPO_URL=https://github.com/user/private-repo.git

SSH密钥

export REPO_URL=git@github.com:user/private-repo.git
docker run -v ~/.ssh:/root/.ssh:ro ...

看 PRIVATE_REPOS.md 以获取完整的文档。

📊 嵌入提供者

提供商	成本	质量	速度	用例
`sentence-transformers`	免费	良好	快速	开发、测试、个人项目
`openai`	0.0001/1K代币	优秀	中等	生产，高质量要求
`huggingface`	免费	可变	中等	实验，自定义模型

🏗️ 建筑

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   Client    │────▶│  FastAPI     │────▶│   Vector    │
│  (n8n, etc) │     │   Server     │     │  Database   │
└─────────────┘     └──────────────┘     │  (Chroma)   │
                            │             └─────────────┘
                            │
                            ▼
                    ┌──────────────┐
                    │  Embeddings  │
                    │  (Local/API) │
                    └──────────────┘
                            │
                            ▼
                    ┌──────────────┐
                    │ Git Repo     │
                    │ (Cloned)     │
                    └──────────────┘

🔍 支持的文件类型

代码： .py, .js, .ts, .jsx, .tsx, .java, .cpp, .c, .h, .cs, .php, .rb, .swift, .go, .rs
网状物： .html, .css, .vue, .svelte
配置： .json, .yml, .yaml, .xml, .env
脚本： .sh, .bash, .sql
基础设施： .tf, .tfvars, .hcl （地形/HCL）
文件： .md, .txt, .pdf
特别： README, LICENSE, DOCKERFILE, MAKEFILE等等。

🎯 用例

AI驱动的代码辅助
- 回答有关代码库的问题
- 从代码生成文档
- 代码审查协助
知识库
- 内部文件搜索
- 引进新开发人员
- 项目知识保留
CI/CD集成
- 自动代码分析
- 文档生成
- 变更影响分析
私人项目
- 保护公司代码库
- 客户项目
- 专有软件

📚 文档

PRIVATE_REPOS.md -私有存储库设置
QUICK_WINS_IMPLEMENTED.md -最近的改进
ROADMAP.md -未来计划
更改日志.md -版本历史

🧪 测试

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
pytest

# Run with coverage
pytest --cov=. --cov-report=html

# Run specific test file
pytest tests/unit/test_models.py -v

🛠️ 发展

# Clone repository
git clone https://github.com/magacho/mcp-git-server.git
cd mcp-git-server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

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

# Run locally
export REPO_URL=https://github.com/example/repo.git
python main.py

# Access API
curl http://localhost:8000/health

🐛 故障排除

问题： 服务器启动缓慢

解决方案： 第一次索引需要时间。后续启动更快（使用缓存数据库）。

问题： 内存不足错误

解决方案： 减小存储库大小或增加Docker内存限制。

问题： 私有仓库身份验证失败

解决方案： 检查GitHub令牌是否具有正确的权限(repo 范围）并且未过期。

问题： 嵌入错误

解决方案： 检查OPENAI_API_KEY是否有效或切换到本地嵌入。

📄 许可证

MIT许可证-请参阅许可证了解详情。

🤝 贡献

欢迎投稿！拜托：

分叉存储库
创建要素分支
通过测试进行更改
提交拉取请求

看 GIT_COMIT_GUIDE.md 承诺约定。

📧 联系

作者弗拉维奥·马加乔
存储库： https://github.com/magacho/mcp-git-server
问题： https://github.com/magacho/mcp-git-server/issues

🌟 明星历史

如果这个项目对你有帮助，请考虑给它一个⭐ 在GitHub上！

由以下材料制成❤️ 面向开发者社区