FolderBridge MCP

简体中文 | English

[!TIP] FolderBridge 本身是一个单文件 Windows 应用：直接下载 FolderBridge.exe 并双击运行即可。无需安装 Python 或 Node.js。 该二进制文件位于 GitHub Releases → latest release → Assets 中；它不会出现在仓库的源文件列表中。对于网页版 ChatGPT，FolderBridge 仍使用 OpenAI 单独分发的官方 tunnel-client.exe；启动器会引导你选择该文件。你也可以打开完整发布页面获取 EXE 及其可选的 SHA-256 校验文件。

一个更安全、本地优先的桥梁，连接 AI 客户端与你明确选择的少量文件夹。

FolderBridge MCP 是一个零依赖的 Python MCP 服务器，外加一个桌面启动器。它允许网页版 ChatGPT——或任何支持本地 stdio MCP 的客户端——检查并谨慎编辑一个有边界的本地工作区。它刻意避免使用公共 HTTP 服务器、任意 shell 访问、遥测和静默后台服务。

[!IMPORTANT] 本项目处于早期公开测试阶段。它缩小了攻击面，但并非操作系统级沙箱。只暴露你信任的文件夹和仓库。

0.5.1 亮点

• 浏览器授权的 GitHub 发布： 新的内置 git-publisher 扩展可以通过 Git Credential Manager 打开 GitHub 授权，将 OAuth 凭据保存在 Windows 凭据管理器中，仅提交显式的文件白名单，并且只将当前分支推送到现有的 GitHub HTTPS 远端。模型不会接触到任何 token/PAT/密码字段。

• Git 发布仍受约束： Publisher 会拒绝预先存在的暂存更改、凭据/密钥类文件、转换内容的 Git attributes 以及不安全的仓库本地 Git 设置；它从不运行 git add .，从不接受任意 remote/ref，在其有边界的提交中禁用 hooks/签名，并且从不强制推送。

• 原生 Microsoft Office 可视化管线： 内置的 office 扩展可以使用本地安装的 Microsoft Office 渲染 .pptx、.docx 和 .xlsx。PowerPoint 直接将幻灯片导出为 PNG；Word/Excel 使用其原生固定版式引擎和 Windows PDF 渲染器生成页面 PNG。

• 无需启动 Word 即可读取 Word 结构： inspect_docx 从 OOXML 中暴露段落、样式/编号、表格、节/页面设置、页眉/页脚、媒体、超链接、脚注/尾注和批注。

• 无需启动 Excel 即可读取 Excel 结构/公式： inspect_xlsx 暴露工作表、有边界的单元格区域、公式及缓存值、合并区域、隐藏行/列、定义名称、计算设置和外部链接部件。

• 可审计的输出： 原生渲染可以写入确定性的 PNG 目录及同级 ZIP，并返回 Office 源文件和生成输出的 SHA-256/大小元数据；现有的 image_open 工具随后可以可视化检查每个页面或 ZIP 成员。

• Office 自动化受约束： 只接受工作区相对的非链接路径；排除启用宏的格式；强制禁用 Office 自动化宏；文件以只读方式打开；禁用 Excel 链接更新；内置的 PowerShell 脚本是固定的，从不接受任意命令。

• 现有 0.4.x 安全/UI 改进保持不变： 高 DPI 滚动、ComfyUI 托管服务诊断、稳定的扩展网关、有边界的全局能力和单文件 Windows 交付均未改变。

完整的发布历史请参阅 CHANGELOG.md，托管服务和插件边界请参阅 Extension ABI v1。

Related MCP server: mcp-readonly-code-server

为什么选择 FolderBridge？

• 独立的文件夹边界： 一个连接最多可包含八个规范工作区；每次多工作区工具调用都选择 workspace_id，而不是合并根目录。

• 默认只读： 在启动器中显式切换到读/写模式。

• 冲突安全的编辑： 现有文件需要上次读取返回的 SHA-256；过期的编辑会失败，而不是覆盖更新的工作。

• 无任意 shell： 可选任务是有名称的、经过本地审查的，并通过精确的配置哈希批准。

• 无公共监听： MCP 服务器仅使用 stdio。

• 无遥测： FolderBridge 本身不发出任何网络请求。

• 密钥感知的启动器： OpenAI Runtime API 密钥只保存在内存中，并在本地 MCP 进程可以使用它之前被移除。

• 对初学者友好的桌面 UI： 添加/删除文件夹列表、全局访问模式、Tunnel 设置、诊断、启动/停止、进程监控和脱敏日志都集中在一个窗口中。

• Windows 缩放支持： 字体和窗口大小跟随当前显示 DPI，并在不同缩放因子的显示器之间移动时刷新。

快速开始

要求取决于你如何使用 FolderBridge：

• 独立 Windows EXE： 无需单独安装 Python 或 Node.js；Windows 是经过测试的双击启动器环境。

• 从源码运行/开发： 需要 Python 3.11 或更高版本；Python 3.11 x64 是推荐的 Windows 构建基线。

• 项目能力： 只安装工作区本身所需的工具链（例如 Node/npm 项目的测试/构建脚本需要 Node.js LTS）。启用某项能力并不会安装该工具链。

• Git 是可选的。有边界的 status/diff 视图在可用时使用 Git；Git Publisher 扩展额外要求安装带 Git Credential Manager 的 Git for Windows，以进行浏览器授权的 GitHub 提交/推送。

Windows 可执行文件 — 推荐

从最新 GitHub 发布 Assets 下载单个 FolderBridge.exe，或直接下载 EXE。该二进制文件不会出现在仓库的源文件列表中。FolderBridge.exe 是完整的 FolderBridge 应用，已包含其 Python 运行时，因此普通 EXE 用户无需安装 Python 或 Node.js。旁边的 FolderBridge.exe.sha256 文件是可选的，仅用于完整性验证。

这个单文件可执行文件刻意不重新打包 OpenAI 独立发布的 tunnel-client；请从 OpenAI 的发布中单独下载官方客户端，并且仅在使用网页版 ChatGPT 时在启动器中选择 tunnel-client.exe。

[!NOTE] 当前的社区构建未进行代码签名，因此 Windows 会将其发布者标识为未知。如果你不信任未签名的二进制文件，请改为从经过审计的源码构建。

从源码运行

克隆仓库并启动 GUI：

git clone https://github.com/MoonTzai/folderbridge-mcp.git
cd folderbridge-mcp
python .\folderbridge_launcher.py gui

添加你所需的工作区，首次运行保持选中 Read only，并使用状态面板完成设置。启动器偏好设置存储在仓库之外；Runtime API 密钥从不保存。旧的单工作区设置会自动迁移到第一个列表条目中。

folderbridge_gui.pyw 作为仅源码的便利文件保留，适用于 .pyw 关联指向带 Tkinter 解释器的 Python 安装。独立的 FolderBridge.exe 是受支持的双击入口点。

可选的开发与项目工具链

这些不是正常使用 FolderBridge.exe 的前提条件：

• 对于源码开发或重新构建 Windows EXE，请从官方 Python Windows 下载 安装 Python 3.11 x64，并验证 python --version。打包流程使用隔离的 .build-venv 和 requirements-build.txt。

• 仅当目标 Node/npm 工作区需要 node/npm 运行其自身的测试或构建命令时，才从官方 Node.js 下载 安装 Node.js LTS；用 node --version 和 npm --version 验证。

• 其他项目可能需要自己的运行时或编译器。FolderBridge 能力提供授权和有边界的发现/执行，而非依赖安装。

连接网页版 ChatGPT

ChatGPT 无法直接连接到本地 stdio 进程。FolderBridge 使用 OpenAI 官方的 Secure MCP Tunnel 来实现此路径。你需要：

[!IMPORTANT] Secure MCP Tunnel 只需要本机出站 HTTPS（默认端口 443），不需要面向互联网的入站端口。切勿为 FolderBridge 启用 Windows 远程桌面、路由器端口转发、DMZ、UPnP 映射或端口 3389；它们都不是 Tunnel 设置的一部分。如果防火墙询问入站访问，不要为了 Tunnel 工作而创建宽泛的公共入站规则。

• 来自 OpenAI Platform Tunnel 设置 的 tunnel_id；

• 来自同一组织的 Runtime API Keys 中用于 tunnel-client 的密钥；

• 官方的 tunnel-client；

• 适合你账户或工作区的 ChatGPT 开发者模式访问权限。

点击启动器右上角的 连接设置向导 可查看与下方相同的步骤和快捷方式，包括可选的 Python/Node 附录。

1. 下载官方 Windows x64 客户端

[!WARNING] 只下载完整的 tunnel-client-v<version>-windows-amd64.zip 压缩包。切勿下载或选择 tunnel-client-runtime-* 文件。 Runtime 文件是内部组件，不实现设置所需的 init 命令；它们相似的文件名仍可能导致"配置失败"。解压完整压缩包后，只选择名称恰好为 tunnel-client.exe 的主程序。

1. 打开最新的 openai/tunnel-client 发布 并展开 Assets。

2. 下载名为 tunnel-client-v<version>-windows-amd64.zip 的完整压缩包。在发布文件名中，amd64 表示 Windows x64，适用于大多数 Intel/AMD 电脑。

3. 可选下载 SHA256SUMS.txt 用于验证。不要选择 tunnel-client-runtime-*、windows-arm64、all.zip、源代码压缩包或许可证文件；Runtime 压缩包不能替代完整客户端。

4. 将整个 ZIP 解压到稳定的文件夹；没有安装程序，也不应在压缩包内运行。向导可以创建并打开 %LOCALAPPDATA%\FolderBridge\bin 作为推荐位置。

5. 返回 FolderBridge，点击 选择已解压的 EXE，只选择名称恰好为 tunnel-client.exe 的文件。

2. 创建 Platform Tunnel

打开 OpenAI Platform Tunnel 设置，点击 Create tunnel，并使用以下当前选项：

创建后，复制以 tunnel_ 开头的 Tunnel ID。运行和选择该 Tunnel 需要 Tunnels Read + Use 权限；创建或编辑它还需要 Manage 权限。仅关联需要访问此本地工作区的组织和 ChatGPT 工作区。

在同一 Platform 组织的 Runtime API Keys 下为 tunnel-client 创建密钥；密钥创建者需要 Tunnels Read + Use 权限。请只把它粘贴到 FolderBridge 中，密钥会保留在进程内存中。不要使用 Admin API 密钥，也不要把 Runtime 密钥填入 ChatGPT 应用的 Authentication 字段。

3. 启动 FolderBridge

1. 添加一个或多个明确的本地工作区文件夹（最多八个），首次运行保持 只读（推荐）。全局访问模式适用于列出的所有文件夹。

2. 从完整压缩包中选择 tunnel-client.exe，绝不能选 tunnel-client-runtime-* 组件；使用默认的 folderbridge 配置文件即可。

3. 输入相同的 Tunnel ID 和 Runtime API 密钥。还可以按需一次性启用所需的全局能力；除非你想用自定义命令，否则请保持按工作区的高级命名任务为禁用状态。

4. 点击 Start connection。启动器会运行官方 init、doctor、run 流程。仅当顶部状态显示 运行中（Running）后再继续。如果之后再更改文件夹或访问模式，请再次点击 应用配置（Apply configuration）；启动器会更新它自己管理的同一个 profile。

4. 创建 ChatGPT 开发模式应用

打开 ChatGPT Plugins，点击 +，并采用下列关键选择：

在 Server URL 中不要保留默认的 OAuth 选项，也不要粘贴 https://tunnel-service... 地址。FolderBridge 未实现用户 OAuth，因此这样的配置会产生 does not implement OAuth 错误。

在 ChatGPT 对话中调用该应用

1. 保持 FolderBridge 状态为 运行中（Running），然后新开一个 ChatGPT 对话。

2. 点击输入框旁的 +，打开 More（更多），选择刚创建的 FolderBridge 应用。

3. 发送一个类似这样的任务：“First use FolderBridge server_info to list the available workspaces, then read the root of the workspace I name.” 在批准任何工具确认之前，检查其中的 workspace_id 和文件指向。

该入口遵循 OpenAI 官方的 connect and test guidance。启动器的连接指南中包含相同步骤以及可一键复制的示例提示词。

保持启动器在 ChatGPT 使用工作区期间持续运行。关闭启动器会停止 Tunnel 进程。账户级别的开发模式和安装确认仍会留在 ChatGPT 中；FolderBridge 不会自动化你的浏览器会话或安全设置。

不需要浏览器扩展。FolderBridge 有意不静默下载或执行来自网络的二进制文件。

连接另一个本地 MCP 客户端

可以。FolderBridge 的兼容边界是其标准 MCP stdio server。ChatGPT Tunnel 只是为无法直接拉起本地进程的 Web 客户端提供的桥梁。MCP stdio 传输也是如此：客户端负责启动服务端子进程，并通过标准输入输出交换 JSON-RPC。 MCP stdio specification

客户端要求

• 能配置一个本地 command + args 对，并持续管理子进程。

• 支持基于 stdio 的 MCP，保持 stdout 只用于协议消息。

• 能发现并调用 MCP 工具（initialize、tools/list、tools/call，或现代 2026-07-28 discovery 流程）。

• 在会话结束时关闭 stdin 或终止子进程。

• 优先选择带工具确认 UX 的客户端，但不要将确认对话框当作唯一的安全边界。

FolderBridge 目前支持 2024-11-05、2025-03-26、2025-06-18、2025-11-25 和 2026-07-28 协议。它返回 standard tool schemas、text content 和 structuredContent；是否出现确认提示取决于客户端。 MCP Tools specification

最短本地连接步骤

1. 在 FolderBridge 中添加一个或多个工作区，并保持 Read-only（推荐）。

2. 打开 连接设置向导 的第 5 页，复制 JSON、TOML 或完整的 stdio 命令。

3. 把它粘贴到客户端的 MCP 服务端设置中；按其精确字段名遵循客户端文档。

4. 重新启动或刷新客户端，确认 server_info 和 workspace 出现。

直接 stdio 连接不需要 tunnel-client、Tunnel ID、Runtime API 密钥或正在运行的 FolderBridge GUI。客户端在需要时启动以下命令：

FolderBridge.exe serve --workspace C:\path\to\repo --read-only

重复 --workspace 来添加文件夹，同时保持各根目录独立：

FolderBridge.exe serve --workspace C:\work\frontend --workspace C:\work\backend --read-only

从源码生成可直接粘贴的配置：

python .\folderbridge_launcher.py client-config --workspace C:\path\to\repo --format json --read-only
python .\folderbridge_launcher.py client-config --workspace C:\path\to\repo --format toml --read-only
python .\folderbridge_launcher.py client-config --workspace C:\path\to\repo --format tunnel --read-only

JSON 输出遵循 mcpServers 约定，被许多桌面客户端普遍采用：

{
  "mcpServers": {
    "folderbridge": {
      "command": "C:\\Tools\\FolderBridge.exe",
      "args": ["serve", "--workspace", "C:\\work\\frontend", "--workspace", "C:\\work\\backend", "--read-only"]
    }
  }
}

[!IMPORTANT] JSON/TOML 顶层键是常见约定，不是客户端的强制要求。兼容性的本质是：客户端把 command/args 按 MCP stdio 子进程原样启动。如果客户端只接受 URL，则此版本没有内置 HTTP/SSE 监听器；不要将临时本地端口直接公网暴露。

如需协议版本、进程生命周期、cwd/env、批准边界和远端桥接细节，请查看 client-compatibility research。

工具与编辑工作流

内置的 server tools 不依赖 per-workspace 任务配置：

• server_info：报告每个可用工作区的名称、稳定的 workspace_id、内置/全局能力和安全边界；

• workspace：在所选 workspace_id 中列出、读取、搜索并显示有界 Git 状态/diff 输出；

• file_info：返回二进制文件的有界元数据和 SHA-256；

• pptx_inspect：检查 PPTX 文本、OOXML 图表关系和 SmartArt 数据，不执行 Office 内容；

• image_open：向 MCP 客户端返回有界的 PNG/JPEG/GIF/WebP 图片内容，包括 ZIP 中的准确 image member；

• extension：稳定的 list / info / run 网关，用于热加载扩展；在新引擎里插件本身设置不会增加 MCP 工具名称；

• edit_file：在读/写模式下，在所选工作区内创建或精确编辑 UTF-8 文件。

当只有一个工作区时，现有客户端可以继续省略 file_schema 中的 workspace_id。当有多个工作区时，workspace 作用域内的工具需要 server_info 返回的 workspace_id；缺失或未知 ID 会被拒绝。重复的根目录、父子重叠以及超过八项的列表都会在启动前被拒绝。

一个安全编辑循环是：

1. 列出或搜索文件；

2. 读取它并保留返回的 SHA-256；

3. 用这个哈希提交精确替换内容；

4. 检查 Git diff。

服务器不能删除或移动文件。绝对值路径、..、符号链接、junction/reparse point、VCS 内部、常见的依赖/构建目录以及凭据类似的名称都会被拒绝。

全局预授权能力

启动器可以一次性为当前和未来的所有工作区授权常用能力：test、build、package-windows、package-android 和 git-push。这些权限与 .folderbridge.json 不同，它们会出现在 launcher 设置中，因此一个工作区即使在加入几个月后新增了支持的 build 脚本，FolderBridge 也会在调用时检测到。启动器会置于该组提供了 Select all 和 Clear 控件。

git-push 是一个 low-level 高级较低权限，仅 allow 向 GitHub HTTPS origin 推当前分支、不能强制推送，也不能进行 仓库内 credential helper / push-target 重写配置。对于需要浏览器授权并 提交/推送明确文件的场景，请使用内置的 Git Publisher 扩展。build/package 能力可能会执行本地项目代码，所以请只启用你真正需要的全局能力。

对于直接 stdio 客户端，请在 serve 或 client-config 命令中重复 --capability <name>。Windows launcher 将这组 capability 显示为持久复选框。

扩展

FolderBridge Extension ABI v1 是未来添加全局集成的首选方式，例如 ComfyUI、FFmpeg、Blender、Ollama、ADB 或其他本地工具，而无需改变 MCP tool catalog。Windows launcher 有一个默认折叠的 Extensions 侧栏，它会热扫描 user extension directory，显示 installed/approved/loaded 状态，并在 Tunnel 保持连接的状态下让你批准或禁用插件。

每个扩展是一个目录，至少包含 folderbridge-extension.json 和 plugin.py。外部插件会按照整个插件目录的精确 SHA-256，加上声明的权限列表进行批准；更改任何文件或权限都会使批准失效。扩展在一个独立的子进程中运行，带有清理过的环境、有界协议 I/O 和声明的超时时间。这使得崩溃和协议污染被隔离，但两者都不是 OS 安全沙箱：对于不受信任的插件代码，请使用 VM/容器。

工作区特定的适配应使用 workspace_adapter.mode=dynamic 配合 detect.any_of / detect.all_of。FolderBridge 会在调用时重新评估这些模式，因此扩展在安装后无需注入 .folderbridge.json 任务，并且可以在项目后续变更后变得适用。持久化插件状态应使用提供的配置文件状态目录，而不是污染仓库。

ComfyUI 是第一个内置扩展。其状态操作会检查固定的回环端点 127.0.0.1:8188；工作流执行需要在 Extensions 侧边栏中进行一次性批准。在 FolderBridge 0.4.1 中，Windows 启动器还可以自行管理本地 ComfyUI 进程：只需选择一次受支持的 Portable 根目录（python_embeded\\python.exe + ComfyUI\\main.py）或源码根目录（main.py + .venv\\Scripts\\python.exe / venv\\Scripts\\python.exe），启动器即可使用显式的 Python/main.py 参数、shell=False 以及固定的 127.0.0.1:8188 绑定来自动启动它。如果该端点在 FolderBridge 启动它之前已经在线，则该服务会被标记为外部服务并复用，而不是重复启动。

托管服务的所有权有意比扩展权限更严格。FolderBridge 只存储 install_root 和 auto_start，从不存储 PID 或任意命令。只有当前启动器运行所创建的内存中 Popen 句柄才被视为已拥有且可停止。FolderBridge 从不运行用户为 ComfyUI 选择的 BAT/CMD，也从不仅仅因为某个未知进程占用 8188 端口就去查找或终止它。退出时，它会在 Tunnel/MCP 之前停止已拥有的托管服务；外部 ComfyUI 保持运行。

在 Windows 上，启动器会请求 Per-Monitor DPI V2 感知，并轮询当前窗口 DPI 作为轻量级回退方案。固定 GUI 度量仅在 DPI 实际变化时才根据其原始逻辑尺寸（dpi / 96）重新计算，因此从 96 → 144 → 96 DPI 的移动不会累积缩放漂移。

ABI v1 插件应使用 FolderBridge 打包的模块和 Python 标准库，而不是假设单文件 EXE 内存在任意的 pip 依赖。额外的软件通常应通过精确的回环 API 或声明的 process.execute:<basename> 依赖来访问。运行 FolderBridge.exe extensions --json 可检查打包的可执行文件能够发现什么。连接指南附录包含完整格式，以及一个一键式 LLM 插件开发提示，它会告诉模型请求/上传缺失的 API 文档、脚本、工作流、示例文件或项目结构，而不是猜测。参见 Extension ABI v1。

可选的按工作区命名任务

任意命令文本永远不会通过 MCP 接受。对于全局能力未覆盖的、特定于仓库的非常规命令，请创建并审查本地任务策略：

python .\folderbridge_launcher.py init --workspace C:\path\to\repo
# Review C:\path\to\repo\.folderbridge.json
python .\folderbridge_launcher.py approve --workspace C:\path\to\repo

然后在启动器中启用已批准的任务，或向生成的服务器命令添加 --allow-tasks。启用此开关不要求每个配置的工作区都包含 .folderbridge.json：无配置工作区、已批准任务工作区、仅扩展工作区以及配置尚未批准的工作区可以在一个连接中共存。批准会在该工作区的命名任务实际被调用时进行检查。模型只能选择任务名称；它不能提供命令、参数、环境变量或工作目录。

[!WARNING] 测试、构建工具和包脚本会以你当前操作系统用户权限执行仓库代码。对于不受信任的仓库，请使用一次性 VM 或容器，或保持任务执行禁用。

安全模型

FolderBridge 将 MCP 请求、仓库文本和工具输出视为不受信任的数据。强制实施位于工具实现中，而不仅仅是 MCP 注解。主要控制措施包括：

• 每个工作区的规范路径限制和链接拒绝，重叠根目录被拒绝；

• 有界的 UTF-8 读取、搜索、Git 输出、子进程输出和协议消息；

• 带当前内容哈希前置条件的原子写入；

• 受保护的本地策略文件；

• shell=False、固定参数数组、干净的任务环境和超时；

• 扩展清单拒绝未知/过宽的权限名称，扩展批准绑定确切的代码哈希和权限，插件执行被移出 MCP 进程；

• 无入站网络监听器，无 FolderBridge 遥测。

阅读完整安全模型和上游设计研究。要报告漏洞，请遵循 SECURITY.md。

开发

没有第三方运行时依赖。

python -m unittest discover -s tests -v

在提交拉取请求之前，请参阅 CONTRIBUTING.md。

构建 Windows 可执行文件

构建使用固定的、仅构建时使用的 PyInstaller 依赖。发布的 EXE 使用控制台引导加载程序并带有 hide-console=hide-early：双击仅打开 GUI，而同一可执行文件在 Tunnel 启动其 serve 子命令时保留 stdio。

python -m venv .build-venv
.\.build-venv\Scripts\python.exe -m pip install -r requirements-build.txt
.\scripts\build_windows.ps1 -Python .\.build-venv\Scripts\python.exe

工件和 SHA-256 文件写入 release\windows-x64。

许可证

根据 Apache License 2.0 许可。

FolderBridge MCP 是一个独立的开源项目。它与 OpenAI 无关联、未获其认可，也非其赞助。ChatGPT、OpenAI、MCP 及其他产品名称归其各自所有者所有。