Codeseeker MCP

🚀 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可以访问指定的目录。

🤝 贡献指南

1. 分叉仓库。
2. 创建功能分支（git checkout -b feature/amazing-feature）。
3. 提交更改（git commit -m 'Add some amazing feature'）。
4. 推送到分支（git push origin feature/amazing-feature）。
5. 打开拉取请求。

📄 许可证

本项目采用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个替换工具）