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