# 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](https://github.com/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](https://github.com/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"
## ⚠️ 先理解一件事：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 / 路径 | What you get / 效果 | What it needs / 需要的东西 |
| --- | --- | --- |
| **A. MCP tools / MCP 工具** | Call `wb_ai_chat` in a conversation to use any international model / 对话里调用 `wb_ai_chat` 使用任意国际版模型 | `mcp.json` entry + trust / `mcp.json` 条目 + 信任 |
| **B. Model dropdown / 模型下拉框** | Pick `wbai/glm-5.3` etc. directly; works in Agent mode / 下拉框里直接选 `wbai/glm-5.3` 等，走 Agent 模式 | `models.json` entries + **the local proxy running** / `models.json` 条目 + **本地代理在跑** |

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 / 安装

```bash
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`（**合并**，不要覆盖其他服务），或直接跑辅助脚本：

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

```json
{
  "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，进程独立存活），所以**只要会话开始过一次，代理就在跑**。

```bash
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 无关：

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

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

```bash
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）

| Tool / 工具 | Description / 说明 |
| --- | --- |
| `wb_ai_models` | List all models available to the account: id, name, credit multiplier, context window, output cap, reasoning tiers, image support, promo; image/video rows are grouped and flagged as non-chat. / 列出账号可用的全部模型：ID、名称、积分倍率、上下文窗口、输出上限、推理档位、是否支持图片、促销信息；图像/视频模型单独分组标注 |
| `wb_ai_chat` | One chat completion. Args: `model` (required), `messages` (required, OpenAI style), `system`, `temperature`, `max_tokens`, `reasoning_effort`. Returns `content` / `reasoning` / `finishReason` / `usage`. / 一次对话补全。参数：`model`、`messages`、`system`、`temperature`、`max_tokens`、`reasoning_effort`。返回 `content` / `reasoning` / `finishReason` / `usage` |
| `wb_ai_status` | Signed-in account, token expiry & source, remaining credits, app version, catalog cache age, plus proxy reachability and registered model count. Makes no model call. / 登录账号、令牌有效期与来源、剩余积分、App 版本、目录缓存年龄，以及代理可达性与已注册模型数。不发模型调用 |

## CLI / 命令行工具

```bash
# --- 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) / 环境变量（均可选）

| Variable / 变量 | Purpose / 作用 |
| --- | --- |
| `WORKBUDDY_AI_AUTH_FILE` | Override the desktop credential file path. / 覆盖桌面凭据文件路径 |
| `WORKBUDDY_AI_ELECTRON_BIN` | Override `WorkBuddyAI.exe` path (when auto-discovery fails). / 覆盖 WorkBuddyAI.exe 路径 |
| `WB_AI_CHAT_TIMEOUT_MS` | Chat timeout, default 600000 (10 min). / 聊天超时，默认 600000（10 分钟） |
| `WB_AI_MCP_LOG` | `=1` → MCP server debug logs to stderr (never prints tokens). / `=1` 时向 stderr 输出调试日志（绝不打印令牌） |
| `WB_INTL_PROXY_PORT` | Proxy port, default 8787 (re-run `register-models.js` after changing). / 代理端口，默认 8787（改了要重跑注册） |
| `WB_INTL_PROXY_HOST` | Proxy bind address, default `127.0.0.1`. / 代理绑定地址 |
| `WB_INTL_PROXY_KEY` | If set, require `Authorization: Bearer <key>`. / 设置后要求 Bearer 鉴权 |
| `WB_INTL_PROXY_LOG` | `=1` → proxy request logs (no tokens or bodies). / `=1` 时代理输出请求日志（不含令牌与正文） |
| `WB_INTL_NODE` | Explicit `node.exe` path for the Windows `.bat` helpers. / Windows 批处理脚本用的 node.exe 路径 |

## 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 / 模型下拉框看不到国际版模型

| Symptom / 现象 | Cause & fix / 原因与处理 |
| --- | --- |
| No `(International)` entries at all / 完全没有 `（国际版）` 条目 | **You did not restart the client** (`models.json` is read at startup only); or `register-models.js` was not run — check with `--list`. / **没重启客户端**（`models.json` 只在启动时读）；或注册未执行 —— 跑 `--list` 确认 |
| Entries exist but calls fail to connect / 有条目但调用报连接失败 | The proxy is not running. Check `curl http://127.0.0.1:8787/health`, then run `scripts\start-proxy.bat` / `node proxy.js`. / 代理没在跑。先 `curl .../health`，再启动代理 |
| You look for the MCP name in the model list / 在模型列表里找 MCP 的名字 | MCP adds tools, not models — by design, see the top section. / MCP 不加模型，只加工具 —— 这是设计，见文首 |
| Breaks after changing the proxy port / 换端口后失效 | Re-run `register-models.js`, otherwise the stored `url` still points at the old port. / 必须重跑注册，否则 url 仍是旧端口 |

### Autostart / 自启相关

| Symptom / 现象 | Cause & fix / 原因与处理 |
| --- | --- |
| Check whether autostart is installed / 想确认自启是否已装 | Look for `wb-intl-proxy.vbs` in your Startup folder (`%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup`). / 看启动文件夹里有无该 VBS |
| Proxy not up after logon / 开机后代理没起来 | Run the VBS once manually (`wscript "<path>\wb-intl-proxy.vbs"`); if it still fails, run `scripts\start-proxy.bat` to see the error. / 手动跑一次 VBS；仍失败则用 start-proxy.bat 看报错 |
| Stop it but keep autostart / 想临时停掉但保留自启 | `scripts\stop-proxy.bat` (it returns at next logon). / 下次登录会照常自启 |
| Remove autostart entirely / 彻底不要自启 | `scripts\autostart-off.bat` |
| Moved the folder / changed Node / 换了目录或 node | Re-run `scripts\autostart-on.bat` to refresh the absolute paths in the VBS. / 重跑以刷新 VBS 里的绝对路径 |

### Other / 其他

| Symptom / 现象 | Cause & fix / 原因与处理 |
| --- | --- |
| `WorkBuddy AI desktop credential not found` / `未找到...登录凭据` | The international app is not signed in; sign in once, or set `WORKBUDDY_AI_AUTH_FILE`. / 国际版 App 未登录；先登录一次，或用 `WORKBUDDY_AI_AUTH_FILE` 指定 |
| `WorkBuddyAI.exe not found` / `找不到...exe` | Set `WORKBUDDY_AI_ELECTRON_BIN` explicitly. / 用 `WORKBUDDY_AI_ELECTRON_BIN` 显式指定 |
| `failed to decrypt accessToken` / `字段 accessToken 解密失败` | The app was reinstalled / its static key changed: open the international app and sign in again. / App 重装或换了静态密钥：打开国际版 App 重新登录 |
| `chat ... 400` mentioning conversation / 提到 conversation | The header trio is missing — make sure you are using this server, not a hand-rolled request. / 网关三件套缺失 —— 确认用的是本 server |
| A model returns 400/11133 / 某模型报 400/11133 | That model rejects a too-small `max_tokens` (the GPT-5.6 family rejects 1); raise it or omit it. / 该模型不接受过小的 `max_tokens`，调大或不传 |
| Out of credits (402) / 积分不足（402） | Check balance with `wb_ai_status`; switch to an x0.00 promo model (`hy3` / `step-5-preview` / `deepseek-v4.1-flash`). / 查余额；换 x0.00 促销模型 |

## 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](https://github.com/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](https://github.com/corrinehu/dsh-workbuddy-connect)（MIT）。本项目是用纯 Node.js 的独立重写，封装不同，并新增了模型下拉框代理通道。

## License / 许可证

[MIT](LICENSE)