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個替換工具）