ast-grep MCP Server

一个实验性的模型上下文协议（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运行

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

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", "/绝对路径到ast-grep-mcp", "run", "main.py"],
      "env": {}
    }
  }
}

对于Claude Desktop

在你的Claude Desktop MCP配置中添加：

{
  "mcpServers": {
    "ast-grep": {
      "command": "uv",
      "args": ["--directory", "/绝对路径到ast-grep-mcp", "run", "main.py"],
      "env": {}
    }
  }
}

自定义ast-grep配置

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

你可以通过以下两种方式之一提供配置文件（按优先级顺序）：

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

使用

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

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

提示会要求LLM使用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"（完整的元数据）

文本输出格式：

找到2个匹配：

path/to/file.py:10-15
def example_function():
    # 函数主体
    return result

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

用例：

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

🚀 find_code_by_rule

使用复杂的YAML规则进行高级代码库搜索，这些规则可以表达复杂的匹配标准。

参数：

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

用例：

• 查找嵌套的代码结构
• 使用关系约束搜索（内部、包含、先于、后于）
• 复杂的多条件搜索

使用示例

基本模式搜索

使用查询：

查找所有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. “命令未找到”错误：确保已安装ast-grep并在PATH中
2. 没有找到匹配项：尝试在关系规则中添加stopBy: end
3. 模式不匹配：使用dump_syntax_tree了解AST结构
4. 权限错误：确保服务器有权读取目标目录

贡献

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

相关项目

• ast-grep - 核心结构化搜索工具
• 模型上下文协议 - 此服务器实现的协议
• FastMCP - 使用的Python MCP框架
• Codemod MCP - 给AI助手提供工具，如tree-sitter AST和节点类型、ast-grep指令（YAML和JS ast-grep）、Codemod CLI命令，以便轻松构建、发布和运行基于ast-grep的codemods。