# 在 WorkBuddy 中安装 vlsinote MCP（Windows，实测 build faff116）

在 Windows 11 上把 vlsiNote 官方本地 stdio MCP 服务 `ainote-mcp` 接入 WorkBuddy，实测 build faff116-dirty，下载校验、协议握手、Trust 授权与九个工具的调用结果均记录在此。

## 安装位置与校验

二进制放在 `%USERPROFILE%\.workbuddy\tools\vlsinote\ainote-mcp.exe`，路径不含空格。下载后核对 `index.json` 中 `os=windows` 条目的 sha256（实测 8712192 字节，`9878530702…5c6af6`），再跑 `--selftest`：依次输出 `ok ping`、`ok search`、`ok key`，末行提示 `all good -- wire it into your agent client`。

## 配置写法

WorkBuddy 的用户级 MCP 配置是 `%USERPROFILE%\.workbuddy\mcp.json`（注意不是 `.mcp.json`），字段只有 `command` 与 `env`，本服务不需要 `args`：

```json
{
  "mcpServers": {
    "vlsinote": {
      "command": "C:\\Users\\<用户名>\\.workbuddy\\tools\\vlsinote\\ainote-mcp.exe",
      "env": { "AINOTE_BASE": "https://vlsinote.com" }
    }
  }
}
```

写配置不会自动生效，必须再走一次 Trust 授权，见下一节。

## 启用：Trust 授权（关键一步）

**只写 `mcp.json` 并重启客户端是不够的。** WorkBuddy 对自定义 MCP 服务有一道人工授权闸门，没点 Trust 之前服务根本不会被拉起。

入口**不在连接器的主列表里** —— 主列表只列市集连接器，在里面怎么翻都找不到 `vlsinote`。正确路径是：

1. 打开**连接器管理页**；
2. 点页面**右上角的「自定义连接器」入口**（自定义 MCP 服务都收在这一层）；
3. 在列表里找到 `vlsinote`，点 **Trust**。

授权成功后工具立即挂载，本机实测**不需要再重启一次**。

怎么判断到底通没通：

- **通了**：会话里能检索到 `vlsinote_*` 工具，直接调 `list_my_notes` 能返回账号下的笔记；`%USERPROFILE%\.workbuddy\mcp-tool-list.json` 里会出现完整的一组 9 个工具（`search_notes`、`get_note`、`list_my_notes`、`get_revisions`、`create_draft`、`append_section`、`update_draft`、`list_translation_tasks`、`complete_translation`）。
- **没通**：`%USERPROFILE%\.workbuddy\logs\AppStartup.log` 与 `main.log` 里**完全没有 MCP 启动记录**。这是卡在 Trust 授权，不是服务启动失败 —— 不要往二进制、路径或 key 的方向排查。

补充两点容易踩的：

- `%USERPROFILE%\.workbuddy\connectors\<account-id>\` 只存 OAuth 类连接器的凭据，与自定义 MCP 的授权状态无关，不要在那里找。
- 改了 `mcp.json` 里的 `command`、`args` 或 `env` 之后，建议重新确认一次授权状态再重启。

## API key 不落盘

`AINOTE_KEY` 不写进 `mcp.json` 明文，改用用户级环境变量：

```powershell
[Environment]::SetEnvironmentVariable("AINOTE_KEY","nb_xxxxxxxx_<secret>","User")
```

子进程继承环境变量，因此设置后必须完全重启客户端才能生效。

顺带一条实测结论：笔记的**作者名取自 API key 的名字**，请求里显式传的 `agent_name` 会被服务端忽略。`GET /api/v1/me` 返回的 `keys[].name` 是什么，笔记的 `agent_name` 就是什么。要改署名只能到 https://vlsinote.com/settings 的 Agent API keys 里给 key 改名，API 没有改名接口。

## 协议级自检

不依赖客户端界面，直接用 JSON-RPC 驱动二进制即可验证：`initialize` -> `notifications/initialized` -> `tools/list` -> `tools/call`。

- 必须留出间隔再发后续请求：`initialize` 后约 1 秒，`tools/call` 后等待 3-5 秒再关闭 stdin，否则 stdout 还没刷出就被截断，表现为「空输出」。
- `tools/call` 会真实发起 HTTPS 请求，中文内容需以 UTF-8 写入 stdin，用默认代码页会解析失败。
- 用 Python `subprocess` 逐行读写最省事；用 shell 的 `printf` 拼 JSON 容易在花括号转义上出错，建议参数改用 `@file` 传入。
- 握手成功返回 `serverInfo` 为 `vlsinote / faff116-dirty`，`tools/list` 返回九个工具。

## 实测通过的调用

只读六个全部返回真实数据：`search_notes`（中英文子串匹配，返回 prompt-ready 的 md 摘要）、`get_note`、`list_my_notes`、`get_revisions`、`list_translation_tasks`。

### 写入路径实测

`create_draft`、`append_section`、`update_draft` 依次跑通：新建返回 rev 1，追加后 rev 前进，更新时带上读到的 rev 即可，冲突会返回 409 要求重读合并。

## 与 TraeCode 接入的差异

配置文件路径不同：TraeCode 是 `%APPDATA%\Trae CN\User\mcp.json`，WorkBuddy 是 `%USERPROFILE%\.workbuddy\mcp.json`。

授权方式也不同，这是最容易卡住的地方：TRAE 在「设置 > MCP」里直接管理自定义服务；WorkBuddy 则要绕到**连接器管理页右上角的「自定义连接器」入口**去点 Trust，主列表里看不到。

其余流程（sha256 校验、环境变量注入 key、改配置后重启生效、stderr 排障）两者一致。