# 说明书 · 市面上的聊天前端

给用别人做好的聊天 app 的人：RikkaHub、Kelivo、Cherry Studio、Claude 桌面版、Open WebUI 这类。你改不了它们的源码，只要它们能挂 MCP，就能让 AI 用道具。

自己写前端的看 [self-built.md](self-built.md)。只想先看看长什么样，直接开[网页试玩](https://the-vault-7o6.pages.dev/)，什么都不用装。

---

## 先看你的前端走哪条路

| 前端 | 在哪儿用 | 走哪条路 |
|---|---|---|
| RikkaHub | 安卓 | A 网络 MCP |
| Kelivo | iOS、安卓、电脑 | 手机上走 A；电脑上 A、B 都行 |
| Cherry Studio | 电脑 | B 本机进程（A 也行） |
| Claude 桌面版 | 电脑 | B 本机进程 |
| LibreChat | 自己部署的网页 | B 或 A |
| Open WebUI 0.6.31 以上 | 自己部署的网页 | A 网络 MCP（它只认这种） |
| SillyTavern 酒馆 | 网页 | 本身不带 MCP，要装第三方的 MCP 扩展、开 function calling。我们没测过 |
| 不支持 MCP 的 app | — | 接不了，只能用网页试玩 |

- **A 网络 MCP**：道具跑在一台机器上（电脑或者服务器），前端隔着网络连 `http://地址:8800/mcp`。手机只能走这条
- **B 本机进程**：前端和道具在同一台电脑上，前端自己把道具拉起来

表里的菜单名照各家文档写的，版本不同可能叫法不一样，找「MCP」或者「工具」那一栏。

## 两条路都要先做的

1. **装 Node.js 18 以上**：<https://nodejs.org>，装 LTS 版
2. **把包拿下来**：在 https://the-vault-7o6.pages.dev/ 下载 the-vault.zip 解压
3. **模型要会调工具**：大多数新模型都会。在前端里找「工具调用 / function calling」有没有开
4. **把说明书给 AI**：`engine/play.md` 是写给 AI 看的，每样道具填什么、什么时候揭问号、报错了怎么演都在里面。整份复制，贴进角色卡、助手的系统提示词或者人设里。不给它，它也能调，但会乱填

---

## A · 网络 MCP（手机）

### 1. 找一台一直开着的机器跑道具

在解压出来的目录里：

```bash
PLAY_TOKEN=换成你自己的口令 HOST=0.0.0.0 node serve.js
```

Windows 的 PowerShell 写法：

```powershell
$env:PLAY_TOKEN="换成你自己的口令"; $env:HOST="0.0.0.0"; node serve.js
```

看到这两行就起来了：

```
档案：http://0.0.0.0:8800
MCP：http://0.0.0.0:8800/mcp（要带口令）
```

- 口令随便编一串长一点的字母数字，别用生日。谁拿到口令谁就能往你档案里写东西
- `HOST` 不是本机的时候不设口令它不启动
- 这个窗口别关，关了就断了。想开机自己跑，用 pm2、系统服务之类，跟别的 Node 程序一样

### 2. 让手机连得到它（三选一）

**同一个 Wi-Fi**（最简单，出门就不行）
- 查电脑的局域网 IP：Windows 命令行 `ipconfig` 看「IPv4 地址」，Mac 在系统设置 → 网络里，一般是 `192.168.x.x`
- 地址是 `http://192.168.x.x:8800/mcp`
- 电脑防火墙第一次会问要不要放行 Node，选允许（专用网络）
- 电脑睡眠了也会断

**云服务器**（一直在线）
- 在服务器上跑第 1 步，安全组 / 防火墙放开 8800
- 地址是 `http://服务器IP:8800/mcp`
- 口令是明文传的，建议前面套一层 https：Caddy 一行 `你的域名 { reverse_proxy 127.0.0.1:8800 }` 就有证书，然后 HOST 改回 127.0.0.1，地址变成 `https://你的域名/mcp`

**内网穿透**（不想买服务器、出门也要用）
- 装 cloudflared：<https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/>
- 另开一个窗口：`cloudflared tunnel --url http://localhost:8800`
- 它会打出一个 `https://xxxx.trycloudflare.com`，地址就是 `https://xxxx.trycloudflare.com/mcp`
- 这种临时地址每次重开都会变，变了要去前端里改。要固定地址得注册 Cloudflare 建正式隧道
- 走穿透时第 1 步的 HOST 可以不改（留 127.0.0.1），但口令照样要设

先在手机浏览器开 `地址（不带 /mcp）?token=你的口令`，能看到档案页，就说明连得到。

### 3. 前端里填

**RikkaHub**（照它官方文档）
1. 设置 → MCP → 右上角 +
2. 传输方式选 Streamable HTTP（不是 SSE）
3. 名称随便写，比如 `vault`
4. URL 填上一步的地址，`/mcp` 结尾
5. 请求头加一条：名字 `Authorization`，值 `Bearer 你的口令`（Bearer 后面有个空格）
6. 保存，等它显示绿色的 Connected
7. **还要挂到助手上**：长按助手 → 编辑 → 往下翻到 MCP Servers，把 vault 打开。不挂的话这个助手看不到工具

**Kelivo**
1. 设置里找 MCP，添加服务器
2. 类型选 Streamable HTTP
3. 地址填 `/mcp` 结尾那个
4. 有请求头就加 `Authorization: Bearer 你的口令`；找不到请求头的地方，就把口令写在地址里：`https://…/mcp?token=你的口令`
5. 在用的助手里把这个 MCP 打开

**Open WebUI**（0.6.31 以上，要管理员）
1. 管理员设置 → External Tools（有的版本叫 Integrations）→ 添加
2. 类型选 **MCP (Streamable HTTP)**，别选 OpenAPI（选错会一直转圈，删了重加）
3. URL 填地址，认证选 Bearer，填口令
4. 保存，再在模型或者对话里把工具打开

**别的前端**：只要有「Streamable HTTP」「HTTP」「远程 MCP」这类选项就能接，填法都一样：地址 + 口令。只有 SSE 选项的接不了（我们没做 SSE）。

### 4. 看档案

手机浏览器开 `地址（不带 /mcp）?token=你的口令`，加到主屏幕就像个 app。

---

## B · 本机进程（电脑）

前端和道具在同一台电脑上。这条路不用开端口、不用口令。

先把档案页跑起来，用来看档案：

```bash
node serve.js
```

浏览器开 <http://127.0.0.1:8800>。

下面填的路径换成你电脑上解压出来的目录的实际位置。Windows 路径里的反斜杠在 JSON 里要写两个（`C:\\Users\\你\\the-vault\\engine\\mcp-play.js`），或者全换成正斜杠。

**Claude 桌面版**
1. 设置 → 开发者 → 编辑配置，会打开 `claude_desktop_config.json`
   （Windows 在 `%APPDATA%\Claude\`，Mac 在 `~/Library/Application Support/Claude/`）
2. 填进去：
   ```json
   {
     "mcpServers": {
       "play": {
         "command": "node",
         "args": ["/路径/the-vault/engine/mcp-play.js"],
         "env": { "PLAY_STATE_DIR": "/路径/the-vault/state" }
       }
     }
   }
   ```
3. 完全退出 Claude 再打开，输入框旁边的工具列表里能看到 play_use 这些
4. `play.md` 贴进项目说明（Project instructions）里

**Cherry Studio**
1. 设置 → MCP 服务器 → 添加服务器
2. 类型 STDIO，命令 `node`，参数 `/路径/the-vault/engine/mcp-play.js`
3. 环境变量加一条：`PLAY_STATE_DIR=/路径/the-vault/state`
4. 保存、打开开关；对话时在输入框的 MCP 按钮里勾上它
5. 也可以走网络那条：类型选 Streamable HTTP，地址 `http://127.0.0.1:8800/mcp`（开着 serve.js 就行，本机不用口令）

**LibreChat**：`librechat.yaml` 里加
```yaml
mcpServers:
  play:
    command: node
    args: ["/路径/the-vault/engine/mcp-play.js"]
    env:
      PLAY_STATE_DIR: "/路径/the-vault/state"
```
重启，在 Agent 的工具里加上。

**`PLAY_STATE_DIR` 一定要跟 serve.js 用的是同一个目录**（默认就是包里的 `state/`）。不一样的话 AI 写进一本、档案页看的是另一本。

---

## 常见问题

**前端显示连不上**
- 先在手机浏览器开档案页试：打不开 = 网络不通（IP 写错、防火墙、电脑睡了、穿透地址变了）
- 档案页能开但 MCP 连不上：看地址是不是 `/mcp` 结尾、类型是不是 Streamable HTTP
- 返回 401：口令不对，或者 `Bearer` 和口令之间少了空格

**连上了，AI 就是不调**
- 助手 / 对话里没把这个 MCP 打开（RikkaHub 要挂到助手上）
- 模型不支持工具调用，或者前端里工具调用关着
- 没给它 `play.md`。直接跟它说「用一下道具」也行，它会先调 play_status 看有什么

**AI 调了但报错**
- 「空了」「没电」「要歇」是机关本身的设定，不是坏了，AI 照着演就行（play.md 里写了）

**档案页和 AI 说的对不上**：两边的 `PLAY_STATE_DIR` 不是同一个目录。

**换口令**：停掉 serve.js，换个 PLAY_TOKEN 再起，前端里也改掉。

**不想要某几样**：看 README「关掉不要的」。

**数据在哪**：全在 `state/` 里，`play.json` 一个文件。备份就拷它，清空就删它。

---

The Vault by **Lei**。转载、二改公开发布请保留署名，不许商用，见 [LICENSE](../LICENSE)。