wb-intl-mcp

Bring WorkBuddy AI (international) models into another WorkBuddy / CodeBuddy client — via MCP tools and the model dropdown. 把 WorkBuddy AI（国际版）的全部模型接入另一个 WorkBuddy / CodeBuddy 客户端 —— 同时提供 MCP 工具与模型下拉框两条通道。

It reuses the already-signed-in WorkBuddy AI (international) desktop app on the same machine, so no API key is needed: the desktop app's own credential is read (read-only) and a logged-in session is used to call the model gateway. 本机已登录的 WorkBuddy AI（国际版） 桌面 App 凭据被复用（只读），因此无需任何 API Key —— 直接以你已登录的会话调用模型网关。

The wire protocol and credential-decryption scheme were ported from the real-device-verified reference implementation corrinehu/dsh-workbuddy-connect (MIT, a DeepSeek Harness plugin), and re-verified on a real machine (Windows 10 / international app 37.10.3-24 / domestic client 37.10.3-42). 协议与加解密方案转录自经真机验证的参考实现 corrinehu/dsh-workbuddy-connect（MIT，DeepSeek Harness 插件），并在本机（Windows 10 / 国际版 App 37.10.3-24 / 国内版 37.10.3-42）实测通过。

This project is unofficial. It talks to the WorkBuddy client-side endpoints (not a public API) and reuses your own account. Use it only on your own machine, for your own account, and at your own risk; it is subject to WorkBuddy's terms of service. 本项目为非官方项目。 它调用的是 WorkBuddy 客户端侧接口（非公开 API）并复用你自己的账号。请仅在你自己的机器、你自己的账号上使用，风险自负，并遵守 WorkBuddy 的服务条款。

⚠️ Read this first: MCP ≠ "model list"

Related MCP server: Collaborative MCP Proxy Server

⚠️ 先理解一件事：MCP 不等于「模型列表」

This is the most common trap: 一个 MCP connector only injects tools into the client; it never adds models to the model dropdown. So if you only install the MCP server, the international models will never appear in the model list — you can only reach them indirectly by asking the assistant to call wb_ai_chat. MCP 连接器只往客户端注入「工具」，不会往模型下拉框里加模型。 所以只装 MCP，模型列表里永远看不到国际版模型 —— 你只能在对话里让 AI 调用 wb_ai_chat 间接使用。

To pick an international model directly in the dropdown, you must go through the "custom model" channel: ~/.workbuddy/models.json. That channel requires plain OpenAI protocol, and the international gateway is not plain OpenAI. Hence this project ships two paths: 要在模型下拉框里直接选国际版模型，必须走「自定义模型」通道：~/.workbuddy/models.json。而该通道要求标准 OpenAI 协议，国际版网关不是。因此本项目同时提供两条路径：

Path B depends on a local OpenAI-compatible proxy (proxy.js, default 127.0.0.1:8787) that translates the international gateway's private protocol (JWT + X-Conversation-* + forced streaming) into plain OpenAI. 路径 B 依赖 本地 OpenAI 兼容代理（proxy.js，默认 127.0.0.1:8787），它把国际版的私有协议（JWT + X-Conversation-* + 强制流式）翻译成标准 OpenAI 协议。

Architecture / 架构

                    ┌──────────────────────────────────────────────┐
Path A: MCP tools ─▶│  wb-intl-mcp (server.js)   stdio MCP         │
路径 A: MCP 工具     │  wb_ai_models / wb_ai_chat / wb_ai_status     │
                    └───────────────────┬──────────────────────────┘
                                        │
Path B: model list ─▶ proxy.js ─────────┤  shares one credential + catalog cache
路径 B: 模型下拉框    127.0.0.1:8787     │  共享同一套凭据与目录缓存
  models.json entry   /v1/models        │
  url=.../v1          /v1/chat/...      │
                                        ▼
                        ┌────────────────────────────────────────┐
                        │  Credential chain (read-only desktop)  │
                        │  凭据链（只读桌面 App 文件）            │
                        │  %LOCALAPPDATA%\CodeBuddyExtension\    │
                        │    Data\Public\auth\                    │
                        │    workbuddy-desktop-ai.info            │
                        │  → spawn WorkBuddyAI.exe -e            │
                        │    .loggerGet() → atRestSecretKey       │
                        │  → sha256 → AES-256-GCM unseal envelope │
                        └───────────────────┬────────────────────┘
                                            ▼
                                 https://www.workbuddy.ai
                                   /v3/config                 model catalog / 模型目录
                                   /v2/chat/completions       chat / 对话
                                   /v2/plugin/auth/token/refresh
                                   /v2/billing/meter/get-user-resource

Key points / 要点:

• The desktop credential file is only ever read, never written. Refreshed tokens live in process memory only. 只读桌面 App 的凭据文件，永不写入；刷新的令牌只存进程内存。

• The international app does not need to stay running — the credential is on disk and the key helper is spawned on demand. 国际版 App 不需要保持运行 —— 凭据在磁盘上，密钥助手按需 spawn。

• Since 2026-10-16 the gateway requires the X-Conversation-ID / Request-ID / Message-ID trio (else 400/11128) and a leading system message. Both are handled. 国际版网关自 2026-10-16 起强制 X-Conversation-ID / Request-ID / Message-ID 三件套（缺则 400/11128）与前置 system 消息，均已实现。

• The gateway forces stream: true. The MCP side aggregates to full text; the proxy side preserves streaming (stream:true) or aggregates to stream:false — both work. 网关强制 stream: true；MCP 侧聚合为完整文本，代理侧则保留流式（stream:true）或聚合为 stream:false，两种都支持。

• Tool calling is relayed, not dropped (verified): tools is forwarded as-is, tool_choice is flattened to a string, developer becomes system, and streamed tool_calls fragments are reassembled by index. So these models also work in Agent mode. 工具调用可透传（已实测）：tools 原样转发、tool_choice 扁平化为字符串、developer 角色改写为 system、流式 tool_calls 片段按 index 拼装。所以这些模型在 Agent 模式下也能用。

• Image input is not relayed yet (the gateway's multimodal wire format is unverified), so registered entries are always supportsImages: false. 图像输入暂不透传（网关多模态线格式未验证），故注册条目一律 supportsImages: false。

Requirements / 环境要求

• Node.js ≥ 18 (uses global fetch / AbortSignal.timeout). Node 20+ recommended. Node.js ≥ 18（依赖全局 fetch / AbortSignal.timeout），建议 Node 20+。

• WorkBuddy AI (international) desktop app installed and signed in on the same machine. 同机已安装并登录 WorkBuddy AI（国际版） 桌面 App。

• A WorkBuddy / CodeBuddy client that supports MCP and/or custom models (the domestic build is what was tested). 支持 MCP 和/或自定义模型的 WorkBuddy / CodeBuddy 客户端（实测对象为国内版）。

Install / 安装

git clone https://github.com/<you>/wb-intl-mcp.git
cd wb-intl-mcp
npm install        # installs @modelcontextprotocol/sdk

node_modules/ is not committed — run npm install.

node_modules/ 不入库 —— 请自行 npm install。

1. Register the MCP server / 注册 MCP 服务

Add to ~/.workbuddy/mcp.json (merge, do not overwrite other servers), or run the helper:

把下面条目加进 ~/.workbuddy/mcp.json（合并，不要覆盖其他服务），或直接跑辅助脚本：

python merge-mcp-config.py          # resolves paths automatically / 自动解析路径
python merge-mcp-config.py --dry-run

{
  "mcpServers": {
    "workbuddy-ai": {
      "command": "node",
      "args": ["/absolute/path/to/wb-intl-mcp/server.js"]
    }
  }
}

On Windows, "command": "node" works if Node is on PATH; otherwise use the absolute path to node.exe (e.g. C:\\Program Files\\nodejs\\node.exe). Windows 下 "command": "node" 需 Node 在 PATH 中；否则写 node.exe 绝对路径（如 C:\\Program Files\\nodejs\\node.exe）。

2. Start the proxy (prerequisite for Path B) / 启动代理（路径 B 的前提）

The MCP server probes and auto-spawns the proxy (detached) at session start, so once a session has run, the proxy is up.

MCP server 启动时会自动探测并拉起代理（detached，进程独立存活），所以只要会话开始过一次，代理就在跑。

node proxy.js                  # foreground / 前台启动
# or on Windows:
scripts\start-proxy.bat
scripts\autostart-on.bat       # install hidden logon autostart / 安装隐藏开机自启
scripts\autostart-off.bat      # remove autostart / 移除自启
scripts\stop-proxy.bat         # stop proxy (only kills the real proxy) / 停止代理

The autostart VBS starts the proxy hidden (no console window), from an absolute path so it is cwd-independent:

自启 VBS 以隐藏窗口启动代理（零控制台窗口），用绝对路径，与 cwd 无关：

Set sh = CreateObject("WScript.Shell")
sh.Run """<node.exe>"" ""<proxy.js>""", 0, False

3. Register the models (Path B) / 注册模型（路径 B）

node register-models.js --dry-run   # preview / 预览
node register-models.js             # write (auto-backup, idempotent) / 写入

This merges wbai/<id> entries into ~/.workbuddy/models.json, preserving your existing custom models.

该命令把 wbai/<id> 条目合并进 ~/.workbuddy/models.json，原有自定义模型全部保留。

4. Restart your WorkBuddy client / 重启你的 WorkBuddy 客户端

models.json is read only at startup, so a restart is required before the wbai/* group appears in the dropdown.

models.json 只在启动时读取，必须重启才能在模型下拉框里看到 wbai/* 分组。

5. Trust the MCP server (Path A) / 信任 MCP 服务（路径 A）

Open the connector manager (the "+" / connectors entry) and trust workbuddy-ai.

右下角「+」/ 连接器管理 → 自定义连接器 → 对 workbuddy-ai 点「信任」。

Using the model dropdown (Path B) / 在模型下拉框里用（路径 B）

Entries appear as GLM-5.3 (International) / GLM-5.3（国际版） and so on (27 of them). Pick one and chat — tool calling works in Agent mode too. The wbai/ prefix keeps them distinct from same-named entries you may already have (e.g. glm-5.2).

下拉框里会出现形如 GLM-5.3（国际版） 的条目，共 27 个。选中即用，走 Agent 模式也能调用工具。wbai/ 前缀是为了与你已有的同名模型（如 glm-5.2）区分开。

MCP tools (Path A) / MCP 工具（路径 A）

CLI / 命令行工具

# --- model registration (models.json) / 模型注册 ---
node register-models.js --dry-run     # preview / 预览
node register-models.js               # write (auto-backup, idempotent) / 写入
node register-models.js --list        # list registered wbai/* entries / 列出已注册条目
node register-models.js --unregister  # remove all wbai/* entries / 移除全部
node register-models.js --json        # machine-readable / 机器可读输出

# --- proxy / 代理 ---
node proxy.js                         # foreground / 前台启动
curl http://127.0.0.1:8787/health      # health check / 健康检查
curl http://127.0.0.1:8787/v1/models   # OpenAI-format model list / 模型列表

# --- MCP self-test / MCP 自检 ---
node test-probe.js                                          # initialize/tools/status/models
node test-probe.js --chat "hello" --model deepseek-v4.1-flash

Environment variables (all optional) / 环境变量（均可选）

Project layout / 目录结构

wb-intl-mcp/
  server.js                 MCP stdio server (3 tools; supervises the proxy) / MCP stdio 服务（3 个工具；守护代理）
  proxy.js                  local OpenAI-compatible proxy (Path B core) / 本地 OpenAI 兼容代理（路径 B 核心）
  register-models.js        write international models into ~/.workbuddy/models.json
  test-probe.js             MCP stdio JSON-RPC end-to-end probe / MCP 端到端探针
  merge-mcp-config.py       merge the MCP entry into mcp.json (with backup) / 合并配置（带备份）
  src/electron.js           WorkBuddyAI.exe discovery + key-helper spawn
  src/auth.js               credential location / envelope decryption / in-memory token store
  src/upstream.js           /v3/config, /v2/chat/completions, refresh, credits, tool normalization
  src/runtime.js            shared bootstrap: credential + client + catalog cache
  src/proxy-supervisor.js   proxy health probe + detached auto-spawn
  scripts/*.bat             Windows helpers (start/stop proxy, register models, autostart)
  LICENSE                   MIT

Troubleshooting / 故障排查

Model dropdown has no international models / 模型下拉框看不到国际版模型

Autostart / 自启相关

Other / 其他

Security & compliance / 合规与安全

• Credentials are read-only: the desktop credential file is never modified, and refreshed tokens stay in memory — never written to disk or logs. 凭据只读：桌面凭据文件永不修改，刷新的令牌只存内存，不落盘、不进日志。

• The proxy binds to 127.0.0.1 (loopback) only, and is unauthenticated by default; set WB_INTL_PROXY_KEY if you want a bearer check. 代理只监听 127.0.0.1（回环），默认不校验密钥；需要时可设 WB_INTL_PROXY_KEY。

• The MCP server listens on no network port — stdio only. MCP 服务不监听任何网络端口，只走 stdio。

• It reuses your own account credential, on your own machine, and is bound by WorkBuddy's terms of service. 复用你自己的账号凭据，仅本机使用，受 WorkBuddy 服务条款约束。

• It depends on WorkBuddy client-side endpoints (not a public API). A major client update may break it; the reference implementation is tracked upstream and this repo follows it. 依赖 WorkBuddy 客户端侧接口（非公开 API）。客户端大版本更新可能导致失效；参考实现持续跟进，本仓库以其为基准。

• Do not commit credentials. No token, account id, nickname, or absolute user path is stored in this repo. 请勿提交凭据。 本仓库不含任何令牌、账号 ID、昵称或用户绝对路径。

Acknowledgements / 致谢

Protocol and credential scheme adapted from corrinehu/dsh-workbuddy-connect (MIT). This project is an independent reimplementation in plain Node.js with a different packaging and an added model-dropdown proxy path.

协议与凭据方案改编自 corrinehu/dsh-workbuddy-connect（MIT）。本项目是用纯 Node.js 的独立重写，封装不同，并新增了模型下拉框代理通道。

License / 许可证

MIT