代码分析器

Name: 代码分析器
Author: johannhartmann

作者：johannhartmann5 星标更新：2025-10-27

安装使用来源：spider==github.com

项目介绍

MCP 代码分析服务器

一个智能的MCP（模型上下文协议）服务器，提供高级代码分析和搜索功能，适用于大型代码库。该服务器使用纯FastMCP实现，采用TreeSitter进行解析，使用带有pgvector扩展的PostgreSQL进行向量存储，并使用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 - 检测域驱动设计反模式（贫血模型、上帝对象等）
analyze_domain_evolution - 跟踪领域模型随时间的变化
get_domain_metrics - 获取全面的领域健康指标和洞察

快速开始

先决条件

Docker 和 Docker Compose
OpenAI API 密钥（用于语义搜索功能）
Nix with flakes（推荐用于开发）

Docker 部署（推荐）

最简单的开始方式是使用 Docker Compose，它提供了包含PostgreSQL和pgvector的完整隔离环境。

克隆仓库：

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

设置环境变量：

export OPENAI_API_KEY="your-api-key-here"
# 或者添加到 .env 文件中

配置仓库：创建一个 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_..."  # 对于私有仓库

# 扫描器配置
scanner:
  storage_path: ./repositories
  exclude_patterns:
    - "__pycache__"
    - "*.pyc"
    - ".git"
    - "venv"
    - "node_modules"

使用 Docker Compose 启动服务：

docker-compose up -d

这将：

启动带有pgvector扩展的PostgreSQL
构建并启动MCP代码分析服务器
初始化数据库所需的模式
自动扫描配置的仓库

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

开发环境（本地）

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

# 进入Nix开发环境
nix develop

# 安装Python依赖项
uv sync

# 启动PostgreSQL（如果不使用Docker Compose）
docker-compose up -d postgres

# 运行扫描器以填充数据库
python -m src.scanner

# 启动MCP服务器
python -m src.mcp_server

# 或运行测试
pytest

# 检查代码质量
ruff check .
black --check .
mypy .
vulture src vulture_whitelist.py

Nix环境包括：

Python 3.11及所有依赖项
代码格式化工具（black, isort）
静态分析工具（ruff, pylint, bandit）
类型检查器（mypy）
死代码检测（vulture）
测试运行器（pytest）
预提交钩子

配置

编辑 config.yaml 以自定义设置：

# OpenAI API 密钥（也可以使用 OPENAI_API_KEY 环境变量）
openai_api_key: "sk-..."

# 要跟踪的仓库
repositories:
  - url: https://github.com/owner/repo
    branch: main  # 可选，未指定时使用默认分支
  - url: https://github.com/owner/private-repo
    access_token: "github_pat_..."  # 对于私有仓库

# 扫描器配置
scanner:
  storage_path: ./repositories
  exclude_patterns:
    - "__pycache__"
    - "*.pyc"
    - ".git"
    - "venv"
    - "node_modules"

# 嵌入配置
embeddings:
  model: "text-embedding-ada-002"
  batch_size: 100
  max_tokens: 10000

# MCP服务器配置
mcp:
  host: "0.0.0.0"
  port: 8080

# 数据库配置
database:
  host: localhost
  port: 5432
  database: code_analysis
  user: codeanalyzer
  password: your-secure-password

使用示例

使用MCP工具

一旦服务器运行，您可以使用任何MCP客户端来调用工具：

# 使用自然语言搜索代码
await mcp.call_tool("search_code", {
    "query": "处理用户认证的函数",
    "limit": 10
})

# 查找符号的定义位置
await mcp.call_tool("find_definition", {
    "name": "UserService",
    "entity_type": "class"
})

# 获取层次代码解释
await mcp.call_tool("explain_code", {
    "path": "src.auth.user_service.UserService"
})

# 查找相似的代码模式
await mcp.call_tool("find_similar_code", {
    "code_snippet": "def authenticate_user(username, password):",
    "limit": 5,
    "threshold": 0.7
})

# 获取代码结构
await mcp.call_tool("get_code_structure", {
    "file_path": "src/auth/user_service.py"
})

# 获取重构建议
await mcp.call_tool("suggest_refactoring", {
    "file_path": "src/auth/user_service.py",
    "focus_area": "性能"
})

# 从代码中提取领域模型
await mcp.call_tool("extract_domain_model", {
    "code_path": "src/domain/user.py",
    "include_relationships": True
})

# 查找聚合根
await mcp.call_tool("find_aggregate_roots", {
    "context_name": "user_management"  # 可选
})

# 分析有界上下文
await mcp.call_tool("analyze_bounded_context", {
    "context_name": "authentication"
})

# 生成上下文地图
await mcp.call_tool("generate_context_map", {
    "output_format": "mermaid"  # json, mermaid, 或 plantuml
})

使用Claude Desktop

在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模块？”

开发

运行测试

# 运行所有测试
pytest

# 运行覆盖率测试
pytest --cov=src --cov-report=html

# 运行特定类型的测试
pytest tests/unit/
pytest tests/integration/

代码质量

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

# 运行所有静态分析工具
ruff check .

# 格式化代码
black .
isort .

# 类型检查
mypy .

# 查找死代码
vulture src vulture_whitelist.py

# 运行预提交钩子
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生成语义嵌入，用于向量搜索
数据库模块：使用带有pgvector扩展的PostgreSQL进行高效的向量存储
查询模块：处理自然语言查询和符号查找
MCP服务器：纯FastMCP实现，暴露代码分析工具
领域模块：提取领域实体和关系，用于DDD分析

性能

初始索引：每分钟约1000个文件，使用并行处理
增量更新：100个更改文件的Git跟踪小于10秒
查询响应：使用pgvector的语义搜索小于2秒
可扩展性：支持多达1000万行代码的代码库
内存效率：优化的数据库会话和批处理

贡献

我们欢迎贡献！请参阅CONTRIBUTING.md获取指南。

许可证

本项目根据MIT许可证发布 - 详情见LICENSE文件。

作者

Johann-Peter Hartmann 邮箱：johann-peter.hartmann@mayflower.de GitHub：@johannhartmann

关键技术

FastMCP：纯MCP协议实现
TreeSitter：强大的代码解析和AST生成
pgvector：高性能向量相似性搜索
OpenAI Embeddings：代码的语义理解
PostgreSQL：可靠的数据持久性和复杂查询
Nix：可重复的开发环境
Docker：容器化部署和隔离