Ast Grep

ast-grep MCP 服务

一个实验性的 Model Context Protocol（MCP） 服务，使用 ast-grep 为 AI 助手提供强大的结构化代码搜索能力。

概述

此 MCP 服务使 AI 助手（如 Cursor、Claude Desktop 等）能够使用抽象语法树（AST）模式匹配来搜索和分析代码库，而不是进行简单的文本搜索。借助 ast-grep 的结构化搜索能力，AI 可以：

• 根据语法结构（而不只是文本匹配）查找代码模式
• 搜索特定的编程结构（函数、类、导入等）
• 使用 YAML 配置编写和测试复杂的搜索规则
• 调试并可视化 AST 结构，以便更好地开发模式

前提条件

1. 安装 ast-grep：请按照 ast-grep 安装指南操作

   # macOS
   brew install ast-grep
   nix-shell -p ast-grep
   cargo install ast-grep --locked
   

2. 安装 uv：Python 包管理器

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

3. 兼容 MCP 的客户端：例如 Cursor、Claude Desktop 或其他 MCP 客户端

安装

1. 克隆此仓库：

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

2. 安装依赖项：

   uv sync
   

3. 验证 ast-grep 是否已安装：

   ast-grep --version
   

使用 uvx 运行

你可以使用 uvx 直接从 GitHub 运行此服务：

uvx --from git+https://github.com/ast-grep/ast-grep-mcp ast-grep-server

这样可以快速试用此服务，无需克隆仓库。

配置

用于 Cursor

将以下内容添加到 MCP 设置中（通常位于 .cursor-mcp/settings.json）：

{
  "mcpServers": {
    "ast-grep": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/ast-grep-mcp", "run", "main.py"],
      "env": {}
    }
  }
}

用于 Claude Desktop

将以下内容添加到 Claude Desktop 的 MCP 配置中：

{
  "mcpServers": {
    "ast-grep": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/ast-grep-mcp", "run", "main.py"],
      "env": {}
    }
  }
}

自定义 ast-grep 配置

此 MCP 服务支持使用自定义的 sgconfig.yaml 文件来配置 ast-grep 的行为。 有关配置文件格式的详细信息，请参阅 ast-grep 配置文档。

你可以通过以下两种方式提供配置文件（优先级依次降低）：

1. 命令行参数：--config /path/to/sgconfig.yaml
2. 环境变量：AST_GREP_CONFIG=/path/to/sgconfig.yaml

自定义 ast-grep 命令

如果 ast-grep 不在 PATH 中，或者必须通过其他命令启动，请设置 AST_GREP_PATH。其值可以是可执行文件路径，也可以是命令前缀：

{
  "mcpServers": {
    "ast-grep": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/ast-grep-mcp", "run", "main.py"],
      "env": {
        "AST_GREP_PATH": "uv run ast-grep"
      }
    }
  }
}

其他示例：

• AST_GREP_PATH="/custom/path/to/ast-grep"
• AST_GREP_PATH="npx ast-grep"
• AST_GREP_PATH='"/path containing spaces/ast-grep"'

如果未设置，该命令默认为 ast-grep。

用法

此仓库在 ast-grep.mdc 中提供了全面的 ast-grep 规则文档。文档涵盖编写有效 ast-grep 规则的各个方面，从简单模式到复杂的多条件搜索。

你可以将其添加到 Cursor 规则或 Claude.md 中，并在需要 AI Agent 为你创建 ast-grep 规则时附上它。

提示词会要求大模型使用 MCP 创建、验证并改进所编写的规则。

功能

此服务提供四种主要的代码分析工具：

🔍 dump_syntax_tree

可视化代码片段的抽象语法树结构。这对于理解如何编写有效的搜索模式至关重要。

使用场景：

• 调试模式未能匹配的原因
• 理解目标代码的 AST 结构
• 学习 ast-grep 模式语法

🧪 test_match_code_rule

在将 ast-grep YAML 规则应用于更大的代码库之前，先针对代码片段进行测试。

使用场景：

• 验证规则是否按预期运行
• 迭代开发规则
• 调试复杂的匹配逻辑

🎯 find_code

使用简单的 ast-grep 模式搜索代码库，查找简单的结构匹配项。

参数：

• max_results：限制返回的完整匹配项数量（默认：不限）
• output_format：可选 "text"（默认，令牌数约减少 75%）或 "json"（完整元数据）

文本输出格式：

Found 2 matches:

path/to/file.py:10-15
def example_function():
    # function body
    return result

path/to/file.py:20-22
def another_function():
    pass

使用场景：

• 查找符合特定模式的函数调用
• 定位变量声明
• 搜索简单的代码结构

🚀 find_code_by_rule

使用复杂的 YAML 规则搜索代码库，可表达精细的匹配条件。

参数：

• max_results：限制返回的完整匹配项数量（默认：不限）
• output_format：可选 "text"（默认，令牌数约减少 75%）或 "json"（完整元数据）

使用场景：

• 查找嵌套代码结构
• 使用关系约束进行搜索（inside、has、precedes、follows）
• 执行复杂的多条件搜索

使用示例

基本模式搜索

使用以下查询：

查找所有 console.log 语句

AI 将生成类似这样的规则：

id: find-console-logs
language: javascript
rule:
  pattern: console.log($$$)

复杂规则示例

用户查询：

查找使用 await 的异步函数

AI 将生成类似这样的规则：

id: async-with-await
language: javascript
rule:
  all:
    - kind: function_declaration
    - has:
        pattern: async
    - has:
        pattern: await $EXPR
        stopBy: end

支持的语言

ast-grep 支持多种编程语言，包括：

• JavaScript/TypeScript
• Python
• Rust
• Go
• Java
• C/C++
• C#
• 以及更多……

如需查看内置支持语言的完整列表，请参阅 ast-grep 语言支持文档。

你也可以通过 sgconfig.yaml 配置文件添加对自定义语言的支持。详情请参阅自定义语言指南。

故障排除

常见问题

1. “Command not found” 错误：确保已安装 ast-grep，且其位于 PATH 中
2. 未找到匹配项：尝试在关系规则中添加 stopBy: end
3. 模式不匹配：使用 dump_syntax_tree 了解 AST 结构
4. 权限错误：确保服务具有读取目标目录的权限

贡献

这是一个实验性项目。欢迎提交问题和拉取请求！

相关项目

• ast-grep - 核心结构搜索工具
• Model Context Protocol - 此服务实现的协议
• MCP Python SDK - 所使用的 Python MCP 框架
• Codemod MCP - 为 AI 助手提供 tree-sitter AST 和节点类型、ast-grep 指南（YAML 和 JS ast-grep），以及 Codemod CLI 命令等工具，帮助轻松构建、发布和运行基于 ast-grep 的 codemod。