# mcp-bridge

Windows MCP 工作空间控制台，集中管理连接、权限、运行任务和文件变更。已打包程序可直接运行。

## GitHub 源码版本

当前源码版本为 1.2.0；首次公开发行版本为 1.1.1。仓库只包含源码、图标、许可和测试脚本，不包含安装包、依赖目录、连接凭据、运行日志或测试数据。下列 release 路径为本地构建输出，并非仓库内置文件。验证报告引用的原始测试数据保留在本地，不公开上传。

## 交付形式

目标平台：Windows x64（Windows 10/11；未逐一验证所有系统版本）。

- `release/mcp-bridge-1.2.0/mcp-bridge-1.2.0-Setup-x64.exe`：安装向导，可选安装路径，带快捷方式和卸载入口。
- `release/mcp-bridge-1.2.0/mcp-bridge-1.2.0-x64.zip`：免安装版。完整解压后运行 `mcp-bridge.exe`。不要只复制 EXE，旁边的 DLL 和 resources 文件夹是运行时的一部分。
- `release/mcp-bridge-1.2.0/win-unpacked/`：未压缩的同一桌面程序。

安装包尚未使用开发者代码签名证书。Windows 可能显示未知发布者或信誉提示；正式公开分发前应配置你自己的代码签名证书。不要关闭系统安全软件。

## 第一次使用

1. 启动 mcp-bridge，点击右上角“选择工作目录”。该目录是默认工作目录；手动/自动审批下也是文件工具的访问边界。
2. 默认是“仅本地连接”，端口 8788；不会自动开启公网隧道，也不会自动启动 MCP。
3. 点击“启动连接”。同机客户端可以使用本地 URL；远程云端 AI 无法访问你电脑的 `127.0.0.1`，需要先在设置里选择 Cloudflare 临时公网隧道。
4. 复制接入提示词，交给支持 MCP Streamable HTTP / POST JSON-RPC 的客户端。
5. 按需授权：默认只开启 Read，Edit、Execute、Capture 默认关闭。默认使用手动审批；审批模式与工具权限是两层控制。
6. 在“运行任务”查看输出、发送交互输入、停止进程树；在“变更记录”查看修改前后内容，并在没有后续冲突时恢复。

端口和隧道类型只允许在服务停止后更改。公网隧道连接失败时，本地 MCP 仍可用，界面会显示失败原因。Cloudflare 临时域名可能在重连时变化，其网络可达性与速率由第三方服务决定。

## 三种审批模式

| 模式 | 文件修改 / 命令 | 截图 | 文件访问范围 |
|---|---|---|---|
| 手动审批（默认） | 每次本地确认 | 每次本地确认 | 所选工作目录 |
| 自动审批 | 已启用的常规操作自动批准；命中风险规则的命令仍确认 | 每次本地确认 | 所选工作目录 |
| 完全访问 | 不逐次确认，开启全部工具权限 | 不逐次确认 | 当前 Windows 用户有权访问的文件，包括工作目录外 |

在连接控制台选择模式。进入自动审批或完全访问需要本机确认，远程 MCP 参数不能代替这一步。完全访问不提权、不绕过 Windows ACL；默认目录仍用于相对路径和搜索。切回其他模式会恢复进入完全访问前的工具开关。模式和已确认的完全访问选择会跨重启保留；旧配置没有模式时使用手动审批。

**自动审批的风险规则不是安全沙箱，也不能识别所有危险脚本。** Execute 在所有模式下都拥有当前 Windows 用户权限。切换模式不会杀死已有命令，需要时先在任务页停止。确认过程中切换模式、目录或停止连接，会拒绝过期操作。仅对可信客户端使用自动审批或完全访问。

## 应用更新

- 默认在启动约 10 秒后及每 6 小时检查 GitHub 的最新稳定 Release；可在设置中关闭，或点击“检查更新”。发现新版后，顶部显示更新入口。
- **只自动检查，不自动下载、不自动安装。** 在设置中点击“下载安装包”，可查看进度、取消和重试。
- 来源固定为 `https://github.com/cnrpot/mcp-bridge`。仅接受匹配版本的 Windows x64 安装包、HTTPS 允许域名、合法大小和 GitHub SHA256 元数据；下载结束和安装前均校验文件。拒绝校验失败的文件并清理下载残片。
- 点击“退出并安装”仍需本地确认，即使当前为完全访问。还有运行任务、工具操作或待审批请求时不允许安装。安装会退出应用并启动普通安装向导，不执行静默安装、不自动提权。开发态不允许启动安装包。
- 免安装版可打开发布页下载 ZIP，退出旧版后完整替换程序目录；点击“退出并安装”会进入安装版向导，不会原地更新 ZIP 目录。
- 首次从 **1.1.1 升级到 1.2.0 需要手动下载安装包或 ZIP**：旧版尚无本功能。更新检查只认识已公开发布的版本，本地构建不会自动成为 GitHub Release。
- SHA256 用于完整性检查，不等同于开发者代码签名。安装包目前未签名；网络错误可稍后重试或打开发布页手动下载，不要关闭系统安全或 TLS 校验。

## 工具范围

桌面版提供 30 个工具：

- 文件：`read_files`、`read_image`、`list_directory`、`find_files`、`search_files`、`apply_patch`。
- 规范与进度：`list_skills`、`read_skill`、`set_todos`、`update_plan`、`report_progress`。
- 命令：`run_command`、`get_command_output`、`list_jobs`、`send_command_input`、`cancel_command`。
- 视觉：`screenshot`、`screenshot_window`、`run_and_capture`。使用 Electron 桌面采集。
- .NET：`dotnet_detect`、`dotnet_build`、`dotnet_test`、`dotnet_run`、`dotnet_publish`、`dotnet_restore`。
- Godot：`godot_detect`、`godot_import`、`godot_run`、`godot_export`、`godot_check`。

.NET SDK、Godot 需要自行安装，可在应用设置中填写可执行文件路径。桌面包不包含这些 SDK。


## 权限与安全边界

- 手动/自动审批下，文件工具校验所选目录边界、真实路径、符号链接/junction 和硬链接；完全访问允许目录外路径及链接目标，但仍拒绝非法路径、设备路径和 NTFS 数据流。目录遍历跳过链接、依赖和生成目录。搜索在独立 Worker 中执行，受数量、大小、时间限制。
- **Execute 不是操作系统沙箱。** 命令仅以工作目录作为起始 cwd，仍拥有当前 Windows 用户的系统权限。它可以访问目录以外的系统资源。仅向可信客户端授权，并保留逐次命令确认。
- 关闭 Execute 只阻止新的执行，不会自动终止已运行命令。要终止任务，请使用任务页的停止按钮或“停止连接”。停止连接及正常退出会停止本应用启动的任务进程树和隧道。
- 截图可能包含屏幕上的敏感信息。Capture 默认为关闭；手动/自动审批中逐次确认，完全访问中不再逐次确认。
- 文件修改前默认显示本地确认。较长内容在确认弹窗中只显示开头，完整前后内容保存到变更记录。
- 连接 URL 的随机 token 等同访问凭据，默认隐藏显示。停止服务后可重新生成，使旧地址失效。应用仅监听 loopback，并校验 Host 和 Origin。
- UI 采用隔离 renderer、sandbox、禁用 Node 集成、限制 IPC、严格 CSP，不向远程网页暴露桌面配置接口。
- 设置保存在 `%APPDATA%\MCPGO Desktop\settings.json`。Windows 可用时，token 使用 Electron safeStorage/系统保护加密；若加密不可用，则不落盘保存 token，下次启动重新生成。
- `history/` 保存最近 50 次文件快照（所有工作区合计），可能含源代码和密钥。`jobs/` 保存有大小限制的命令日志；活动列表不记录参数内容。不要公开上传用户数据目录。
- 变更记录只覆盖 `apply_patch`，不覆盖 shell 命令造成的修改。恢复前校验当前内容，发现后续修改则拒绝覆盖。
- 不要同时让其他编辑器持有同一文件的未保存修改；本应用直接读写磁盘。

## MCP 握手示例

所有请求都使用 POST，`Content-Type: application/json`。用 UI 复制出来的完整 URL，不要把凭据提交到仓库。

```json
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0"}}}
```

随后发送 `notifications/initialized`（无 id），再调用：

```json
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
```

服务采用无状态 JSON 响应，不提供 SSE 长连接。任务取消使用 `cancel_command`，不是仅发送 JSON-RPC cancellation 通知。

## 源码结构与构建

- `main/`：Electron 主进程、窄 IPC、系统托盘、Windows 采集和 Cloudflare 进程生命周期。
- `core/`：MCP 服务、权限与路径检查、文件历史和命令/.NET/Godot 工具。
- `ui/`：中文控制台，五个页面，无 CDN 依赖。
- `test/`：协议、权限、文件和真实命令回归测试。
- `assets/`、`vendor/`：应用图标、Cloudflare 二进制与许可。

从 Git 获取源码时，`vendor/cloudflared.exe` 默认未跟踪，需要放入合法来源的 cloudflared.exe 并保留许可；当前交付目录已包含该文件。

构建机器需要 Windows x64、Node.js >=22.12 和 npm。无需全局安装 Electron：

```powershell
npm ci
npm run check
npm test
npm start
npm run dist
```

如果机器使用系统代理，可运行 `scripts/build.ps1`；它只为当前构建进程读取并使用系统代理，不修改全局代理、不关闭 TLS 校验、不自动使用你的签名证书。

`npm start` 会清理 父进程环境中的 `ELECTRON_RUN_AS_NODE`，保证启动真实桌面窗口。应用默认使用软件合成，以兼容 Windows 远程/虚拟桌面。

最终测试结果、构建产物与限制见 `VERIFICATION.md`。

## 许可

包含的 MCPGO 代码保留 MIT 许可。Cloudflare 二进制来自提供的 VSIX，未作修改，附 Apache-2.0 许可。没有把原包中的专有 ngrok 二进制纳入分发。参见 `THIRD_PARTY_NOTICES.md`。

## 1.1.0 更新

任务启动、输出和结束会通知界面刷新；任务区区分运行中、已完成、失败和已停止。停止连接后保留近期任务及输出，切换工作区或退出应用时清理任务列表。任务列表不跨重启持久化，已结束任务会按保留策略过期。

变更记录兼容 Windows 路径大小写差异；列表使用轻量元数据缓存，恢复后自动更新状态。只显示当前工作目录的记录。既有配置和连接凭据继续使用原存储目录，无需重新授权。

## 1.1.1 稳定性更新

- 写入失败且原文件未改变时，不再留下成功变更记录，也不会因此提前淘汰旧快照。
- 如果写入只完成了一部分，保留原内容并记录实际失败结果，供查看及恢复；无法核实结果时只允许查看备份，不自动恢复。
- 恢复前先检查文件类型和长度，再校验原始字节哈希，避免读取后来变大的文件或误判截断的 UTF-8 内容。
- 恢复确认期间若停止连接或改变工作区，会拒绝过期的恢复操作。
- 快照和配置跨重启保留；任务列表仍不跨重启持久化，不会把已退出的任务显示成仍在运行。

上述保护不等同于断电情况下的文件与历史数据库原子事务。磁盘故障时请保留数据目录中的备份，并查看具体错误。

## 1.2.0 更新

增加三种审批模式、工作目录外完全访问、自动更新检查及手动下载安装；修复远程截图参数伪造内部确认的问题。保留现有配置、凭据和历史目录。详见 `RELEASE_NOTES_1.2.0.md`。