MCP Explorer

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

項目資源管理器MCP服務器是一款強大的模型上下文協議（MCP）服務器，具備高級搜索功能，可用於探索、分析和管理項目文件，為開發者提供智能的項目導航和分析能力。

🚀 快速開始

你可以通過以下配置將此服務器添加到MCP設置中：

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

✨ 主要特性

項目資源管理器MCP服務器提供了全面的工具，用於分析項目結構、搜索代碼庫、管理依賴項和執行文件操作，非常適合需要智能項目導航和分析功能的開發者。

📦 安裝指南

🚀 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 文件。