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

💻 使用示例

基础用法

// 探索项目结构
explore_project({
  directory: "/path/to/project"
})

// 简单文本搜索
search_files({
  pattern: "your search term",
  searchPath: "/path/to/search"
})

// 检查过时的npm包
check_outdated({
  projectPath: "/path/to/project"
})

// 删除文件
delete_file({
  path: "/path/to/file.txt"
})

// 重命名文件
rename_file({
  oldPath: "/path/to/old-name.txt",
  newPath: "/path/to/new-name.txt"
})

// 列出允许访问的目录
list_allowed_directories()

高级用法

// 探索项目结构（指定子目录并包含隐藏文件）
explore_project({
  directory: "/path/to/project",
  subDirectory: "src",
  includeHidden: true
})

// 高级文件搜索
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"
})

// 详细的过时npm包检查
check_outdated({
  projectPath: "/path/to/project",
  includeDevDependencies: true,
  outputFormat: "detailed"
})

// 删除目录
delete_file({
  path: "/path/to/directory",
  recursive: true,
  force: false
})

// 移动文件到不同目录
rename_file({
  oldPath: "/path/to/file.txt",
  newPath: "/different/path/file.txt"
})

📚 详细文档

🛠️ 可用命令

📂 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
• 🐛 搜索潜在的bug：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
})

📋 输出格式：

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