Directory Browser MCP Server (TypeScript)

一个使用 Node.js + TypeScript 编写的 Model Context Protocol (MCP) 服务器，用于安全地浏览与打开本地目录。新版实现了 ROOTS 协议，可以向客户端暴露经过白名单校验的根目录列表。

特性

• 📁 目录浏览：列出指定目录的文件与子目录，支持隐藏文件过滤与数量限制
• 📄 详细信息：获取文件/目录的尺寸、时间戳、权限等元数据
• 🔍 权限检查：检测目标路径的读/写/执行权限，并返回安全策略结论
• 🗂️ ROOTS 协议：通过 ROOTS 动态暴露安全的根目录，方便客户端挂载
• 🛡️ 安全防护：内置白名单、路径穿越校验与跨平台兼容处理
• 🖥️ 目录打开：在系统文件管理器中直接打开已校验的目录

环境要求

• Node.js 18+
• npm 或 pnpm / yarn 等兼容包管理器

安装与构建

# 安装依赖
npm install

# 构建 TypeScript 输出到 dist/
npm run build

# 作为 MCP 服务器运行（STDIO 传输）
npm start

开发调试可使用：

npm run dev

配置

服务器启动时会按以下优先级查找 config.json：

1. 当前工作目录：./config.json
2. 项目目录：dist/../config.json
3. 用户目录：~/.directory_browser_mcp/config.json

配置示例：

{
  "allowed_directories": [
    "/Users/your-name",
    "/Users/your-name/Documents",
    "/Users/your-name/Desktop"
  ],
  "show_hidden_files": false,
  "max_entries": 1000
}

字段说明：

• allowed_directories：允许访问的根目录集合（绝对路径）
• show_hidden_files：缺省是否展示隐藏文件
• max_entries：单次目录列出的最大条目数

若未提供配置，将自动回退到用户主目录、Documents、Desktop 与 Downloads 的默认白名单。

可用工具

| 工具名 | 描述 | 参数 | | --- | --- | --- | | list_directory | 列出目录内容 | path (必填)、show_hidden (选填) | | get_file_info | 获取文件/目录详细信息 | path (必填) | | check_path_access | 检查路径访问权限 | path (必填) | | open_directory | 在系统文件管理器中打开目录 | path (必填) |

所有工具都会先经过安全白名单校验，未通过时会直接返回拒绝原因。

运行方式

构建后可直接使用 dist/index.js（已在 package.json 的 bin 字段中声明），或将其集成到支持 MCP 的代理/客户端。STDIO 传输由 @modelcontextprotocol/sdk 提供的 StdioServerTransport 完成。

旧的 Python 实现已移至 python_src/ 目录，可按需参考或清理。

License

MIT