MCP Code Analysis Server

MCP代码分析服务器

    

一种智能MCP（模型上下文协议）服务器，为大型代码库提供高级代码分析和搜索功能。它使用纯FastMCP实现构建，使用TreeSitter进行解析，使用PostgreSQL和pgvector进行向量存储，使用OpenAI嵌入进行语义搜索。

特性

• 🔍 语义代码搜索：查找相关代码的自然语言查询
• 🏛️ 领域驱动分析：使用LLM提取业务实体和有界上下文
• 📊 代码结构分析：对模块、类和函数的分层理解
• 🔄 增量更新：基于Git的更改跟踪，实现高效的重新索引
• 🎯 智能代码解释：具有上下文聚合的AI驱动解释
• 🔗 相关性分析：了解代码关系和依赖关系
• 🌐 知识图谱：使用社区检测（Leiden算法）构建语义图
• 💡 DDD重构：领域驱动设计建议和改进
• 🚀 高性能：处理包含数百万行代码的代码库
• 🐍 Python支持：全面支持Python，更多语言即将推出

MCP工具可用

核心搜索工具

• search_code -使用具有语义理解的自然语言查询搜索代码
• find_definition -查找定义符号（函数、类、模块）的位置
• find_similar_code -使用向量相似度查找与给定代码段相似的代码模式
• get_code_structure -获取代码文件的层次结构

代码分析工具

• explain_code -获取代码元素（模块、类、函数）的层次化解释
• suggest_refactoring -获取AI支持的代码重构建议以进行代码改进
• analyze_dependencies -分析代码实体之间的依赖关系和关系

存储库管理工具

• sync_repository -手动触发特定存储库的同步

领域驱动设计分析工具

• extract_domain_model -使用LLM分析提取域实体和关系
• find_aggregate_roots -使用域分析在代码库中查找聚合根
• analyze_bounded_context -分析有界上下文及其关系
• suggest_ddd_refactoring -建议领域驱动设计重构改进
• find_bounded_contexts -查找代码库中的所有有界上下文
• generate_context_map -生成上下文映射（JSON、Mermaid、PlantUML）

高级分析工具

• analyze_coupling -使用度量分析有界上下文之间的耦合
• suggest_context_splits -建议如何拆分大型有界上下文
• detect_anti_patterns -检测DDD反模式（贫血模型、上帝对象等）
• analyze_domain_evolution -跟踪域模型随时间的变化
• get_domain_metrics -获取全面的领域健康指标和见解

快速开始

先决条件

• Docker和Docker Compose
• OpenAI API密钥（用于语义搜索功能）
• 带薄片的镍（建议用于开发）

Docker部署（推荐）

最简单的入门方法是使用Docker Compose，它提供了一个包含PostgreSQL和pgvector的完整隔离环境。

1. 克隆存储库：

git clone https://github.com/johannhartmann/mcp-code-analysis-server.git
cd mcp-code-analysis-server

1. 设置环境变量：

export OPENAI_API_KEY="your-api-key-here"
# Or add to .env file

1. 配置存储库：

创建一个 config.yaml 文件以指定要跟踪的存储库：

repositories:
  - url: https://github.com/owner/repo1
    branch: main
  - url: https://github.com/owner/repo2
    branch: develop
  - url: https://github.com/owner/private-repo
    access_token: "github_pat_..."  # For private repos

# Scanner configuration
scanner:
  storage_path: ./repositories
  exclude_patterns:
    - "__pycache__"
    - "*.pyc"
    - ".git"
    - "venv"
    - "node_modules"

1. 使用Docker Compose启动服务：

docker-compose up -d

这将：

• 使用pgvector扩展名启动PostgreSQL
• 构建并启动MCP代码分析服务器
• 使用所需的架构初始化数据库
• 开始自动扫描已配置的存储库

服务器作为纯MCP实现运行，可以通过任何兼容MCP的客户端访问。

发展环境（当地）

对于开发工作，请使用提供所有必要工具和依赖关系的Nix开发环境：

# Enter the Nix development environment
nix develop

# Install Python dependencies
uv sync

# Start PostgreSQL (if not using Docker Compose)
docker-compose up -d postgres

# Run the scanner to populate the database
python -m src.scanner

# Start the MCP server
python -m src.mcp_server

# Or run tests
pytest

# Check code quality
ruff check .
black --check .
mypy .
vulture src vulture_whitelist.py

Nix环境包括：

• Python 3.11及其所有依赖项
• 代码格式化工具（黑色，isort）
• 棉绒（头皮屑、皮绒、土匪）
• 类型检查器（mypy）
• 死码检测（秃鹫）
• 测试运行器（pytest）
• 预提交挂钩

配置

编辑 config.yaml 自定义：

# OpenAI API key (can also use OPENAI_API_KEY env var)
openai_api_key: "sk-..."

# Repositories to track
repositories:
  - url: https://github.com/owner/repo
    branch: main  # Optional, uses default branch if not specified
  - url: https://github.com/owner/private-repo
    access_token: "github_pat_..."  # For private repos

# Scanner configuration
scanner:
  storage_path: ./repositories
  exclude_patterns:
    - "__pycache__"
    - "*.pyc"
    - ".git"
    - "venv"
    - "node_modules"

# Embeddings configuration
embeddings:
  model: "text-embedding-ada-002"
  batch_size: 100
  max_tokens: 8000

# MCP server configuration
mcp:
  host: "0.0.0.0"
  port: 8080

# Database configuration
database:
  host: localhost
  port: 5432
  database: code_analysis
  user: codeanalyzer
  password: your-secure-password

使用示例

使用MCP工具

服务器运行后，您可以通过任何MCP客户端使用这些工具：

# Search for code using natural language
await mcp.call_tool("search_code", {
    "query": "functions that handle user authentication",
    "limit": 10
})

# Find where a symbol is defined
await mcp.call_tool("find_definition", {
    "name": "UserService",
    "entity_type": "class"
})

# Get hierarchical code explanation
await mcp.call_tool("explain_code", {
    "path": "src.auth.user_service.UserService"
})

# Find similar code patterns
await mcp.call_tool("find_similar_code", {
    "code_snippet": "def authenticate_user(username, password):",
    "limit": 5,
    "threshold": 0.7
})

# Get code structure
await mcp.call_tool("get_code_structure", {
    "file_path": "src/auth/user_service.py"
})

# Get refactoring suggestions
await mcp.call_tool("suggest_refactoring", {
    "file_path": "src/auth/user_service.py",
    "focus_area": "performance"
})

# Extract domain model from code
await mcp.call_tool("extract_domain_model", {
    "code_path": "src/domain/user.py",
    "include_relationships": True
})

# Find aggregate roots
await mcp.call_tool("find_aggregate_roots", {
    "context_name": "user_management"  # optional
})

# Analyze bounded context
await mcp.call_tool("analyze_bounded_context", {
    "context_name": "authentication"
})

# Generate context map
await mcp.call_tool("generate_context_map", {
    "output_format": "mermaid"  # json, mermaid, or plantuml
})

使用克劳德桌面

在Claude Desktop设置中配置MCP服务器：

对于stdio模式（在本地运行时）：

{
  "mcpServers": {
    "code-analysis": {
      "command": "python",
      "args": ["-m", "src.mcp_server"],
      "cwd": "/path/to/mcp-code-analysis-server",
      "env": {
        "OPENAI_API_KEY": "your-api-key"
      }
    }
  }
}

对于HTTP模式（使用Docker时）：

{
  "mcpServers": {
    "code-analysis": {
      "url": "http://localhost:8000"
    }
  }
}

然后在Claude Desktop中：

• “搜索处理身份验证的函数”
• “显示UserService类的实现”
• “查找数据库连接池的所有用法”
• “哪些文件导入utils模块？”

发展

运行测试

# Run all tests
pytest

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

# Run specific test types
pytest tests/unit/
pytest tests/integration/

代码质量

该项目使用集成到Nix开发环境中的全面代码质量工具：

# Run all linters
ruff check .

# Format code
black .
isort .

# Type checking
mypy .

# Find dead code
vulture src vulture_whitelist.py

# Run pre-commit hooks
nix-pre-commit

预提交钩子

安装预提交挂钩以进行自动代码质量检查：

echo '#!/bin/sh' > .git/hooks/pre-commit
echo 'nix-pre-commit' >> .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

建筑

服务器由几个关键组件组成：

• 扫描仪模块：通过增量更新监视和同步Git存储库
• 解析器模块：使用TreeSitter提取代码结构以进行精确的AST解析
• 嵌入模块：通过OpenAI生成用于向量搜索的语义嵌入
• 数据库模块：PostgreSQL具有pgvector扩展，可实现高效的向量存储
• 查询模块：处理自然语言查询和符号查找
• MCP服务器：纯FastMCP实现，公开代码分析工具
• 域模块：提取用于DDD分析的域实体和关系

演出

• 初始索引：并行处理时约1000个文件/分钟
• 增量更新：使用Git跟踪100个更改的文件，时间\<10秒
• 查询响应：使用pgvector进行语义搜索\<2秒
• 可扩展性：支持多达1000万行以上的代码库
• 存储器效率：优化了数据库会话和批处理

贡献

我们欢迎捐款！请看 贡献.md 作为指导方针。

许可证

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

作者

约翰·彼得·哈特曼 电子邮件：johann-peter.hartmann@mayflower.de github： @约翰哈特曼

关键技术

• FastMCP：纯MCP协议实现
• TreeSitter：强大的代码解析和AST生成
• pg载体：高性能矢量相似性搜索
• OpenAI嵌入：代码的语义理解
• PostgreSQL：可靠的数据持久性和复杂的查询
• 无：可复制的开发环境
• 码头工人：容器化部署和隔离