CodeSeeker

AI助手的高级代码搜索与转换工具

一个全面的模型上下文协议（MCP）服务器，结合了ugrep和ast-grep的理念，提供现代开发工作流程中的智能搜索和替换功能。

<a href="https://glama.ai/mcp/servers/@mixelpixx/CodeSeeker-MCP"> <img width="380" height="200" src="https://gips1.baidu.com/it/u=3080440621,1344487166&fm=3081&app=3081&f=PNG?w=760&h=400" alt="CodeSeeker-MCP MCP服务器" /> </a>

🚀 特性

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
# 应该显示所有测试通过

⚙️ 配置

Claude Desktop集成

添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "codeseeker": {
      "command": "node",
      "args": ["/绝对路径/codeseeker-mcp/build/index.js"]
    }
  }
}

注意: 将/绝对路径/codeseeker-mcp替换为您实际的安装路径。

📖 使用示例

基础搜索

在JavaScript文件中搜索"function":
- 模式: function
- 文件类型: js,ts
- 路径: ./src
- 区分大小写: false

布尔搜索

查找标记为urgent但未标记为later的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

🔧 工具参考

搜索工具

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: 同search_and_replace

code_refactor

语言感知的代码重构。

参数:

• structureType (必需): 代码结构类型（function, class, variable, import）
• oldPattern (必需): 要查找的模式
• newPattern (必需): 替换模式
• language (必需): 编程语言（js, ts, py, java, cpp）
• path, dryRun, backup: 同search_and_replace

实用工具

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未找到"

• 确保ugrep已安装并在PATH中
• 运行ugrep --version以验证安装

"权限被拒绝"

• 确保build/index.js文件是可执行的
• 运行chmod +x build/index.js（在Unix系统上）

"模块未找到错误"

• 运行npm install以安装依赖
• 确保您使用的是Node.js 18或更高版本

"Claude Desktop未显示工具"

• 验证配置文件路径是否正确
• 在更改配置后重启Claude Desktop
• 检查Claude Desktop日志中的连接错误

"未找到要处理的文件"

• 检查路径是否存在且包含匹配文件
• 验证文件类型过滤器是否正确
• 确保ugrep可以访问指定目录

⚡ 性能说明

• ugrep非常快速，通常超越其他grep工具
• JSON输出增加的开销极小
• 归档搜索可能根据压缩情况较慢
• 大的结果集由maxResults参数限制
• 替换操作高效地处理文件流
• 交互模式需要终端，不能通过MCP运行

🤝 贡献

1. 分叉仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m '添加一些惊人的功能')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开Pull Request

📄 许可证

MIT许可证 - 详情参见LICENSE文件。

🔗 相关项目

• ugrep - 超快的grep替代品
• ast-grep - 基于AST的代码搜索和重写工具
• 模型上下文协议 - 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替换)