Skip to content

docs: update actual Local Bridge MCP integration and WeChat boundaries #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
opendev9 merged 1 commit into from
Oct 27, 2026
Merged

docs: update actual Local Bridge MCP integration and WeChat boundaries #4

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

**跨平台、本地优先的微信 MCP 能力提供者（macOS / Windows）。**

独立运行，无需安装 [Local Bridge](https://github.com/eaopen/local-bridge)；未来可作为普通 MCP Provider 由 Local Bridge 注册和调用。微信聊天数据、实际发送和 UI 操作均由本项目负责，Bridge 不内置微信业务逻辑。
独立运行，无需安装 [Local Bridge](https://github.com/eaopen/local-bridge)；目前也可由用户通过 Local Bridge 手动注册为本机 MCP Provider 并调用。微信聊天数据、实际发送和 UI 操作仍由本项目负责，Bridge 不内置微信业务逻辑。

## 当前交付（v0.1.0）

Expand All @@ -14,7 +14,8 @@
| Windows 4.x GUI 适配 | 🔶 对接 [pyweixin](https://github.com/Hello-Mr-Crab/pywechat)；需实机验证 |
| macOS GUI 适配 | 🔶 对接 [wxauto-mac](https://github.com/PatrickHua/wxauto-mac)；需实机验证当前微信版本 |
| 微信原生 SQLCipher 数据库解密与增量导入 | ❌ 尚未实现，放在独立后续任务 |
| Local Bridge 直接自动注册 | ❌ 尚未实现；MCP Server 可单独启动 |
| Local Bridge 本机手动 MCP 接入 | ✅ 已提供，见 [接入步骤](docs/LOCAL_BRIDGE.md)；**未通过真实微信 GUI 验收** |
| Local Bridge 自动注册 / 浏览器直接读写微信 | ❌ 尚未实现；MCP Server 可单独启动 |

**重要：仓库提供可运行的软件骨架、SQLite 和 MCP 实现，但还没有完成真实微信账号的端到端发送验收。** 微信 4.x 的可访问性树可随账号/版本变化，不能假设任意机器可用。

Expand Down Expand Up @@ -93,7 +94,7 @@ wechat-provider import-jsonl /path/to/my_messages.jsonl
- 数据库读取的下一阶段参考 [robbin/wechat-exporter](https://github.com/robbin/wechat-exporter)、[Wechat-MCP](https://github.com/xerlxzx/Wechat-MCP) 及 Windows 的 [wechat-local-analytics](https://github.com/davids1896/wechat-local-analytics)；先验证不同微信版本的兼容性，再接入 **只读离线快照**，不直接嵌入未经确认的解密脚本。
- **不使用 OpenRPA** 作为默认引擎；复杂 Windows 通用业务工作流有实际需求时再评估独立适配。

见 [架构和完成条件](docs/ARCHITECTURE.md)、[2026-10-28 微信 MCP 与发送方案横向调研](docs/WECHAT_MCP_SEND_OPTIONS_2026-10-28.md)、[Local Bridge 对接边界](docs/LOCAL_BRIDGE.md) 及 [开发要求](AGENTS.md)。
见 [架构和完成条件](docs/ARCHITECTURE.md)、[2026-10-28 微信 MCP 与发送方案横向调研](docs/WECHAT_MCP_SEND_OPTIONS_2026-10-28.md)、[Local Bridge 当前实际接入命令与边界](docs/LOCAL_BRIDGE.md) 及 [开发要求](AGENTS.md)。

## 开发验证

Expand Down
66 changes: 52 additions & 14 deletions docs/LOCAL_BRIDGE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,25 +1,63 @@
# Integration with Local Bridge
# Integration with Local Bridge — 当前可用合同

WeChat Provider is a standalone, locally installed communication capability.
WeChat Provider 是独立安装、独立运行的本机微信 MCP 服务。微信登录、桌面 GUI/RPA、SQLite/FTS5、本机发送任务和结果状态始终由本仓库管理；Local Bridge 只作为**可选 MCP Client** 连接已安装的 Provider。

## 当前已实现（2026-10-28）

- WeChat Provider 提供 `wechat-provider serve` stdio MCP 和六个工具，不依赖 Local Bridge。
- [Local Bridge PR #13](https://github.com/eaopen/local-bridge/pull/13) 已合并：用户可以在本机主动注册固定可执行程序及参数，再通过 MCP `initialize → tools/list → tools/call` 调用已公布的工具。
- [Local Bridge PR #14](https://github.com/eaopen/local-bridge/pull/14) 已合并：Ubuntu CI **实际安装并启动本仓库的 Python MCP Server**，由 Rust Local Bridge 完成状态、空索引搜索及拒绝未知工具的跨进程验证。
- **尚未实现**：自动扫描微信聊天、`messages.subscribe` 事件订阅、Bridge 自动代理全部工具给浏览器/AI、实际 Windows/macOS 微信 4.x GUI 读写验收或发送送达核验。

## 最小本机接入

先按照 [README](../README.md) 安装微信 Provider 和目标操作系统对应的可选依赖；`wechat-provider serve` 是由本仓提供的**独立 MCP Server**。

在安装 Local Bridge 的用户本机，找到真正的 `wechat-provider` 可执行程序绝对路径，手动注册：

```sh
local-bridge provider add wechat /absolute/path/to/wechat-provider serve
local-bridge provider list
local-bridge provider tools wechat
local-bridge provider call wechat wechat_status '{}'
local-bridge provider call wechat wechat_search '{"query":"待办","limit":10}'
```

如果已登录的微信 UI 可以提供相应读取，显式指定想读取的聊天：

```sh
local-bridge provider call wechat wechat_list_chats '{"limit":5}'
local-bridge provider call wechat wechat_get_messages '{"chat_id":"文件传输助手","limit":10}'
```
Agent / MCP client ──► wechat-provider serve (stdio)
Agent / Web client ──► Local Bridge ──► [future user-installed MCP registration] ──► Provider

发送操作仅限用户明确从本机 CLI 发起，**不会因为注册而默认允许网页或 Agent 自动发送**：

```sh
local-bridge provider call wechat wechat_send_message '{"chat_id":"文件传输助手","text":"受控测试","idempotency_key":"test-local-20261028-01"}'
local-bridge provider call wechat wechat_get_send_status '{"task_id":"<task-id>"}'
```

## Ownership
当前 `chat_id` 是 UI **显示名称**，不是微信唯一且稳定的用户 ID。用受控的测试会话验收，发送前核对聊天对象；返回 `submitted` 只表示 UI 调用没有抛错，**绝不等于已送达**。遇到 `uncertain` 时查询原任务，不自动重复发送。该限制也适用于经 Local Bridge 代理的结果。

取消注册：`local-bridge provider remove wechat`。这不会删除原 Provider 的 SQLite、账号资料或安装目录。

## 所有权与非目标

- **WeChat Provider:** user-authorized local chat reads, its own SQLite index, desktop RPA, recipient checks, send ledger and statuses.
- **Local Bridge:** discover/register callable capabilities, route requests within its own caller authorization model, and coordinate cross-application tasks. It does not inspect WeChat's DB schema, impersonate a WeChat user, or implement send logic.
- **Etech/other applications:** remain independently authorized; Provider must not contain Etech-specific business rules.
| 所属模块 | 职责 |
|---|---|
| WeChat Provider | 登录中的微信桌面适配、聊天 UI、消息索引、发送状态/幂等、实际响应 |
| Local Bridge | 当前 OS 用户主动安装的 MCP 连接器注册、工具发现、调用转发和结果展示 |
| Local Tool Bridge Chrome 扩展 | 独立网页上下文采集、用户主动交接；**尚未**开放浏览器直接调用微信读取或发送 |
| CloudFile/Etech | 原企业登录、业务对象/文件权限和文件版本，不因微信 Provider 接入而改变 |

**Current state:** Local Bridge 0.1.0 has a read-only MCP prototype; it does not yet offer general installed-provider registration. Thus this repository works independently today. Do not claim automatic Bridge integration is shipped.
默认可以在同一电脑同时使用个人微信和企业文件工具，不建立新的个人/企业隔离墙；每个原模块仍执行已有认证、权限与操作结果判断。消息文本是数据，不能被当作命令自动执行。

## Future registration contract (proposal)
不硬编码 Etech、CloudFile 或 Local Bridge 的私有程序/路径到 WeChat Provider 核心，不构建新的微信协议解密/RPA，不因为出现 Bridge 就要求用户迁移原有 MCP 客户端。

Advertise a fixed, locally installed executable and explicit stdio arguments:
`wechat-provider serve`. Announce six MCP tools and side-effecting classifications; `wechat_send_message` is a write operation. Respect the user's local connector permissions. Do not accept arbitrary execution paths or commands from a webpage or chat message.
## 待验收的真实场景

When Local Bridge exposes actual user-approved provider registration, add a small setup example here rather than linking its runtime into this project.
- [Windows 微信 UI 验收 #1](https://github.com/eaopen/wechat-provider/issues/1)
- [macOS 微信 UI 验收 #2](https://github.com/eaopen/wechat-provider/issues/2)
- [只读离线快照导入 #3](https://github.com/eaopen/wechat-provider/issues/3)

Message send outcomes are `queued/running/submitted/uncertain/failed`; only separately evidenced receipt checks may be marked `verified`. Never automatically interpret `submitted` as delivered.
MCP 传输验证成功 ≠ GUI 兼容 ≠ 微信发送核验成功。
Loading