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