Code AST MCP 服务器（code-ast-mcp）

code-ast-mcp 是一个基于 Python 原生抽象语法树（ast）解析器构建的架构型 Model Context Protocol (MCP) 服务器。它允许 AI 模型（在 Claude Desktop、Cursor、Antigravity 或自定义 MCP 客户端中）分析本地 Python 代码结构、搜索符号定义、构建依赖关系图、审计文档字符串覆盖率，并完成代码重构，而无需将完整的原始源文件加载到 LLM 上下文窗口中。

🔗 在线仓库：https://github.com/m-sameerkhan/code-ast-mcp
🔗 Smithery 注册中心：https://smithery.ai/servers/sameerbalouch758/code-ast-mcp

⚡ 功能与特性

🛠️ 工具

1. analyze_file_ast(file_path: str)

   • 将 .py 文件解析为清晰的 AST 大纲。

   • 提取模块文档字符串、行数、导入语句、顶层函数、类、方法和变量。

2. find_class_methods(file_path: str, class_name: str)

   • 定位特定类，并返回其方法函数、类型注解、行范围和文档字符串。

3. find_symbol(target_dir: str, symbol_name: str)

   • 递归搜索目录，查找匹配 symbol_name 的类、函数、方法或变量赋值。

4. get_imports_graph(target_dir: str)

   • 扫描 Python 文件以构建依赖关系导入图，并输出 Mermaid 图 字符串。

5. find_missing_docstrings(target_dir: str, include_private: bool = False)

   • 审计代码库的文档字符串，并计算整体文档字符串覆盖率百分比。

📝 提示词（Prompts）

• refactor_code_summary(file_path: str)

  • 生成一个结构化提示词，指令 LLM 审查文件的 AST 大纲，并提出重构、设计模式改进和文档修复建议。

📊 资源

• codeast://stats

  • 实时 JSON 资源，提供工作区统计信息（扫描的文件总数、文档字符串覆盖率百分比、缺失项数量）。

Related MCP server: codeweave-mcp

🚀 快速开始与安装

方式 1：通过 Smithery CLI 安装

smithery mcp add sameerbalouch758/code-ast-mcp

方式 2：从源码安装

克隆仓库并以可编辑模式安装依赖：

git clone https://github.com/m-sameerkhan/code-ast-mcp.git
cd code-ast-mcp

# Create & activate virtual environment (or Conda)
python -m venv .venv
# On Windows:
.venv\Scripts\activate
# On macOS/Linux:
source .venv/bin/activate

# Install project and dependencies
pip install -r requirements.txt
pip install -e .

方式 3：打包为 MCP Bundle（.mcpb）

适用于支持 MCP Bundle 的桌面客户端（例如 Claude Desktop）：

# Install MCPB toolchain
npm install -g @anthropic-ai/mcpb

# Build bundle
mcpb pack . code-ast-mcp.mcpb

🧪 本地测试

运行单元测试

pytest

使用 MCP Inspector 测试

使用官方 MCP Inspector 的交互方式测试工具和资源：

npx @modelcontextprotocol/inspector python -m code_ast_mcp.server

⚙️ 客户端配置

Claude Desktop / Cursor / Antigravity 集成

将 code-ast-mcp 添加到你的客户端配置文件（claude_desktop_config.json 或 mcp_config.json）中：

{
  "mcpServers": {
    "code-ast-mcp": {
      "command": "python",
      "args": [
        "-m",
        "code_ast_mcp.server"
      ],
      "cwd": "/path/to/code-ast-mcp"
    }
  }
}

注意：Windows 用户可以将 "command" 指向虚拟环境或 Conda 的 Python 路径（例如 C:/Users/<Username>/.conda/envs/code-ast-mcp/python.exe 或 D:/my_mcp/.venv/Scripts/python.exe）。

📦 项目结构

code-ast-mcp/
├── code_ast_mcp/          # Core package
│   ├── __init__.py        # Package exports
│   ├── analyzer.py        # Python AST parsing & static analysis engine
│   └── server.py          # FastMCP server definition & tool handlers
├── tests/                 # Test suite
│   └── test_analyzer.py   # Unit tests with pytest
├── manifest.json          # MCPB extension manifest
├── smithery.yaml          # Smithery registry configuration
├── Dockerfile             # Container image definition
├── pyproject.toml         # Packaging & metadata
└── requirements.txt       # Dependencies

📄 许可证

MIT License. Created by m-sameerkhan。