代码搜索与转换工具

CodeSeeker

AI助手的高级代码搜索和转换

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

🚀 特性

CodeSeeker为AI助手提供完整的搜索和替换功能：

🔍 核心搜索工具

• 基本搜索：与文件类型筛选和上下文进行标准模式匹配
• 布尔搜索：使用AND、OR、NOT运算符进行类似谷歌的搜索
• 模糊搜索：允许字符错误的近似模式匹配
• 档案搜索：搜索压缩文件和存档（zip、tar、7z等）
• 交互式搜索：启动ugrep的TUI进行实时搜索
• 代码结构搜索：查找函数、类、方法、导入和变量

🔧 搜索和替换工具

• 搜索和替换：使用模拟运行预览和自动备份进行安全查找和替换
• 批量更换：在单个命令中执行多个搜索/替换操作
• 与全面的程式重整：跨多种语言的代码结构的语言感知重构

⚡ 高级功能

• JSON输出：结构化结果非常适合人工智能处理
• 文件类型筛选：搜索特定的编程语言或文档类型
• 上下文行：显示周围的线条以更好地理解
• 搜索统计信息：获取有关搜索操作的详细指标
• 存档支持：搜索嵌套存档而不提取
• 安全第一：默认情况下为模拟运行模式，自动创建备份
• 语言意识：JavaScript、TypeScript、Python、Java、C的智能模式++

📋 先决条件

1.安装ugrep

Ubuntu/Debian：

sudo apt-get install ugrep

macOS（Homebrew）：

brew install ugrep

窗户（巧克力）：

choco install ugrep

来源：

git clone https://github.com/Genivia/ugrep.git
cd ugrep
./configure
make
sudo make install

验证安装：

ugrep --version
# Should show version 7.4 or higher

2.安装Node.js

确保您已安装Node.js 18+：

node --version
# Should show v18.0.0 or higher

🛠️ 安装

克隆和构建

git clone https://github.com/yourusername/codeseeker-mcp.git
cd codeseeker-mcp
npm install
npm run build

快速测试

npm test
# Should show all tests passing

⚙️ 配置

Claude桌面集成

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

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

{
  "mcpServers": {
    "codeseeker": {
      "command": "node",
      "args": ["/absolute/path/to/codeseeker-mcp/build/index.js"]
    }
  }
}

备注：替换 /absolute/path/to/codeseeker-mcp 安装的实际路径。

📖 使用示例

基本搜索

Search for "function" in JavaScript files:
- Pattern: function
- File Types: js,ts
- Path: ./src
- Case Sensitive: false

布尔搜索

Find TODO items that are urgent but not marked as later:
- Query: TODO AND urgent -NOT later
- File Types: cpp,h,js,py

模糊搜索

Find "function" with up to 2 character errors (matches "functoin", "functio", etc.):
- Pattern: function  
- Max Errors: 2
- File Types: js,ts,py

搜索和替换

Replace old function names with new ones (safe preview first):
- Pattern: oldFunctionName
- Replacement: newFunctionName
- File Types: js,ts
- Dry Run: true (preview changes)
- Backup: true (create backups)

批量更换

Multiple replacements in one operation:
- Replace "var " with "const "
- Replace "== " with "=== " 
- File Types: js,ts
- Dry Run: true

与全面的程式重整

Refactor function names across a codebase:
- Structure Type: function
- Old Pattern: getUserData
- New Pattern: fetchUserData
- Language: typescript
- Dry Run: true

🔧 工具参考

搜索工具

basic_search

带过滤选项的标准模式搜索。

参数：

• pattern （必填）：搜索模式或正则表达式
• path （可选）：要搜索的目录（默认：当前目录）
• caseSensitive （可选）：区分大小写的搜索（默认值：false）
• fileTypes （可选）：逗号分隔的文件类型（例如“js、py、cpp”）
• excludeTypes （可选）：要排除的文件类型
• contextLines （可选）：围绕匹配的上下文行
• maxResults （可选）：最大结果（默认值：100）

boolean_search

使用布尔运算符进行类似谷歌的搜索。

参数：

• 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 （必填）：要搜索的类型（函数、类、方法、导入、变量）
• 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 （必填）：代码结构类型（函数、类、变量、导入）
• 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          # Main server implementation
├── build/                # Compiled JavaScript output
├── package.json          # Node.js dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── test.js              # Test suite
├── README.md            # This file
└── SETUP.md             # Quick setup guide

建筑

npm run build           # Compile TypeScript
npm run dev            # Watch mode for development
npm run inspector      # Debug with MCP inspector

测试服务器

# Test basic functionality
npm test

# Use MCP inspector for interactive testing
npm run inspector

# Test with Claude Desktop
# (Add to config and restart 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 'Add some amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

📄 许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

🔗 相关项目

• ugrep -超快速grep替换
• ast grep -基于AST的代码搜索和重写工具
• 模型上下文协议 -AI数据连接的开放标准
• 克劳德桌面 -支持MCP的AI助手

📊 工具摘要

CodeSeeker-每一次搜索都充满智慧，每一次更改都精准无误。

可用工具总数：11 （8次搜索+3次替换）