MCP Grep

🚀 Grep用MCPサーバー

grep コマンドラインユーティリティを使用して強力なテキスト検索機能を提供する、Model Context Protocol (MCP) サーバーです。このサーバーを使用すると、自然言語による説明と直接的な正規表現パターンの両方を使って、ファイルやディレクトリ内のパターンを検索できます。

✨ 主な機能

🧠 自然言語検索

• 検索対象を平易な英語で記述することができます。
• 自動的に適切な正規表現パターンに変換されます。
• 一般的な検索（メールアドレス、URL、電話番号など）のための組み込みパターンが用意されています。

🔍 高度な検索機能

• 直接的な正規表現パターンのマッチングが可能です。
• ディレクトリを再帰的に検索できます。
• ファイル拡張子でのフィルタリングができます。
• 大文字小文字を区別する/区別しない検索が可能です。
• 単語全体のマッチングができます。
• マッチした行の前後の行を表示できます。
• マッチ数をカウントできます。
• マッチしたファイルを一覧表示できます。

🛡️ セキュリティを重視

• child_process.spawn を使用して安全にコマンドを実行します。
• Zodスキーマを使用して入力を検証します。
• シェルインジェクションの脆弱性がありません。
• パスの検証とサニタイズを行います。

📦 インストール

方法1: NPMを使用したインストール（推奨）

# グローバルにインストール
npm install -g @247arjun/mcp-grep

# または、プロジェクト内にローカルインストール
npm install @247arjun/mcp-grep

方法2: ソースからのインストール

# リポジトリをクローン
git clone https://github.com/247arjun/mcp-grep.git
cd mcp-grep

# 依存関係をインストール
npm install

# プロジェクトをビルド
npm run build

# オプション: グローバルにリンク
npm link

方法3: GitHubから直接インストール

# GitHubから直接インストール
npm install -g git+https://github.com/247arjun/mcp-grep.git

📚 ドキュメント

Claude Desktopの設定

Claude Desktopの設定ファイルに以下を追加します。

場所:

• 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": ["/absolute/path/to/mcp-grep/build/index.js"]
    }
  }
}

設定を追加した後、Claude Desktopを再起動して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. ClaudeにMCPサーバーが表示されない

   • 設定ファイルのJSON構文を検証します。
   • Claude Desktopを完全に再起動します。
   • コマンドのパスが正しいことを確認します。

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スキーマを使用して入力を検証します。
• 指定された対象外のシステムファイルにはアクセスできません。