scriptscat · cyfung1031 · May 24, 2026 · Jul 11, 2026 · Jul 11, 2026 · Jul 11, 2026
diff --git a/docs/DOC-MAINTENANCE.md b/docs/DOC-MAINTENANCE.md
@@ -96,6 +96,7 @@ of sanitization patterns can otherwise look like matches — so don't rely on a
 | [`architecture.md`](./architecture.md) | Deep internals: process model, message passing; subsystem deep-dives split to [`references/architecture-services.md`](./references/architecture-services.md), [`references/architecture-data.md`](./references/architecture-data.md), [`references/architecture-gm-api.md`](./references/architecture-gm-api.md), [`references/architecture-execution.md`](./references/architecture-execution.md), [`references/architecture-build.md`](./references/architecture-build.md), [`references/architecture-agent.md`](./references/architecture-agent.md). |
 | [`cloud-sync.md`](./cloud-sync.md) | Cloud sync internals: sync files, digest/status semantics, provider differences, error classification, retry policy. |
 | [`translation.md`](./translation.md) | Translation / localization single source of truth. |
+| [`mcp-bridge-guide.md`](./mcp-bridge-guide.md) | End-user how-to for the MCP bridge: install sctl, enable, pair (extension↔daemon + MCP client), tool table, CLI verbs, worked examples. Security rationale lives in the sctl repo's `THREAT-MODEL.md`/`PROTOCOL.md` — link, don't duplicate. `mcp-bridge-guide_zh-CN.md` is its zh-CN translation — keep in sync via [`translation.md`](./translation.md), don't fork content. |
 | [`DOC-MAINTENANCE.md`](./DOC-MAINTENANCE.md) | This guide: doc-set organization rules, fact-check / anti-drift discipline, and policy-consistency checks — for every tracked agent/contributor Markdown file, not just `AGENTS.md` + `docs/*`. |
 | [`README.md`](./README.md) | The index that points to all of the above. |
 | `.github/copilot-instructions.md` | Copilot-specific entry point and any genuine tool-specific differences; shared facts (architecture, commands, testing, design, translation, PR mechanics) route to the owning doc above instead of being copied. |

diff --git a/docs/README.md b/docs/README.md
@@ -15,6 +15,16 @@
 | [`cloud-sync.md`](./cloud-sync.md) | 云同步实现说明:同步文件语义、主流程、状态合并、provider 差异、错误分类、retry 策略和维护注意事项。 |
 | [`DOC-MAINTENANCE.md`](./DOC-MAINTENANCE.md) | 文档维护与事实核对指南:组织规则、逐条核对清单、跨文档政策一致性核对、隐私清理、以及在 resolved final tree 上的复核方法,覆盖全部 tracked 的 agent/contributor Markdown(不止 `AGENTS.md` + `docs/*`,还包括 `.github/*.md`、package-local README)。**改/审文档前先读。** |
 
+## MCP 桥接 / MCP Bridge
+
+内置于所有构建、**默认关闭**,从扩展设置开启;经本地伴随二进制 [`sctl`](https://github.com/scriptscat/sctl)(WebSocket daemon,仅回环 `127.0.0.1:8643`)通信,不新增浏览器权限、无 native-messaging 主机与安装器。
+
+| 文档 | 说明 |
+| --- | --- |
+| [`mcp-bridge-guide.md`](./mcp-bridge-guide.md) | 使用指南:安装 sctl、启用桥接、两条配对(扩展↔daemon、MCP 客户端)、授权的实操步骤,附 6 个 MCP 工具、CLI 动词与真实用例(读取源码、请求安装、启停、删除脚本、撤销客户端)。**想实际用起来先读这份。**中文版见 [`mcp-bridge-guide_zh-CN.md`](./mcp-bridge-guide_zh-CN.md)。 |
+| [`sctl` 仓库 `PROTOCOL.md`](https://github.com/scriptscat/sctl/blob/main/PROTOCOL.md) | 协议规范:扩展↔daemon WS 双向握手、扩展/客户端配对、bridge action、错误码、写操作阻塞语义。常量单源 `protocol.json` 与本仓库 [`src/app/service/service_worker/mcp/protocol.json`](../src/app/service/service_worker/mcp/protocol.json) 逐字节镜像(由 `protocol.conformance.test.ts` 守护)。 |
+| [`sctl` 仓库 `THREAT-MODEL.md`](https://github.com/scriptscat/sctl/blob/main/THREAT-MODEL.md) | 威胁模型:两个信任锚点(长期密钥 K + 0600 控制令牌)、攻击面与对策、写路径人工审批 + TOCTOU、落盘凭据一览。 |
+
 ## 翻译 / Translation
 
 | 文档 | 说明 |

diff --git a/docs/develop.md b/docs/develop.md
@@ -40,6 +40,19 @@ using it — including links already shipped in installed builds, which keep sen
 
 After `pnpm run dev`, load `dist/ext` as an unpacked extension. The browser hot-reloads page changes, but edits to `manifest.json`, `service_worker`, `offscreen`, or `sandbox` require reloading the extension.
 
+### The MCP bridge
+
+The MCP bridge (`src/app/service/service_worker/mcp/`) is **built into every profile and gated only
+at runtime** by `mcp_enabled` (`SystemConfig`, device-local, off by default) — there is no build-time
+flag and no `nativeMessaging` permission (both were removed when the transport moved to WebSocket).
+It connects, from an offscreen WebSocket client (`src/app/service/offscreen/mcp-connect.ts`), to a
+local companion binary [`sctl`](https://github.com/scriptscat/sctl) — a loopback-only WS daemon on
+`127.0.0.1:8643`; the extension never listens on a port itself. Protocol constants are single-sourced
+in [`mcp/protocol.json`](../src/app/service/service_worker/mcp/protocol.json), mirrored byte-for-byte
+with the sctl repo and guarded by `protocol.conformance.test.ts`. See
+[`mcp-bridge-guide.md`](./mcp-bridge-guide.md) for usage, and the sctl repo's `PROTOCOL.md` /
+`THREAT-MODEL.md` for the wire protocol and security design.
+
 ## Project Structure & Module Organization
 
 Core entry points live in `src` (`service_worker.ts`, `content.ts`, `inject.ts`, `offscreen.ts`, `sandbox.ts`). UI pages are in `src/pages`, with shared UI in `src/pages/components` and state in `src/pages/store`. Reusable domain code is in `src/pkg`; app services are in `src/app`; templates are in `src/template`; assets and translations are in `src/assets` and `src/locales`. Workspace packages live in `packages`, including browser mocks and filesystem adapters. Unit tests are colocated as `*.test.ts`/`*.test.tsx` or placed in `tests`; E2E specs are in `e2e`.