MCP Explorer

🚀 🔍 Project Explorer MCP Server

高度な検索機能を備え、プロジェクトファイルの探索、分析、管理を行う強力なModel Context Protocolサーバーです。

📦 npmで利用可能: @team-jd/mcp-project-explorer

🚀 クイックスタート

{
  "mcpServers": {
    "project-explorer": {
      "command": "npx",
      "args": ["-y", "@team-jd/mcp-project-explorer", "/your/project/path"]
    }
  }
}

✨ 主な機能

Project Explorer MCP Serverは、プロジェクト構造の分析、コードベースの検索、依存関係の管理、ファイル操作を行う包括的なツールを提供します。開発者にとって、インテリジェントなプロジェクトのナビゲーションと分析機能が必要な場合に最適です。

📦 インストール

🚀 MCPユーザー向け（推奨）

このサーバーをMCP設定構成に追加します。

{
  "mcpServers": {
    "project-explorer": {
      "command": "npx",
      "args": [
        "-y",
        "@team-jd/mcp-project-explorer",
        "/path/to/your/project"
      ]
    }
  }
}

📁 複数ディレクトリへのアクセス:

{
  "mcpServers": {
    "project-explorer": {
      "command": "npx",
      "args": [
        "-y",
        "@team-jd/mcp-project-explorer",
        "/path/to/project1",
        "/path/to/project2",
        "/path/to/project3"
      ]
    }
  }
}

🛠️ 開発者向け

# 開発用にクローンしてセットアップ
git clone https://github.com/MausRundung362/mcp-explorer.git
cd mcp-explorer

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

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

# テスト用にMCPインスペクターを実行
npm run inspector

🛠️ 利用可能なコマンド

📂 explore_project

詳細なファイル情報とインポート/エクスポート分析を伴うプロジェクト構造の分析

// 基本的な使用法
explore_project({
  directory: "/path/to/project"
})

// 高度な使用法
explore_project({
  directory: "/path/to/project",
  subDirectory: "src",           // オプション: 特定のサブディレクトリに焦点を当てる
  includeHidden: false          // オプション: 隠しファイルを含める (デフォルト: false)
})

✨ 機能:

• 📊 人間が読みやすい形式でのファイルサイズ分析
• 🔍 JS/TSファイルのインポート/エクスポート文の検出
• 🚫 ビルドディレクトリ (node_modules, .git, dist など) を自動的に除外
• 📁 再帰的なディレクトリトラバーサル
• 🎯 サブディレクトリ分析のサポート

🔎 search_files

包括的なフィルタリング機能を備えた高度なファイルとコードの検索

// 単純なテキスト検索
search_files({
  pattern: "your search term",
  searchPath: "/path/to/search"
})

// フィルターを使用した高度な検索
search_files({
  pattern: "function.*async",     // 正規表現パターン
  searchPath: "/path/to/search",
  regexMode: true,               // 正規表現を有効にする
  caseSensitive: false,          // 大文字小文字を区別するか
  extensions: [".js", ".ts"],    // 含めるファイルタイプ
  excludeExtensions: [".min.js"], // 除外するファイルタイプ
  excludeComments: true,         // コメントをスキップ
  excludeStrings: true,          // 文字列リテラルをスキップ
  maxResults: 50,                // 結果を制限
  sortBy: "relevance"            // ソート方法
})

🎛️ 検索オプション:

🎯 使用例:

• 🔍 すべてのTODOコメントを検索: pattern: "TODO.*", excludeStrings: true
• 🐛 潜在的なバグを検索: pattern: "console\\.log", regexMode: true
• 📦 インポート文を検索: pattern: "import.*from", regexMode: true
• 🔧 最近の変更を検索: modifiedAfter: "2024-01-01", extensions: [".js", ".ts"]

📊 check_outdated

詳細な分析を伴う古いnpmパッケージのチェック

// 基本的なチェック
check_outdated({
  projectPath: "/path/to/project"
})

// 詳細な分析
check_outdated({
  projectPath: "/path/to/project",
  includeDevDependencies: true,  // 開発依存関係を含める
  outputFormat: "detailed"       // detailed, summary, or raw
})

📋 出力形式:

• detailed - バージョンと更新コマンドを含む完全なパッケージ情報
• summary - タイプ別の古いパッケージの数
• raw - 生のnpm outdated JSON出力

🔧 必要条件:

• Node.jsとnpmがインストールされている必要があります。
• 指定されたディレクトリに有効な package.json が存在する必要があります。

🗑️ delete_file

保護メカニズムを備えたファイルまたはディレクトリの安全な削除

// ファイルを削除
delete_file({
  path: "/path/to/file.txt"
})

// ディレクトリを削除 (再帰フラグが必要)
delete_file({
  path: "/path/to/directory",
  recursive: true,              // ディレクトリの場合は必須
  force: false                  // 読み取り専用ファイルを強制削除
})

⚠️ 安全機能:

• 🔒 許可されたディレクトリ内でのみ動作します。
• 📁 空でないディレクトリの場合は recursive: true が必要です。
• 🛡️ 誤削除からの保護
• ⚡ 読み取り専用ファイルの強制削除オプション

✏️ rename_file

ファイルとディレクトリの名前変更または移動

// 単純な名前変更
rename_file({
  oldPath: "/path/to/old-name.txt",
  newPath: "/path/to/new-name.txt"
})

// 別のディレクトリに移動
rename_file({
  oldPath: "/path/to/file.txt",
  newPath: "/different/path/file.txt"
})

✨ 機能:

• 📁 ファイルとディレクトリの両方で動作します。
• 🔄 ディレクトリ間で移動できます。
• 🚫 移動先が既に存在する場合は失敗します。
• 🔒 両方のパスは許可されたディレクトリ内にある必要があります。

📋 list_allowed_directories

サーバーがアクセスできるディレクトリを表示

list_allowed_directories()

🔧 使用例:

• 🔍 操作前にアクセス許可を確認する
• 🛡️ セキュリティ検証
• 📂 ディレクトリの探索

💻 使用例

📊 プロジェクト分析ワークフロー

// 1. アクセスできるディレクトリを確認する
list_allowed_directories()

// 2. プロジェクト構造を探索する
explore_project({
  directory: "/your/project/path",
  includeHidden: false
})

// 3. 特定のパターンを検索する
search_files({
  pattern: "useState",
  searchPath: "/your/project/path",
  extensions: [".jsx", ".tsx"],
  excludeComments: true
})

// 4. 古い依存関係を確認する
check_outdated({
  projectPath: "/your/project/path",
  outputFormat: "detailed"
})

🔍 高度な検索シナリオ

// すべての非同期関数を検索する
search_files({
  pattern: "async\\s+function",
  regexMode: true,
  extensions: [".js", ".ts"]
})

// 最近変更された大きなファイルを検索する
search_files({
  pattern: ".*",
  minSize: 1000000,  // 1MB以上
  modifiedAfter: "2024-01-01",
  sortBy: "size"
})

// テストファイルを除外してTODOコメントを検索する
search_files({
  pattern: "TODO|FIXME|BUG",
  regexMode: true,
  excludePatterns: ["*test*", "*spec*"],
  excludeStrings: true
})

🛡️ セキュリティとパーミッション

サーバーは許可されたディレクトリ内でのみ動作し、以下の機能を提供します。

• 🔒 サンドボックス化されたアクセス - 許可されたパス外のファイルにアクセスできません。
• 🛡️ 安全な操作 - 危険な操作からの組み込み保護
• 📂 パスの検証 - すべてのパスは正規化され、検証されます。
• ⚠️ エラーハンドリング - パーミッションの問題に対する明確なエラーメッセージ

🔧 開発

📁 プロジェクト構造

src/
├── index.ts              # メインサーバーのエントリポイント
├── explore-project.ts    # プロジェクト分析ツール
├── search.ts            # 高度な検索機能
├── check-outdated.ts   # NPM依存関係チェッカー
├── delete-file.ts       # ファイル削除ツール
├── rename-file.ts       # ファイルの名前変更/移動ツール
└── list-allowed.ts      # ディレクトリパーミッションチェッカー

🏗️ ビルドコマンド

npm run build     # TypeScriptをコンパイル
npm run watch     # 開発用のウォッチモード
npm run inspector # MCPインスペクターでテスト

🤝 コントリビュート

1. 🍴 リポジトリをフォークする
2. 🌟 機能ブランチを作成する
3. 💻 変更を加える
4. ✅ 十分にテストする
5. 🚀 プルリクエストを送信する

📄 ライセンス

詳細については LICENSE ファイルを参照してください。