Codeseeker MCP

🚀 CodeSeeker

CodeSeekerは、現代の開発ワークフローにおけるインテリジェントな検索と置換機能を提供する包括的なModel Context Protocol (MCP)サーバーです。ugrepと[ast - grep](https://github.com/ast - grep/ast - grep)の哲学を融合し、AIアシスタントに高度なコード検索と変換機能を提供します。

🚀 クイックスタート

CodeSeekerはAIアシスタントに完全な検索と置換機能を提供します。以下のセクションでは、その機能や使い方、インストール方法などを詳しく説明します。

✨ 主な機能

🔍 核心な検索ツール

• 基本検索：ファイルタイプフィルタリングとコンテキスト付きの標準的なパターンマッチング
• ブール検索：AND、OR、NOT演算子を使用したGoogleライクな検索
• ファジー検索：文字の誤りを許容する近似パターンマッチング
• アーカイブ検索：圧縮ファイルやアーカイブ（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（バックアップを作成する）

一括置換

1つの操作で複数の置換を行う:
- "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 not found"

• ugrepがインストールされていて、PATHに含まれていることを確認してください。
• 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が指定されたディレクトリにアクセスできることを確認してください。

⚡ パフォーマンスに関する注意

• 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ライセンス - 詳細についてはLICENSEファイルを参照してください。

🔗 関連プロジェクト

• ugrep - 超高速なgrep代替ツール
• [ast - grep](https://github.com/ast - grep/ast - grep) - ASTベースのコード検索と書き換えツール
• Model Context Protocol - AIデータ接続のオープン標準
• Claude Desktop - MCPをサポートするAIアシスタント

📊 ツールの概要

CodeSeeker - すべての検索に知性を、すべての変更に精度を。

利用可能なツールの総数: 11 (8つの検索ツール + 3つの置換ツール)