Directory Browser MCP Server (TypeScript)

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

特性

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

环境要求

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

安装与构建

``bash


安装依赖

npm install

构建 TypeScript 输出到 dist/

npm run build

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

npm start
`

开发调试可使用：

`bash
npm run dev
`

配置

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

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

配置示例：

`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