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或更高版本
• 紫外线 包管理器（推荐）或pip

使用紫外线（推荐）

1. 克隆此存储库：

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

1. 安装项目和依赖项：

# 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

1. 构建树状图解析器：

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
• 窗户： %APPDATA%\claude-desktop\claude_desktop_config.json

1. 添加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 使用系统上的实际绝对路径。

1. 重新启动Claude Desktop以加载新的MCP服务器。

1. 在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. 安装相应的树状图语言包：

uv add tree-sitter-

1. 更新 LANGUAGE_MODULES 字典在 build_parsers.py 和 ast_mcp_server/tools.py.

1. 构建解析器：

uv run build-parsers

当前支持的语言

• python (tree-sitter-python)
• JavaScript (tree-sitter-javascript)
• TypeScript (tree-sitter-typescript)
• 去 (tree-sitter-go)
• 锈 (tree-sitter-rust)
• C (tree-sitter-c)
• C (tree-sitter-cpp)
• Java (tree-sitter-java)

运作原理

AST MCP服务器通过模型上下文协议（MCP）与Claude Desktop连接：

1. 初始化：Claude Desktop使用以下命令启动服务器 uv run 具有适当的工作目录
2. 语言加载：服务器加载树型语言模块，用于解析各种编程语言
3. MCP注册：它使用MCP协议注册工具和资源
4. 分析：Claude可以访问这些工具来分析您共享的代码或本地文件。工具设计得很稳健：它们可以智能地从本地读取 filename 如果提供的代码是占位符，则返回路径。
5. 缓存：结果在本地缓存以提高性能

所有工具的执行都在您的机器上本地进行，结果将返回给Claude进行解释和帮助。

配置文件

• pyproject.toml：项目元数据、依赖关系和工具配置
• claude_desktop_config.json：克劳德桌面配置示例
• 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桌面连接问题

1. 验证Claude Desktop配置中的绝对路径
2. 确保uv在您的系统PATH中
3. 检查Claude Desktop日志中的错误消息
4. 配置更改后重新启动Claude Desktop

性能问题

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

贡献

1. 克隆该仓库
2. 创建要素分支： git checkout -b feature-name
3. 通过适当的测试进行更改
4. 运行测试套件： uv run pytest
5. 提交拉取请求

开发指南

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

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

更新日志

v0.2.0版本

• 添加了pyproject.toml配置
• 改善紫外线兼容性
• 增强型缓存系统
• 添加了增量解析支持
• 扩展语言支持
• 更好的错误处理和日志记录

v0.1.0

• 初始版本
• 基本AST/ASG解析
• Claude桌面集成
• 支持Python和JavaScript