🔍 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-here

2. 启动服务器

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 翻译为中文是：“欢乐商贸/欢乐板块”

📞 支持