⚙

代码结构搜索服务

ast-grep MCP Server 是一个实验性的模型上下文协议服务器，为AI助手提供基于抽象语法树（AST）的代码结构搜索功能，支持多种编程语言的复杂模式匹配。

作者 By ast-grep
本地部署 代码搜索 AST匹配
GitHub

ast grep MCP服务器

一个实验 模型上下文协议（MCP） 服务器，为AI助手提供强大的结构化代码搜索功能，使用 ast grep.

概述

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

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

先决条件

  1. 安装ast grep：关注 astgrep安装指南

BASH``` 1 2 3 4# macOS brew install ast-grep nix-shell -p ast-grep cargo install ast-grep —locked

2. **安装uv**：Python包管理器


BASH```
1curl -LsSf https://astral.sh/uv/install.sh | sh
  1. MCP兼容客户端：例如Cursor、Claude Desktop或其他MCP客户端

安装

  1. 克隆此存储库：

BASH``` 1 2git clone https://github.com/ast-grep/ast-grep-mcp.git cd ast-grep-mcp

2. 安装依赖项：


BASH```
1uv sync
  1. 验证ast grep安装：

BASH``` 1ast-grep —version



## 跑步 `uvx`


您可以使用以下命令直接从GitHub运行服务器 `uvx`:


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

这对于在不克隆存储库的情况下快速试用服务器非常有用。

配置

对于光标

添加到MCP设置（通常在 .cursor-mcp/settings.json):

JSON``` 1 2 3 4 5 6 7 8 9{ “mcpServers”: { “ast-grep”: { “command”: “uv”, “args”: [“—directory”, “/absolute/path/to/ast-grep-mcp”, “run”, “main.py”], “env”: {} } } }


### 适用于克劳德桌面


添加到您的Claude Desktop MCP配置中：


JSON```
1
2
3
4
5
6
7
8
9{
  "mcpServers": {
    "ast-grep": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/ast-grep-mcp", "run", "main.py"],
      "env": {}
    }
  }
}

自定义ast-grep配置

MCP服务器支持使用自定义 sgconfig.yaml 配置astgrep行为的文件。 看 astgrep配置文档 有关配置文件格式的详细信息。

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

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

用法

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

您可以将其添加到游标规则或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" （完整元数据）

文本输出格式：

1
2
3
4
5
6
7
8Found 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" （完整元数据）

使用案例：

  • 查找嵌套代码结构
  • 使用关系约束（内、有、前、后）进行搜索
  • 复杂的多条件搜索

用法示例

基本模式搜索

使用查询：

查找所有console.log语句

AI将生成如下规则：

YAML``` 1 2 3 4id: find-console-logs language: javascript rule: pattern: console.log($$$)


### 复杂规则示例


用户查询：


> 查找使用wait的异步函数


AI将生成如下规则：


YAML```
1
2
3
4
5
6
7
8
9
10id: async-with-await
language: javascript
rule:
  all:
    - kind: function_declaration
    - has:
        pattern: async
    - has:
        pattern: await $EXPR
        stopBy: end

支持的语言

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

  • JavaScript/TypeScript
  • python
  • 锈
  • 去
  • Java
  • C/C++
  • C
  • 还有更多。…

有关内置支持语言的完整列表，请参阅 astgrep语言支持文档.

您还可以通过添加对自定义语言的支持 sgconfig.yaml 配置文件。看 自定义语言指南 了解详情。

故障排除

常见问题

  1. “找不到命令”错误：确保ast grep已安装并位于您的PATH中
  2. 未找到匹配项：尝试添加 stopBy: end 关系规则
  3. 图案不匹配：使用 dump_syntax_tree 了解AST结构
  4. 权限错误：确保服务器具有对目标目录的读取权限

贡献

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

相关项目

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