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

💻 使用例

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

// 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
})

📚 詳細ドキュメント

🛠️ 利用可能なコマンド

📂 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()

🔧 使用例:

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

🔧 技術詳細

📁 プロジェクト構造

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 ファイルを参照してください。