MCP Explorer

🚀 🔍 項目資源管理器MCP服務器

項目資源管理器MCP服務器是一款強大的模型上下文協議（MCP）服務器，具備高級搜索功能，可用於探索、分析和管理項目文件。它能幫助開發者更高效地導航和分析項目，提供了全面的項目結構分析、代碼搜索、依賴管理和文件操作工具。

🚀 快速開始

將以下配置添加到您的MCP設置中：

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

✨ 主要特性

• 提供全面的項目結構分析、代碼搜索、依賴管理和文件操作工具。
• 具備高級搜索功能，支持正則表達式、文件類型過濾等。
• 能檢測過時的npm包，並提供詳細的分析。
• 提供安全的文件刪除和重命名功能，內置保護機制。

📦 安裝指南

🚀 面向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 - 按類型統計過時包的數量。
• raw - 原始的npm過時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文件。