AST MCP Server

AST MCP 服务

一个 MCP（模型上下文协议）服务，通过抽象语法树（AST）和抽象语义图（ASG）提供代码结构与语义分析能力。

功能

• 将代码解析为抽象语法树（AST）
• 根据代码生成抽象语义图（ASG）
• 分析代码结构和复杂度
• 支持多种编程语言（Python、JavaScript、TypeScript、Go、Rust、C/C++、Java）
• 兼容 Claude Desktop 和其他 MCP 客户端
• 增量解析，加快大型文件的处理速度
• 增强作用域处理，提供更完整的语义分析
• 通过 AST 差异比对识别不同代码版本之间的变更
• 缓存资源，提升性能

安装

前置条件

• Python 3.9 或更高版本
• uv 包管理器（推荐）或 pip

使用 uv（推荐）

1. 克隆此仓库：

git clone https://github.com/angrysky56/ast-mcp-server.git
cd ast-mcp-server

2. 安装项目和依赖项：

# Install the project in development mode with all dependencies
uv sync

# Or install with specific optional dependencies
uv sync --extra dev  # Development tools
uv sync --extra testing  # Testing dependencies
uv sync --extra docs  # Documentation tools

3. 构建 tree-sitter 解析器：

uv run build-parsers

使用 pip（备选）

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

# Install dependencies
pip install -e .

# Build parsers
python build_parsers.py

在 Claude Desktop 中使用

1. 编辑配置文件，将 Claude Desktop 配置为使用此服务：

配置文件位置：

• macOS：~/Library/Application Support/claude-desktop/claude_desktop_config.json
• Linux：~/.config/claude-desktop/claude_desktop_config.json
• Windows：%APPDATA%\claude-desktop\claude_desktop_config.json

2. 添加 AST MCP 服务配置：

{
  "mcpServers": {
    "AstAnalyzer": {
      "command": "uv",
      "args": [
        "--directory",
        "/home/ty/Repositories/ai_workspace/ast-mcp-server/ast_mcp_server",
        "run",
        "server.py"
      ]
    }
  }
}

重要： 将 /absolute/path/to/ast-mcp-server 替换为系统中的实际绝对路径。

3. 重启 Claude Desktop，以加载新的 MCP 服务。

4. 在 Claude Desktop 中，现在可以通过引用代码文件或粘贴代码片段来使用基于 AST 的代码分析工具。

开发

开发环境设置

# Install with development dependencies
uv sync --extra dev

# Install pre-commit hooks (optional)
uv run pre-commit install

在开发模式下运行

要在开发模式下使用 MCP 检查器运行服务：

# Using uv
uv run --extra dev -- -m mcp dev server.py

# Or using the development script
./dev_server.sh

测试

# Run all tests
uv run --extra testing pytest

# Run tests with coverage
uv run --extra testing pytest --cov=ast_mcp_server --cov-report=html

# Run specific tests
uv run --extra testing pytest tests/test_specific.py

代码质量

# Format code
uv run black .
uv run isort .

# Lint code
uv run flake8 .

# Type checking
uv run mypy ast_mcp_server/

可用工具

此服务提供以下代码分析工具：

基础工具

• parse_to_ast：将代码解析为抽象语法树
• generate_asg：根据代码生成抽象语义图
• analyze_code：分析代码结构和复杂度
• supported_languages：获取支持的编程语言列表

缓存工具

• parse_and_cache：将代码解析为 AST，并缓存以供资源访问
• generate_and_cache_asg：生成 ASG，并缓存以供资源访问
• analyze_and_cache：分析代码，并缓存结果以供资源访问

增强工具

• parse_to_ast_incremental：以增量方式解析代码，加快处理速度
• generate_enhanced_asg：生成增强版 ASG，改进作用域处理
• diff_ast：查找两个代码版本之间的差异
• find_node_at_position：定位指定行列位置的节点
• parse_and_cache_incremental：以增量方式解析代码并缓存结果
• generate_and_cache_enhanced_asg：生成增强版 ASG 并缓存
• ast_diff_and_cache：生成 AST 差异并缓存

添加语言支持

要添加对其他编程语言的支持：

1. 安装相应的 tree-sitter 语言包：

uv add tree-sitter-<language>

2. 更新 build_parsers.py 和 ast_mcp_server/tools.py 中的 LANGUAGE_MODULES 字典。

3. 构建解析器：

uv run build-parsers

当前支持的语言

• Python（tree-sitter-python）
• JavaScript（tree-sitter-javascript）
• TypeScript（tree-sitter-typescript）
• Go（tree-sitter-go）
• Rust（tree-sitter-rust）
• C（tree-sitter-c）
• C++（tree-sitter-cpp）
• Java（tree-sitter-java）

工作原理

AST MCP Server 通过 Model Context Protocol (MCP) 与 Claude Desktop 连接：

1. 初始化：Claude Desktop 使用 uv run 并指定适当的工作目录启动服务
2. 加载语言：服务加载 tree-sitter 语言模块，用于解析各种编程语言
3. MCP 注册：服务通过 MCP 协议注册工具和资源
4. 分析：Claude 可以使用这些工具分析你分享的代码或本地文件。工具经过稳健性设计：如果提供的代码是占位符，它们可以智能地从本地 filename 路径读取内容。
5. 缓存：结果会缓存在本地，以提升性能

所有工具执行都在你的计算机本地进行，结果会返回给 Claude，由其进行解读并提供协助。

配置文件

• pyproject.toml：项目元数据、依赖项和工具配置
• claude_desktop_config.json：Claude Desktop 配置示例
• dev_server.sh：开发服务脚本
• .gitignore：Git 忽略规则

目录结构

ast-mcp-server/
├── ast_mcp_server/          # Main package
│   ├── __init__.py
│   ├── tools.py             # Core AST/ASG tools
│   ├── enhanced_tools.py    # Enhanced analysis features
│   ├── resources.py         # MCP resource handlers
│   └── parsers/             # Tree-sitter parser cache
├── examples/                # Usage examples
├── tests/                   # Test suite
├── server.py                # Main server entry point
├── build_parsers.py         # Parser setup script
├── pyproject.toml           # Project configuration
└── README.md               # This file

故障排除

解析器问题

如果遇到解析器相关错误：

# Rebuild parsers
uv run build-parsers

# Check for missing language packages
uv add tree-sitter-python tree-sitter-javascript

Claude Desktop 连接问题

1. 检查 Claude Desktop 配置中的绝对路径
2. 确保 uv 位于系统 PATH 中
3. 查看 Claude Desktop 日志中的错误消息
4. 更改配置后重启 Claude Desktop

性能问题

• 对大型文件使用增量解析工具
• 启用缓存以便重复分析
• 考虑分析较小的代码片段

参与贡献

1. Fork 此仓库
2. 创建功能分支：git checkout -b feature-name
3. 进行更改并添加适当的测试
4. 运行测试套件：uv run pytest
5. 提交拉取请求

开发指南

• 遵循 PEP 8 风格指南（由 black 和 flake8 强制执行）
• 为所有公共函数添加类型提示
• 为所有模块、类和函数编写文档字符串
• 为新功能编写测试
• 根据需要更新文档

许可证

MIT 许可证——详情请参阅 LICENSE 文件。

更新日志

v0.2.0

• 添加 pyproject.toml 配置
• 改进与 uv 的兼容性
• 增强缓存系统
• 添加增量解析支持
• 扩展语言支持
• 改进错误处理和日志记录

v0.1.0

• 首次发布
• 基本 AST/ASG 解析
• 集成 Claude Desktop
• 支持 Python 和 JavaScript