ast grep MCP服务器（Swift）
概述
此MCP服务器使AI助手（如Cursor、Claude Desktop等）能够使用抽象语法树（AST）模式匹配而不是简单的基于文本的搜索来搜索和分析代码库。通过利用ast grep的结构化搜索功能，AI可以：
- 基于语法结构查找代码模式，而不仅仅是文本匹配
- 搜索特定的编程构造（函数、类、导入等）
- 使用YAML配置编写和测试复杂的搜索规则
- 调试和可视化AST结构，以更好地开发模式
先决条件
- 安装ast grep：关注 astgrep安装指南
# macOS
brew install ast-grep
nix-shell -p ast-grep
cargo install ast-grep --locked- Swift工具链：Swift 6.2（或Xcode 26+）来构建/运行服务器
- MCP兼容客户端：例如Cursor、Claude Desktop或其他MCP客户端
安装
- 克隆此存储库：
git clone https://github.com/ast-grep/ast-grep-mcp-swift.git
cd ast-grep-mcp-swift- 一次构建（下载SwiftPM deps，如MCP Swift SDK和Yams）：
swift build- 验证ast grep安装：
ast-grep --version跑步
通过stdio启动MCP服务器：
swift run ast-grep-mcp-swift --config /absolute/path/to/sgconfig.yaml
swift run ast-grep-mcp-swift --verbose --config /absolute/path/to/sgconfig.yaml # verbose debug logs to stderr
swift run ast-grep-mcp-swift --version # print version information你可以省略 --config 如果您依赖默认值或 AST_GREP_CONFIG 环境变量。
快速本地测试
- 确保
ast-grep在路径上：ast-grep --version - 构建一次：
swift build - 运行服务器（stdio）：
swift run ast-grep-mcp-swift - 从支持MCP的客户端调用
tools/list然后tools/call使用下面的工具之一。
使用预构建版本（macOS）
- 首选 发布 并下载名为的资产
ast-grep-mcp-swift-vX.Y.Z-macOS-universal加上它.sha256. - 验证校验和（可选但推荐）：
shasum -a 256 -c ast-grep-mcp-swift-vX.Y.Z-macOS-universal.sha256 - 使其可执行：
chmod +x ast-grep-mcp-swift-vX.Y.Z-macOS-universal - 运行：
./ast-grep-mcp-swift-vX.Y.Z-macOS-universal --config /absolute/path/to/sgconfig.yaml
- 或者将其移动到您的路径中（例如。， /usr/local/bin/ast-grep-mcp-swift).
- 将MCP客户端指向该二进制文件（请参阅下面的Cursor/Claude示例）。
配置
对于光标
添加到MCP设置（通常在 .cursor-mcp/settings.json):
{
"mcpServers": {
"ast-grep": {
"command": "swift",
"args": ["run", "ast-grep-mcp-swift", "--config", "/absolute/path/to/sgconfig.yaml"],
"env": {}
}
}
}适用于克劳德桌面
添加到您的Claude Desktop MCP配置中：
{
"mcpServers": {
"ast-grep": {
"command": "swift",
"args": ["run", "ast-grep-mcp-swift", "--config", "/absolute/path/to/sgconfig.yaml"],
"env": {}
}
}
}自定义ast-grep配置
MCP服务器支持使用自定义 sgconfig.yaml 配置astgrep行为的文件。 请参阅 astgrep配置文档 有关配置文件格式的详细信息。
您可以通过两种方式提供配置文件（按优先级顺序）：
- 命令行参数:
--config /path/to/sgconfig.yaml - 环境变量:
AST_GREP_CONFIG=/path/to/sgconfig.yaml
用法
您可以将自己的ast-grep规则文档附加到MCP客户端；服务器工具(dump_syntax_tree, test_match_code_rule)帮助您快速迭代。
特性
服务器提供了四种主要的代码分析工具：
🔍 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"（完整元数据）
使用案例：
- 查找嵌套代码结构
- 使用关系约束（内、有、前、后）进行搜索
- 复杂的多条件搜索
使用示例
基本模式搜索
使用查询：
查找所有console.log语句
AI将生成如下规则：
id: find-console-logs
language: javascript
rule:
pattern: console.log($$$)复杂规则示例
用户查询：
查找使用wait的异步函数
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
- 锈
- 去
- Java
- C/C++
- C
- 还有更多。..
有关内置支持语言的完整列表，请参阅 astgrep语言支持文档.
您还可以通过添加对自定义语言的支持 sgconfig.yaml 配置文件。请参阅 自定义语言指南 了解详情。
故障排除
常见问题
- “找不到命令”错误：确保ast grep已安装并位于您的PATH中
- 未找到匹配项：尝试添加
stopBy: end关系规则 - 图案不匹配：使用
dump_syntax_tree了解AST结构 - 权限错误：确保服务器具有对目标目录的读取权限
贡献
这是一个实验项目。欢迎问题和拉取请求！作为原始Python服务器的Swift端口构建：https://github.com/ast-grep/ast-grep-mcp.
相关项目
- ast grep -核心结构搜索工具
- 模型上下文协议 -此服务器实现的协议
- MCP Swift SDK -此服务器使用的Swift实现
- Codemod MCP -为AI助手提供树保姆AST和节点类型、AST grep指令（YAML和JS AST grep）和Codemod CLI命令等工具，以轻松构建、发布和运行基于AST grep的codemods。