🔍 MCP 代码库分析器
一个智能的模型上下文协议（MCP）服务器，能够分析GitHub仓库，并提供基于人工智能的建议，帮助您找到适合您功能需求的代码部分。
🎯 它的作用是什么？
这个MCP服务器允许您提出诸如以下问题：
*“我需要创建一个产品获取弹出模态框。请从jolly-commerce/jolly-sections中找到最佳的板块。”*
服务器将：
- 获取并分析 仓库（本地克隆和缓存）
- 解析 源代码文件（仅限JS/TS，跳过压缩包）
- 提取 具有完整代码的函数、类和组件
- 索引 使用语义嵌入（OpenAI或Ollama）的章节
- 搜索 在语义上对于相关代码
- 提供人工智能推荐 附带推理和实施建议
✨ 特点
- 🔎（放大镜图标，常用于表示搜索或查看细节） 语义代码搜索 - 通过意义而非仅通过关键词来查找代码（相关性得分0.7+）
- 🤖 机器人 基于人工智能的推荐 - 获取高置信度的智能建议
- 📁 文件夹 智能过滤 - 自动跳过压缩文件（.min.js、.chunk.js、捆绑文件）
- 💻 电脑/笔记本电脑 专注于JavaScript/TypeScript - 优化用于现代网页开发
- 💾 磁盘驱动器或存储设备的符号 持久缓存 - 为即时重复查询缓存的存储库和嵌入表示
- 🐳 表示海豚或海豚的叫声（在某些网络语境中），但直接翻译这个表情符号并不容易，因为它是一个非文字的符号。如果要结合语境来翻译，可以理解为“海豚”或者在网络用语中表示“厉害”、“厉害至极”等意思。不过，直接给出的翻译是“海豚”或“海豚的叫声”。 Docker 准备就绪 - 准备就绪的容器化部署
- 🔌（电源插头） 兼容MCP - 与Cursor IDE及其他MCP客户端无缝协作
- ⚡ 闪电符号（表示快速、能量或电力） 生产测试 - 成功为jolly-commerce/jolly-sections建立索引（152个部分，100%成功率）
🚀 快速入门
先决条件： Docker Desktop，OpenAI API密钥
1. 设置环境
cp env.example .env
# Edit .env and add your OpenAI API key:
# LLM_API_KEY=sk-your-key-here2. 启动服务器
docker-compose up -d
docker-compose logs -f # Wait for "All components initialized"3. 配置光标
添加到光标MCP设置（Cmd/Ctrl + , → 搜索 "MCP"：
{
"mcpServers": {
"codebase-analyser": {
"url": "http://localhost:8050/sse",
"transport": {"type": "sse"}
}
}
}重启光标。
4. 进行测试
在 Cursor 中，尝试：
Analyze the repository jolly-commerce/jolly-sections等待2-3分钟，然后：
I need to create a product fetch popup modal. Find the best section.✅ 预期：带有代码片段的 FetchModalProductPopUp 类
______________________________________________________________________
备选方案：本地开发（不使用 Docker）
pip install uv
uv pip install -e .
# Edit .env with your API key
uv run src/main.py📖 使用示例
1. 分析一个存储库
首先，分析你想要搜索的仓库：
User: Analyze the repository jolly-commerce/jolly-sections
AI uses: analyze_repository("jolly-commerce/jolly-sections")结果：
{
"success": true,
"message": "Successfully analyzed jolly-commerce/jolly-sections",
"indexing": {
"indexed": 152,
"errors": 0,
"total": 152
},
"files_analyzed": 43,
"section_types": {
"functions": 37,
"classes": 74,
"react_component": 32
}
}2. 找到适合您特性的最佳部分
User: I need to create a product fetch popup modal.
Find the best section from jolly-commerce/jolly-sections.
AI uses: find_best_section(
feature_description="product fetch popup modal",
repo_identifier="jolly-commerce/jolly-sections"
)真实回应：
{
"found_match": true,
"best_match": "src/templates/components/g-modal.js",
"best_match_name": "FetchModalProductPopUp",
"confidence": "high",
"score": 0.69,
"reasoning": "The FetchModalProductPopUp class is specifically designed to handle product fetching in a modal context, which aligns perfectly with the user's request...",
"usage_advice": "To use this section, instantiate the FetchModalProductPopUp class and call the onTrigger method with the appropriate event and trigger element...",
"alternatives": ["DynamicModal", "GModal"],
"code_snippet": "class FetchModalProductPopUp extends FetchModal { ... }"
}3. 搜索特定代码模式
User: Find cart drawer components in jolly-commerce/jolly-sections
AI uses: search_code_sections(
query="cart drawer shopping cart sidebar",
repo_identifier="jolly-commerce/jolly-sections",
limit=10
)真实回应：
{
"success": true,
"results_count": 3,
"results": [
{
"file": "src/templates/components/g-cart.js",
"name": "CartDrawer",
"type": "class",
"score": 0.72,
"code": "class CartDrawer extends Cart { ... }"
},
{
"file": "src/templates/components/g-cart.js",
"name": "CartDrawerItem",
"type": "class",
"score": 0.70
}
]
}4. 获取仓库结构
User: What sections are available in jolly-sections?
Tool: get_repository_structure("jolly-sections/jolly-sections")5. 列出所有已分析的存储库
User: What repositories have been analyzed?
Tool: list_analyzed_repositories()🛠️ 可用的MCP工具
| 工具 | 描述 | 示例 | |||
|---|---|---|---|---|---|
| 项目 | 描述 | 类型 | analyze_repository | analyze_repository("owner/repo") | 索引 GitHub 仓库 |
find_best_section | find_best_section("hero section", "owner/repo") | 获取针对功能的AI推荐 | |||
search_code_sections | search_code_sections("button component", "owner/repo") | 语义代码搜索 | |||
get_repository_structure | get_repository_structure("owner/repo") | 查看已索引部分 | |||
list_analyzed_repositories | list_analyzed_repositories() | 列出所有已索引的仓库 | |||
clear_repository_cache | clear_repository_cache("owner/repo") | 清除缓存数据 |
|
┌─────────────────────────────────────────────────────────────┐
│ Cursor IDE │
│ (MCP Client) │
└────────────────────────┬────────────────────────────────────┘
│ MCP Protocol (SSE/STDIO)
↓
┌─────────────────────────────────────────────────────────────┐
│ MCP Server (FastMCP) │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Repository Fetcher │ │
│ │ • Clone GitHub repos │ │
│ │ • Cache locally │ │
│ │ • Handle authentication │ │
│ └──────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Code Parser │ │
│ │ • Parse JS/TS/Python/etc. │ │
│ │ • Extract functions/classes/components │ │
│ │ • Generate metadata │ │
│ └──────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Embedding System │ │
│ │ • Generate embeddings (OpenAI/Ollama) │ │
│ │ • ChromaDB vector database │ │
│ │ • Semantic search │ │
│ └──────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Recommendation System │ │
│ │ • LLM analysis (GPT-4/Ollama) │ │
│ │ • Context-aware suggestions │ │
│ │ • Implementation advice │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│ │ │
↓ ↓ ↓
repo_cache/ chroma_db/ GitHub API🏗️ 建筑学
mcp-codebase-analyser/
├── src/
│ ├── main.py # MCP server & tools
│ ├── repo_fetcher.py # GitHub repository fetching
│ ├── code_parser.py # Code parsing & extraction
│ ├── embedding_system.py # Vector embeddings & search
│ ├── recommendation_system.py # AI recommendations
│ └── utils.py # Utility functions
├── repo_cache/ # Cached repositories
├── chroma_db/ # Vector database
├── Dockerfile # Docker image
├── docker-compose.yml # Docker compose config
├── pyproject.toml # Python dependencies
├── env.example # Environment variables template
└── README.md # This file📁 项目结构
🔑 环境变量 | 变量 | 描述 | 默认值 | 是否必需 | |----------|-------------|---------|----------| HOST | 0.0.0.0 | 服务器主机 | | 编号 | PORT | 8050 | 服务器端口 | | 编号 | TRANSPORT |sse | 交通方式（ stdio或者 sse ）| | 不 | LLM_PROVIDER |openai| 大型语言模型（LLM）提供商 ( ollama， openai ) | | 是 | LLM_API_KEY | 大型语言模型的API密钥 | - | 是（OpenAI） | LLM_MODEL | gpt-4o-mini | 模型名称 | | 编号/序号 | EMBEDDING_MODEL | text-embedding-3-small | 嵌入模型 | | 序号 | GITHUB_TOKEN | | GitHub个人访问令牌 | - | 否 | REPO_CACHE_DIR | ./repo_cache | 仓库缓存目录 | | 不 | CHROMA_PERSIST_DIR | ./chroma_db | ChromaDB 目录 | | 编号 | MAX_FILE_SIZE_KB | 500 | 可解析的最大文件大小 | | 编号 | SUPPORTED_EXTENSIONS | .js,.jsx,.ts,.tsx | 需要解析的文件扩展名 |
| 不 | 注：
- 系统自动跳过：
.min.js压缩后的文件（ - )
.chunk.js捆绑文件（bundle-*.js， - )
- 资源目录中的编译代码
这确保了仅对源代码进行索引，以获得更高质量的结果
🧪 测试
# 1. Start the server
docker-compose up -d
# 2. Check logs for success messages
docker-compose logs -f
# Look for: "Initialized embedding system with openai provider"
# Look for: "All components initialized successfully"
# 3. In Cursor, try these verified examples:使用经过生产环境测试的存储库来测试服务器： 测试1：分析仓库
Analyze the repository jolly-commerce/jolly-sections（2-3分钟）
预期：已索引152个部分，0个错误 测试2：查找特定组件
I need to create a product fetch popup modal. Find the best section.(10-15秒)
预期：高置信度（0.69+）的FetchModalProductPopUp类 测试3：搜索组件
Find cart drawer components in jolly-commerce/jolly-sections（5-10秒）
预期：购物车抽屉，带有相关性评分的购物车抽屉项
🐛 故障排除
- 服务器无法启动
- 检查Docker Desktop是否正在运行
.env验证 - 文件存在且包含正确的值
docker-compose logs -f
检查日志：
- 无法克隆私有仓库
GITHUB_TOKEN添加.env - to
repo确保令牌具有（所需属性/权限等，具体根据上下文确定）
范围
- 内存不足 / 索引速度慢
MAX_FILE_SIZE_KB减少.env - 在里面
SUPPORTED_EXTENSIONS限制 - 仅需特定类型
增加Docker的内存限制
- 嵌入式API错误
LLM_API_KEY验证 - 是正确的
- 检查OpenAI账户是否有余额
尝试使用Ollama进行本地嵌入
🔄 与Ollama（本地大型语言模型）配合使用
- 对于完全本地设置：安装Ollama
- https://ollama.ai（注：该网址直接翻译为中文即保持原样，因为网址本身不是需要翻译的语言内容，而是指向一个特定网站的地址。）拉模（或拉伸模型）
ollama pull qwen2.5-coder:7b
ollama pull nomic-embed-text- ：
.env更新
LLM_PROVIDER=ollama
LLM_MODEL=qwen2.5-coder:7b
LLM_BASE_URL=http://host.docker.internal:11434
EMBEDDING_MODEL=nomic-embed-text- :重启服务器
docker-compose restart：
📝 开发
添加对新文件类型的支持 src/code_parser.py 编辑
PATTERNS = {
"your_language": [
r"pattern_to_match_functions",
r"pattern_to_match_classes",
]
}并为您的语言添加模式：
定制化推荐 src/recommendation_system.py编辑系统提示语
def _get_system_prompt(self) -> str:
return """Your custom prompt here..."""：
🤝 贡献（或“参与贡献”）
欢迎贡献！请随时提交问题和拉取请求。
📊 表现统计
- 在jolly-commerce/jolly-sections上进行的生产测试：
- ✅ 152个部分已索引（100%成功）
- ✅ 索引过程中无错误
- ✅ 已分析43个源文件
- ✅ 平均搜索得分：0.7+（高度相关）
- ✅ 未索引任何压缩文件（智能过滤）
- ✅ 查询时间：5-15秒
✅ 初始索引：2-3分钟
- 代码质量：
- 仅索引源文件（src/templates/）
- 提取了完整的代码内容（而不仅仅是名称）
- 高精度语义搜索
带有推理的AI推荐
📄 许可证
MIT 许可证 - 详见 LICENSE 文件
- 🙏 致谢 构建于
- FastMCP 由……提供动力/支持
- ChromaDB（可译为“色度数据库”，但具体翻译可能根据上下文有所调整，若“ChromaDB”为特定产品或服务名，建议保留原名） 用途 OpenAI 嵌入（或向量表示） 或者
- Ollama（注：Ollama是一个用于本地运行大型语言模型的工具或框架，直接翻译可能无法准确传达其含义，但在此处保持原样以指代该特定名称） 生产测试于
jolly-commerce/jolly-sections 翻译为中文是：“欢乐商贸/欢乐板块”
📞 支持
______________________________________________________________________
对于问题和疑问，请在GitHub上提交一个议题。