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个替换工具）