🚀 CodeSeeker
CodeSeeker是一款先进的代码搜索与转换工具，专为AI助手打造。它融合了ugrep和ast-grep的优势，构建了全面的模型上下文协议（MCP）服务器，为现代开发工作流程提供智能搜索和替换功能。
🚀 快速开始
CodeSeeker为AI助手提供完整的搜索和替换功能，以下是使用前的准备和安装步骤。
✨ 主要特性
🔍 核心搜索工具
- 基础搜索：支持标准模式匹配，可进行文件类型过滤并显示上下文信息。
- 布尔搜索：类似Google搜索，支持使用AND、OR、NOT运算符。
- 模糊搜索：允许字符错误的近似模式匹配。
- 存档搜索：可在压缩文件和存档（如zip、tar、7z等）中进行搜索。
- 交互式搜索：启动ugrep的TUI进行实时搜索。
- 代码结构搜索：可查找函数、类、方法、导入和变量。
🔧 搜索与替换工具
- 搜索并替换：安全的查找和替换功能，支持预运行预览和自动备份。
- 批量替换：可在单个命令中执行多个搜索/替换操作。
- 代码重构：支持多语言的代码结构感知重构。
⚡ 高级特性
- JSON输出：结构化的结果，非常适合AI处理。
- 文件类型过滤：可搜索特定的编程语言或文档类型。
- 上下文行：显示匹配结果周围的行，便于更好地理解。
- 搜索统计：获取搜索操作的详细指标。
- 存档支持：无需解压即可搜索嵌套存档。
- 安全优先：默认启用预运行模式，并自动创建备份。
- 语言感知：支持JavaScript、TypeScript、Python、Java、C++等语言的智能模式。
📦 安装指南
1. 安装ugrep
- Ubuntu/Debian：
sudo apt-get install ugrep
- macOS (Homebrew)：
brew install ugrep
- Windows (Chocolatey)：
choco install ugrep
- 从源代码安装：
git clone https://github.com/Genivia/ugrep.git
cd ugrep
./configure
make
sudo make install
- 验证安装：
ugrep --version
# 应显示版本7.4或更高
2. 安装Node.js
确保安装了Node.js 18或更高版本：
node --version
# 应显示v18.0.0或更高
克隆并构建项目
git clone https://github.com/yourusername/codeseeker-mcp.git
cd codeseeker-mcp
npm install
npm run build
快速测试
npm test
# 应显示所有测试通过
💻 使用示例
基础用法
基础搜索
在JavaScript文件中搜索 "function"：
- 模式：function
- 文件类型：js,ts
- 路径：./src
- 区分大小写：false
布尔搜索
查找紧急但未标记为稍后处理的TODO项：
- 查询：TODO AND urgent -NOT later
- 文件类型：cpp,h,js,py
模糊搜索
查找最多允许2个字符错误的 "function"（匹配 "functoin"、"functio" 等）：
- 模式：function
- 最大错误数：2
- 文件类型：js,ts,py
搜索并替换
将旧函数名替换为新函数名（先进行安全预览）：
- 模式：oldFunctionName
- 替换内容：newFunctionName
- 文件类型：js,ts
- 预运行：true（预览更改）
- 备份：true（创建备份）
批量替换
在一次操作中进行多次替换：
- 将 "var " 替换为 "const "
- 将 "== " 替换为 "=== "
- 文件类型：js,ts
- 预运行：true
代码重构
在代码库中重构函数名：
- 结构类型：function
- 旧模式：getUserData
- 新模式：fetchUserData
- 语言：typescript
- 预运行：true
高级用法
本工具还提供了丰富的API供高级使用场景，以下是部分工具的详细说明。
📚 详细文档
搜索工具
basic_search
标准模式搜索，支持过滤选项。
| 属性 | 详情 |
|---|---|
pattern（必需） |
搜索模式或正则表达式 |
path（可选） |
搜索目录（默认：当前目录） |
caseSensitive（可选） |
区分大小写搜索（默认：false） |
fileTypes（可选） |
逗号分隔的文件类型（如 "js,py,cpp"） |
excludeTypes（可选） |
要排除的文件类型 |
contextLines（可选） |
匹配结果周围的上下文行数 |
maxResults（可选） |
最大结果数（默认：100） |
boolean_search
类似Google的布尔搜索。
| 属性 | 详情 |
|---|---|
query（必需） |
布尔查询（支持AND、OR、NOT、括号） |
path |
同基础搜索 |
fileTypes |
同基础搜索 |
maxResults |
同基础搜索 |
示例查询：
"error AND (critical OR fatal)""TODO AND urgent -NOT completed""function OR method -NOT test"
fuzzy_search
近似模式匹配。
| 属性 | 详情 |
|---|---|
pattern（必需） |
要搜索的模式 |
maxErrors（可选） |
允许的字符错误数（1 - 9，默认：2） |
path |
同基础搜索 |
fileTypes |
同基础搜索 |
maxResults |
同基础搜索 |
archive_search
在压缩文件和存档中搜索。
| 属性 | 详情 |
|---|---|
pattern（必需） |
搜索模式 |
path |
同基础搜索 |
maxResults |
同基础搜索 |
archiveTypes（可选） |
要搜索的存档类型 |
code_structure_search
查找特定的代码结构。
| 属性 | 详情 |
|---|---|
structureType（必需） |
要搜索的结构类型（function、class、method、import、variable） |
name（可选） |
要搜索的特定名称 |
language（必需） |
编程语言（js、ts、py、java、cpp） |
path |
同基础搜索 |
maxResults |
同基础搜索 |
interactive_search
启动交互式TUI模式。
| 属性 | 详情 |
|---|---|
initialPattern（可选） |
初始搜索模式 |
path（可选） |
初始搜索目录 |
替换工具
search_and_replace
安全的查找和替换，支持预览。
| 属性 | 详情 |
|---|---|
pattern（必需） |
搜索模式或正则表达式 |
replacement（必需） |
替换文本（支持 $1、$2 捕获组） |
path（可选） |
要处理的目录（默认：当前目录） |
fileTypes（可选） |
要包含的文件类型 |
caseSensitive（可选） |
区分大小写搜索（默认：false） |
dryRun（可选） |
预览模式（默认：true） |
maxFiles（可选） |
最大处理文件数（默认：50） |
backup（可选） |
创建备份（默认：true） |
bulk_replace
多个搜索/替换操作。
| 属性 | 详情 |
|---|---|
replacements（必需） |
{pattern, replacement, description} 对象数组 |
path |
同搜索并替换 |
fileTypes |
同搜索并替换 |
caseSensitive |
同搜索并替换 |
dryRun |
同搜索并替换 |
backup |
同搜索并替换 |
code_refactor
语言感知的代码重构。
| 属性 | 详情 |
|---|---|
structureType（必需） |
代码结构类型（function、class、variable、import） |
oldPattern（必需） |
要查找的模式 |
newPattern（必需） |
替换模式 |
language（必需） |
编程语言（js、ts、py、java、cpp） |
path |
同搜索并替换 |
dryRun |
同搜索并替换 |
backup |
同搜索并替换 |
实用工具
list_file_types
获取所有支持的文件类型，用于过滤。
get_search_stats
获取详细的搜索统计信息和性能指标。
项目结构
codeseeker-mcp/
├── src/
│ └── index.ts # 主服务器实现
├── build/ # 编译后的JavaScript输出
├── package.json # Node.js依赖和脚本
├── tsconfig.json # TypeScript配置
├── test.js # 测试套件
├── README.md # 本文件
└── SETUP.md # 快速设置指南
构建项目
npm run build # 编译TypeScript
npm run dev # 开发时的监听模式
npm run inspector # 使用MCP检查器进行调试
测试服务器
# 测试基本功能
npm test
# 使用MCP检查器进行交互式测试
npm run inspector
# 使用Claude Desktop进行测试
# （添加到配置文件并重启Claude Desktop）
🔧 技术细节
安全特性
预运行模式
所有替换操作默认启用预运行模式，以确保安全：
- 在应用更改之前预览更改内容。
- 确切了解将修改的内容。
- 避免意外覆盖。
自动备份
进行更改时：
- 自动创建带有时间戳的备份文件。
- 保留原始文件。
- 需要时可轻松回滚。
错误处理
- 提供全面的错误消息。
- 优雅地处理失败情况。
- 检查文件权限。
性能说明
- ugrep速度极快，通常优于其他grep工具。
- JSON输出带来的额外开销极小。
- 存档搜索的速度可能会因压缩方式而异。
- 大结果集受
maxResults参数限制。 - 替换操作通过流式处理高效处理文件。
- 交互式模式需要终端支持，无法通过MCP运行。
🐛 故障排除
常见问题及解决方法
"ugrep not found"
- 确保ugrep已安装并在系统路径中。
- 运行
ugrep --version验证安装。
"Permission denied"
- 确保build/index.js文件可执行。
- 在Unix系统上运行
chmod +x build/index.js。
"Module not found errors"
- 运行
npm install安装依赖项。 - 确保使用的是Node.js 18或更高版本。
"Claude Desktop not showing tools"
- 验证配置文件路径是否正确。
- 更改配置后重启Claude Desktop。
- 检查Claude Desktop日志中的连接错误。
"No files found to process"
- 检查路径是否存在且包含匹配的文件。
- 验证文件类型过滤器是否正确。
- 确保ugrep可以访问指定的目录。
🤝 贡献指南
- 分叉仓库。
- 创建功能分支（
git checkout -b feature/amazing-feature）。 - 提交更改（
git commit -m 'Add some amazing feature'）。 - 推送到分支（
git push origin feature/amazing-feature）。 - 打开拉取请求。
📄 许可证
本项目采用MIT许可证，详情请参阅 LICENSE 文件。
🔗 相关项目
- ugrep - 超快速的grep替代工具。
- ast-grep - 基于AST的代码搜索和重写工具。
- Model Context Protocol - AI数据连接的开放标准。
- Claude Desktop - 支持MCP的AI助手。
📊 工具总结
| 工具 | 用途 | 输入 | 输出 |
|---|---|---|---|
basic_search |
标准文本搜索 | 模式 + 过滤器 | 带上下文的匹配结果 |
boolean_search |
逻辑搜索查询 | 布尔表达式 | 过滤后的结果 |
fuzzy_search |
近似匹配 | 模式 + 错误容忍度 | 模糊匹配结果 |
archive_search |
在压缩文件中搜索 | 模式 + 存档类型 | 存档内容 |
code_structure_search |
查找代码元素 | 结构类型 + 语言 | 代码定义 |
search_and_replace |
查找并替换文本 | 模式 + 替换内容 | 预览/更改内容 |
bulk_replace |
多个替换操作 | 操作数组 | 批量结果 |
code_refactor |
重构代码结构 | 旧/新模式 + 语言 | 重构后的代码 |
interactive_search |
启动TUI模式 | 初始模式 | 要运行的命令 |
list_file_types |
显示支持的类型 | 无 | 可用的文件扩展名 |
get_search_stats |
搜索指标 | 搜索参数 | 性能统计信息 |
CodeSeeker - 每次搜索皆具智慧，每次更改尽显精准。
可用工具总数：11（8个搜索工具 + 3个替换工具）