MCP Grep

🚀 Grep的MCP服務器

這是一個基於grep命令行工具的模型上下文協議（MCP）服務器，具備強大的文本搜索能力。支持使用自然語言描述和直接的正則表達式模式在文件和目錄中搜索指定模式。

🚀 快速開始

本項目是一個模型上下文協議（MCP）服務器，它藉助grep命令行工具，提供強大的文本搜索能力。你可以使用自然語言描述或直接的正則表達式模式，在文件和目錄中進行搜索。

✨ 主要特性

🧠 自然語言搜索

• 能用簡潔的英文描述搜索內容。
• 自動將自然語言轉換為合適的正則表達式模式。
• 內置常見搜索模式（如電子郵件、URL、電話號碼等）。

🔍 高級搜索功能

• 支持直接的正則表達式模式匹配。
• 可遞歸搜索目錄。
• 能按文件擴展名過濾。
• 支持區分大小寫或不區分大小寫搜索。
• 支持全詞匹配。
• 可顯示匹配上下文行。
• 能統計匹配數量。
• 可列出包含匹配項的文件。

🛡️ 安全至上

• 使用child_process.spawn安全執行命令。
• 利用Zod模式進行輸入驗證。
• 無shell注入漏洞。
• 對路徑進行驗證和清理。

📦 安裝指南

方法一：NPM安裝（推薦）

# 全局安裝
npm install -g @247arjun/mcp-grep

# 或在項目中本地安裝
npm install @247arjun/mcp-grep

方法二：從源碼安裝

# 克隆倉庫
git clone https://github.com/247arjun/mcp-grep.git
cd mcp-grep

# 安裝依賴
npm install

# 構建項目
npm run build

# 可選：全局鏈接
npm link

方法三：直接從GitHub安裝

# 直接從GitHub安裝
npm install -g git+https://github.com/247arjun/mcp-grep.git

📚 詳細文檔

配置

Claude桌面設置

將以下內容添加到Claude桌面配置文件中： 位置：

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

配置內容：

{
  "mcpServers": {
    "mcp-grep": {
      "command": "mcp-grep",
      "args": []
    }
  }
}

替代方法：使用npx（無需全局安裝）

{
  "mcpServers": {
    "mcp-grep": {
      "command": "npx",
      "args": ["@247arjun/mcp-grep"]
    }
  }
}

本地開發設置

{
  "mcpServers": {
    "mcp-grep": {
      "command": "node",
      "args": ["/絕對路徑/mcp-grep/build/index.js"]
    }
  }
}

添加配置後，重啟Claude桌面以加載MCP服務器。

驗證

測試服務器是否正常工作：

# 測試構建好的服務器
node build/index.js

# 應顯示："Grep MCP Server running on stdio"
# 按Ctrl+C退出

可用工具

1. grep_search_intent

使用自然語言描述進行搜索。 參數：

• intent（字符串）：簡潔的英文描述（如 "email addresses", "TODO comments"）
• target（字符串）：要搜索的文件或目錄路徑
• case_sensitive（布爾值，可選）：區分大小寫搜索（默認：false）
• max_results（數字，可選）：限制結果數量
• show_context（布爾值，可選）：顯示周圍的行（默認：false）
• context_lines（數字，可選）：上下文行數（默認：2）

示例：

{
  "intent": "email addresses",
  "target": "./src",
  "show_context": true,
  "context_lines": 1
}

2. grep_regex

使用直接的正則表達式模式進行搜索。 參數：

• pattern（字符串）：正則表達式模式
• target（字符串）：要搜索的文件或目錄路徑
• case_sensitive（布爾值，可選）：區分大小寫搜索
• whole_words（布爾值，可選）：僅匹配全詞
• invert_match（布爾值，可選）：顯示不匹配的行
• max_results（數字，可選）：限制結果數量
• show_context（布爾值，可選）：顯示上下文行
• context_lines（數字，可選）：上下文行數量
• file_extensions（數組，可選）：按文件擴展名過濾

示例：

{
  "pattern": "function\\s+\\w+\\s*\\(",
  "target": "./src",
  "file_extensions": ["js", "ts"],
  "show_context": true
}

3. grep_count

統計模式的匹配數量。 參數：

• pattern（字符串）：要統計的模式
• target（字符串）：搜索目標
• case_sensitive（布爾值，可選）：區分大小寫
• whole_words（布爾值，可選）：全詞匹配
• by_file（布爾值，可選）：顯示每個文件的匹配數量
• file_extensions（數組，可選）：文件擴展名過濾

4. grep_files_with_matches

列出包含指定模式的文件。 參數：

• pattern（字符串）：搜索模式
• target（字符串）：要搜索的目錄
• case_sensitive（布爾值，可選）：區分大小寫
• whole_words（布爾值，可選）：全詞匹配
• file_extensions（數組，可選）：要包含的文件擴展名
• exclude_patterns（數組，可選）：要排除的文件模式

5. grep_advanced

使用自定義參數執行grep（適用於高級用戶）。 參數：

• args（數組）：grep參數數組（不包括 'grep' 本身）

內置自然語言模式

服務器識別以下自然語言意圖：

通信

• "email", "email address", "emails" → 電子郵件地址模式
• "url", "urls", "website", "link", "links" → URL模式
• "phone", "phone number", "phone numbers" → 電話號碼模式

網絡

• "ip", "ip address", "ip addresses" → IPv4地址模式

數據類型

• "number", "numbers", "integer", "integers" → 數字模式
• "date", "dates" → 日期模式

代碼模式

• "function", "functions" → 函數聲明
• "class", "classes" → 類定義
• "import", "imports" → 導入語句
• "export", "exports" → 導出語句
• "comment", "comments" → 註釋行
• "todo", "todos" → TODO/FIXME/HACK註釋

錯誤模式

• "error", "errors" → 錯誤消息
• "warning", "warnings" → 警告消息

💻 使用示例

在項目中搜索電子郵件地址

{
  "tool": "grep_search_intent",
  "intent": "email addresses",
  "target": "./src",
  "show_context": true
}

查找所有TODO註釋

{
  "tool": "grep_search_intent", 
  "intent": "todo comments",
  "target": "./",
  "file_extensions": ["js", "ts", "py"]
}

使用正則表達式搜索函數定義

{
  "tool": "grep_regex",
  "pattern": "^\\s*function\\s+\\w+",
  "target": "./src",
  "file_extensions": ["js"]
}

統計單詞出現次數

{
  "tool": "grep_count",
  "pattern": "async",
  "target": "./src",
  "by_file": true
}

列出包含導入語句的文件

{
  "tool": "grep_files_with_matches",
  "pattern": "^import",
  "target": "./src",
  "file_extensions": ["js", "ts"]
}

開發

構建和運行

# 開發時自動重建
npm run dev

# 生產環境構建
npm run build

# 啟動服務器
npm start

項目結構

mcp-grep/
├── src/
│   └── index.ts          # 主服務器實現
├── build/                # 編譯後的JavaScript輸出
├── package.json          # 項目配置
├── tsconfig.json         # TypeScript配置
└── README.md            # 本文件

故障排除

常見問題

1. "Command not found" 錯誤

   • 確保全局安裝了mcp-grep：npm install -g @247arjun/mcp-grep
   • 或使用npx："command": "npx", "args": ["@247arjun/mcp-grep"]

2. "Permission denied" 錯誤

   • 檢查文件權限：chmod +x build/index.js
   • 重新構建項目：npm run build

3. MCP服務器未在Claude中顯示

   • 驗證配置文件中的JSON語法。
   • 完全重啟Claude桌面。
   • 檢查命令路徑是否正確。

4. "grep command not found"

   • 在系統上安裝grep（通常macOS/Linux預裝）。
   • Windows用戶：通過WSL安裝或使用Git Bash。

調試

通過設置環境變量啟用詳細日誌記錄：

# 開發時使用
DEBUG=1 node build/index.js

# 使用示例輸入進行測試
echo '{"jsonrpc": "2.0", "method": "initialize", "params": {}}' | node build/index.js

🔧 技術細節

• 使用spawn且shell: false來防止命令注入。
• 在執行前驗證所有文件路徑。
• 在高級模式下阻止潛在危險的grep標誌。
• 使用Zod模式進行輸入驗證。
• 不允許訪問指定目標之外的系統文件。

📄 許可證

文檔中未提及相關信息。