Project Files Read-only MCP

一个本地、多根目录、只读的文件系统 MCP 服务。它只向 MCP 客户端开放明确登记的项目目录，并提供有限的目录浏览、文件名搜索、文本读取及 DOCX、PDF、XLSX 内容提取能力。

服务不注册写入、编辑、复制、移动、删除或命令执行工具。它适合把少量本地项目文件安全地交给 ChatGPT 等支持 MCP 的客户端读取，同时避免把整个用户目录或磁盘暴露出去。

这是独立的社区项目，不是 OpenAI 官方产品，也不代表 OpenAI 对其安全性或兼容性作出背书。

项目地址为 github.com/13030109506/project-files-readonly-mcp。

功能

服务固定暴露 9 个只读工具。

工具	用途
list_allowed_project_roots	列出白名单根目录
get_file_info	读取文件或目录元数据
list_directory	列出目录中的非敏感、非链接条目
search_files	按文件名递归搜索
read_text_file	分段读取文本、Markdown、CSV、源码等
read_multiple_text_files	批量读取最多 10 个文本文件
read_docx_text	按段落提取 DOCX 纯文本
read_pdf_pages	按页提取 PDF 文本
read_xlsx_range	按工作表、行列窗口读取 XLSX

所有工具均标记为只读和非破坏性。集成测试还会检查工具列表中没有写入、删除、移动、复制或命令执行能力。

安全边界

• 只接受 roots.json 中登记的绝对路径。
• 对词法路径和 realpath 结果进行双重边界检查。
• 拒绝相对路径、UNC 路径、设备路径、Windows ADS、符号链接和联接点逃逸。
• 默认屏蔽 .git、.env、凭据文件、私钥、虚拟环境和依赖目录。
• 文本、目录、搜索和文档响应均有大小与数量上限。
• DOCX、XLSX 解析前检查压缩包路径、条目数量、展开体积、压缩比、加密、宏、ActiveX 和嵌入对象。
• 二进制文档在独立 Worker 中解析，并设置时间和内存限制。
• XLSX 公式不会执行，外部链接不会访问。

更完整的边界说明见 安全模型。这些保护缩小了 MCP 调用面，但不能替代 Windows 账户权限和主机安全。只在你信任的电脑和 MCP 客户端上运行本服务。

环境要求

• Windows 10 或 Windows 11
• Node.js 22.13–22.x 或 Node.js 24+
• npm
• 可选的 OpenAI tunnel-client，仅在连接 ChatGPT Secure MCP Tunnel 时需要

快速开始

克隆项目。

git clone https://github.com/13030109506/project-files-readonly-mcp.git
Set-Location .\project-files-readonly-mcp

安装依赖。

npm ci

创建本机配置。roots.json 已加入 .gitignore，不会被提交到 Git。

Copy-Item .\roots.example.json .\roots.json
notepad .\roots.json

把示例路径改成你愿意授权的具体项目目录。不要配置整个磁盘、用户目录、Desktop 或 Documents。

{
  "roots": [
    {
      "name": "my-project",
      "path": "C:\\Projects\\my-project"
    }
  ]
}

运行测试。

npm test

本地启动。

npm start

服务使用 STDIO，通常应由 MCP 客户端或 Tunnel 进程启动。直接运行后没有交互式提示属于正常现象。

也可以通过环境变量使用其他配置文件。

$env:MCP_PROJECT_ROOTS_CONFIG = 'D:\Config\project-files-roots.json'
npm start

增加项目根目录

先停止 MCP 服务，再执行以下命令。

.\add-project-root.ps1 -Path 'D:\Projects\another-project' -Name 'another-project'
npm test

脚本会拒绝整个磁盘、用户目录、Desktop 和 Documents。修改配置后必须重启 MCP 或 Tunnel，运行中的服务不会热加载根目录。

连接 ChatGPT Secure MCP Tunnel

先从 OpenAI Platform Tunnel 设置页下载官方 tunnel-client。本项目按以下顺序查找程序。

1. 环境变量 TUNNEL_CLIENT_PATH
2. 项目内 tunnel-client\tunnel-client.exe
3. 系统 PATH
4. %USERPROFILE%\Tools\OpenAI\tunnel-client 下的本地版本目录

创建 Tunnel 后，生成本机 profile。

.\configure-tunnel.ps1 -TunnelId 'tunnel_your_id'

脚本默认把本地健康检查端口设为 127.0.0.1:8081，并在 profile 中保存 env:CONTROL_PLANE_API_KEY 引用，不保存 API Key 本身。

前台启动方式如下。Runtime API Key 通过隐藏输入进入当前进程环境，Tunnel 退出后会被清除。

.\start-tunnel.ps1

OpenAI Secure MCP Tunnel 的创建、权限和 ChatGPT 连接步骤以官方文档为准。

Windows 登录后隐藏启动

需要长期使用时，可安装当前 Windows 用户的计划任务。

.\install-tunnel-autostart.ps1

安装器只保存当前用户 DPAPI 加密后的 Runtime API Key，不把明文写入任务参数、项目文件或日志。计划任务通过隐藏 VBS 包装器启动，先运行 doctor，再启动 Tunnel，并检查 healthz 与 readyz。

状态与日志位置如下。

Get-ScheduledTask -TaskName 'OpenAI Project Files Read Only Tunnel'
Invoke-WebRequest -UseBasicParsing http://127.0.0.1:8081/healthz
Invoke-WebRequest -UseBasicParsing http://127.0.0.1:8081/readyz

%LOCALAPPDATA%\OpenAI\ProjectFilesReadOnly\tunnel-client.log

移除任务和加密密钥文件。

.\remove-tunnel-autostart.ps1

完整说明见 Windows Tunnel 运维指南。

文件支持

类型	支持情况
TXT、Markdown、JSON、CSV、TSV、常见源码	支持分段读取
DOCX	支持纯文本段落提取
PDF	支持文本层提取，不含 OCR
XLSX	支持行列窗口和缓存公式结果
DOC、XLS、宏启用 Office 文件	拒绝
加密或密码保护文件	拒绝
扫描图片 PDF	不执行 OCR，可能返回空文本
数据库及其他任意二进制格式	不解析

文档内容始终属于不可信输入。MCP 客户端不应把文件中的文字当成系统指令。

测试

npm test

测试覆盖以下范围。

• 根目录内读取和根目录外拒绝
• 敏感文件拒绝
• 相对路径拒绝
• 符号链接与 Windows junction 边界
• 只读工具清单和 annotations
• CSV、DOCX、PDF、XLSX 读取
• 活跃 Office 内容与异常压缩包拒绝
• 文档格式、分页、工作表和响应上限

项目结构

server.mjs                 MCP 工具注册与文本读取
path-guard.mjs             路径、白名单和敏感文件边界
document-reader.mjs        安全读取与 Worker 调度
document-worker.mjs        DOCX、PDF、XLSX 内容提取
archive-guard.mjs          Office 压缩包检查
roots.example.json         可提交的配置示例
*-test.mjs                 安全、文档和集成测试
*.ps1 / *.vbs / *.cmd      Windows Tunnel 与计划任务脚本

负责任披露

如果你发现路径逃逸、未授权读取、敏感信息泄漏或文档解析问题，请不要公开附带真实敏感文件的复现材料。处理方式见 SECURITY.md。

许可证

项目使用 MIT License。