twine-play-mcp 0.1.3 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CONTRIBUTING.md +111 -0
- package/README-zh.md +136 -199
- package/README.md +140 -220
- package/dist/bridge/bridge.js +62 -55
- package/dist/index.js +0 -0
- package/dist/live-view.js +14 -0
- package/dist/live-view.js.map +1 -1
- package/dist/render.js +53 -7
- package/dist/render.js.map +1 -1
- package/dist/server.js +353 -384
- package/dist/server.js.map +1 -1
- package/dist/session.js +152 -43
- package/dist/session.js.map +1 -1
- package/package.json +9 -3
- package/src/bridge/bridge.js +62 -55
- package/src/live-view.ts +15 -0
- package/src/render.ts +51 -8
- package/src/server.ts +374 -428
- package/src/session.ts +184 -46
package/CONTRIBUTING.md
ADDED
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
# Contributing
|
|
2
|
+
|
|
3
|
+
Thanks for helping. The user-facing docs live in [README.md](README.md) /
|
|
4
|
+
[README-zh.md](README-zh.md); everything below is for people working on the server itself.
|
|
5
|
+
|
|
6
|
+
## Repository map
|
|
7
|
+
|
|
8
|
+
```
|
|
9
|
+
src/
|
|
10
|
+
index.ts stdio transport, signal handling
|
|
11
|
+
server.ts the MCP tool surface — one tool per user-facing verb
|
|
12
|
+
session.ts SessionManager: browser, per-game contexts, static server, downloads
|
|
13
|
+
render.ts observations -> the text a model reads
|
|
14
|
+
live-view.ts the local JPEG stream the user watches
|
|
15
|
+
static-server.ts serves a local game over 127.0.0.1 so localStorage/saves work
|
|
16
|
+
bridge/bridge.js injected into every page (plain JS, no build step); sees the DOM
|
|
17
|
+
scripts/ self-checks and dev tools (see below)
|
|
18
|
+
test/fixtures/ 4 story formats compiled to html — the fixture test data
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## How it works
|
|
22
|
+
|
|
23
|
+
- **The page bridge** (`src/bridge/bridge.js`) is injected with `addInitScript` before any game
|
|
24
|
+
script runs, and exposes `window.__twineMCP`. Every DOM-touching operation goes through it:
|
|
25
|
+
format detection, passage/choice extraction, click/fill helpers, settle-waiting, snapshots,
|
|
26
|
+
seeding. It is plain JS on purpose — it is shipped to the browser as-is.
|
|
27
|
+
- **One `BrowserContext` per game** keeps saves and localStorage isolated, and a tiny static server
|
|
28
|
+
puts local games on `http://127.0.0.1` (needed for `localStorage` to work at all).
|
|
29
|
+
- **Every interactive element gets a temporary `data-twmcp-ref`** during an observation. The server
|
|
30
|
+
prefers a real Playwright click, and falls back to a DOM `click()` for exotic macro-generated
|
|
31
|
+
links. Refs are re-assigned on every observation, which is why a stale ref is a normal error.
|
|
32
|
+
- **Spoiler policy**: only what a player can see is returned. No passage list, no source dump.
|
|
33
|
+
|
|
34
|
+
## Adding a story-format adapter
|
|
35
|
+
|
|
36
|
+
1. `src/bridge/bridge.js` — extend `detectFormat()` and the per-format branches of
|
|
37
|
+
`readPassageName()`, `readVariables()`, `back()`, `snapshot()`, `restore()`, `goTo()`, `seed()`.
|
|
38
|
+
Return `{ ok: false, error: 'unsupported', message: '...' }` when the format has no such API —
|
|
39
|
+
never throw, and never fake it.
|
|
40
|
+
2. `test/fixtures/<format>.twee` — add a small three-passage fixture that exercises text, choices,
|
|
41
|
+
a variable, a snapshot round trip and (if supported) `back`.
|
|
42
|
+
3. `test/fixtures/build.sh` — add the `-f <format>` line for Tweego, then `npm run fixtures`.
|
|
43
|
+
4. `scripts/formats.ts` — add a `CASES` entry with the expected behaviour, including which
|
|
44
|
+
capabilities are `unsupported`.
|
|
45
|
+
5. `npx tsx scripts/debug.ts probe <fixture>` dumps the format's DOM and engine globals if you need
|
|
46
|
+
to see what the engine exposes.
|
|
47
|
+
|
|
48
|
+
Then update the support matrix in both READMEs.
|
|
49
|
+
|
|
50
|
+
## Scripts
|
|
51
|
+
|
|
52
|
+
| Script | Needs | What it covers |
|
|
53
|
+
| --- | --- | --- |
|
|
54
|
+
| `npm test` | nothing | Build, 4-format fixture checks, tool-surface snapshot + byte budget, doc check |
|
|
55
|
+
| `npm run smoke` | `TWMCP_GAME` | Full MCP round trip over stdio: open, play, snapshots, downloads, live view |
|
|
56
|
+
| `npm run spike` | `TWMCP_GAME` | Longer single-format play: variables, N steps, back, screenshot |
|
|
57
|
+
| `npm run clarity` | `TWMCP_GAME` | Agent-ergonomics regressions: input pagination, label matching, error shape |
|
|
58
|
+
| `npm run formats` | nothing | Just the fixture checks |
|
|
59
|
+
| `npm run tools` | nothing | Print the tool surface; refresh `test/tools.snapshot.json` |
|
|
60
|
+
| `npm run docs` | nothing | Regenerate the README tool tables |
|
|
61
|
+
| `npm run debug` | varies | Ad-hoc tools — see `npx tsx scripts/debug.ts` for the subcommands |
|
|
62
|
+
| `npm run fixtures` | Tweego in `.tools/` | Rebuild `test/fixtures/compiled/*.html` from the `.twee` sources |
|
|
63
|
+
|
|
64
|
+
`npm test` is the one that must always work on a clean clone: the compiled fixtures are committed
|
|
65
|
+
on purpose, so no Tweego install is needed. The `TWMCP_GAME` scripts skip cleanly (exit 0) when no
|
|
66
|
+
game is configured, so they are safe to wire into CI.
|
|
67
|
+
|
|
68
|
+
### The tool-surface budget
|
|
69
|
+
|
|
70
|
+
`scripts/tools.ts` measures the JSON a client actually receives (`tools/list`) and enforces a byte
|
|
71
|
+
budget plus a per-description limit, and pins tool/parameter names in
|
|
72
|
+
`test/tools.snapshot.json`. Every tool definition costs context in *every* session, so growing the
|
|
73
|
+
surface is a deliberate act, not a side effect.
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
npx tsx scripts/tools.ts # show the surface, refresh the snapshot
|
|
77
|
+
npx tsx scripts/tools.ts --check # fail if names/parameters changed
|
|
78
|
+
npx tsx scripts/tools.ts --budget # fail if the surface or a description grew past budget
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
After an intentional change: refresh the snapshot, bump `SURFACE_BUDGET_BYTES` if the new tool is
|
|
82
|
+
worth it, and update `scripts/docs.ts` (it fails on an undocumented tool).
|
|
83
|
+
|
|
84
|
+
## Docs are generated
|
|
85
|
+
|
|
86
|
+
The tool tables in both READMEs are produced from the live tool list:
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
npx tsx scripts/docs.ts # regenerate the blocks between the markers
|
|
90
|
+
npx tsx scripts/docs.ts --check # fail when they are stale
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Only the group labels and one-line summaries in `scripts/docs.ts` are hand-written. If you add a
|
|
94
|
+
tool, `docs.ts` fails until it is mapped there — that is intentional, so the README cannot drift.
|
|
95
|
+
|
|
96
|
+
## Style notes
|
|
97
|
+
|
|
98
|
+
- Keep tool **descriptions** short; put detail in the parameter descriptions. `tools.ts --budget`
|
|
99
|
+
enforces a per-description limit.
|
|
100
|
+
- Error messages must be actionable: a `Hint`, and the choices/passages the agent can act on.
|
|
101
|
+
Prefer `errResult()` over a bare `errorText()` in a `catch`.
|
|
102
|
+
- Never swallow a failure into a silently-empty result — a poisoned observation is worse than a
|
|
103
|
+
loud error.
|
|
104
|
+
- `src/bridge/bridge.js` is not type-checked. Change it carefully and lean on `npm test` and
|
|
105
|
+
`npm run smoke`.
|
|
106
|
+
|
|
107
|
+
## Roadmap
|
|
108
|
+
|
|
109
|
+
- [ ] `click_at(x, y)` for canvas-only games
|
|
110
|
+
- [ ] Optional spoiler-gated story-map analysis
|
|
111
|
+
- [ ] A second fixture per format covering dialogs and iframes
|
package/README-zh.md
CHANGED
|
@@ -2,261 +2,198 @@
|
|
|
2
2
|
|
|
3
3
|
[English](README.md) · **简体中文**
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
让 AI agent **游玩、测试并 QA Twine / 互动小说 HTML 游戏** 的 MCP 服务。
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
7
|
+
agent 能读取当前段落、点击带编号的选项、填写输入框、观察故事变量、应答游戏对话框、存快照以
|
|
8
|
+
探索分支,还能把真实页面实时投给你看——用的是一个小巧省 token 的工具面,而不是通用浏览器自动化。
|
|
9
9
|
|
|
10
10
|
```
|
|
11
11
|
Agent ──MCP(stdio)──> twine-play-mcp ──Playwright──> 无头 Chrome
|
|
12
12
|
│ │
|
|
13
13
|
│ 静态服务器 (127.0.0.1) │ 注入页面桥
|
|
14
|
-
└────────>
|
|
14
|
+
└────────> 游戏 HTML <──────────┘
|
|
15
15
|
```
|
|
16
16
|
|
|
17
|
-
## 为什么不用通用浏览器 MCP?
|
|
18
|
-
|
|
19
|
-
通用浏览器 MCP 会让模型去猜 DOM 选择器、把整页内容灌进上下文,而且完全没有「剧情状态」的概念。
|
|
20
|
-
本服务在之上加了一层语义:
|
|
21
|
-
|
|
22
|
-
- **段落视图**:文本以 Markdown 呈现,附带段落名、游戏格式/版本、剧情元数据
|
|
23
|
-
- **编号选项**:标注目标段落名(并默认拦截外链)
|
|
24
|
-
- **剧情变量**(SugarCube `State.variables`):带安全的深度/体积上限
|
|
25
|
-
- **原生状态**:SugarCube `Engine.backward/forward`、`Save.base64` 快照
|
|
26
|
-
- **格式探测**:优先 SugarCube,其余(Harlowe / Snowman / Chapbook / 未知)走 DOM 兜底
|
|
27
|
-
- **追踪器拦截**,以及干净的 console/网络捕获,方便做游戏测试
|
|
28
|
-
|
|
29
17
|
## 环境要求
|
|
30
18
|
|
|
31
|
-
- Node.js
|
|
32
|
-
- 已安装 Google Chrome
|
|
19
|
+
- **Node.js ≥ 20**
|
|
20
|
+
- 已安装 **Google Chrome**(通过 `channel: 'chrome'` 调用,不会额外下载 200 MB 浏览器)
|
|
33
21
|
- Linux / macOS / Windows
|
|
34
22
|
|
|
35
23
|
## 安装
|
|
36
24
|
|
|
37
25
|
```bash
|
|
38
|
-
npm install -g twine-play-mcp #
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
无需构建、无需下载浏览器——包内已包含编译好的服务端与页面桥,直接驱动你已有的 Chrome。
|
|
42
|
-
|
|
43
|
-
然后把它指向任意已发布的 Twine HTML 文件(或包含游戏与资源的文件夹):
|
|
44
|
-
|
|
45
|
-
```bash
|
|
46
|
-
twine-play-mcp # 在 stdio 上运行 MCP 服务
|
|
26
|
+
npm install -g twine-play-mcp # 或者直接:npx twine-play-mcp
|
|
47
27
|
```
|
|
48
28
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
```bash
|
|
52
|
-
git clone https://github.com/adorablelovelymia/twine-play-mcp.git
|
|
53
|
-
cd twine-play-mcp
|
|
54
|
-
npm install
|
|
55
|
-
npm run build # 编译到 dist/ 并复制页面桥
|
|
56
|
-
|
|
57
|
-
# 可选的自检
|
|
58
|
-
npm run spike # 针对真实 SugarCube 游戏的 17 项端到端检查
|
|
59
|
-
npm run smoke # 以 stdio 启动 MCP 服务,并用 MCP SDK 驱动它
|
|
60
|
-
```
|
|
29
|
+
npm 包里已包含编译好的服务端与页面桥,无需构建步骤。
|
|
61
30
|
|
|
62
31
|
## 客户端配置
|
|
63
32
|
|
|
64
|
-
|
|
65
|
-
替换为单独一个 `"twine-play-mcp"` 即可。
|
|
66
|
-
|
|
67
|
-
### OpenCode(`~/.config/opencode/opencode.json`)
|
|
33
|
+
把服务加进你的 MCP 客户端。任何 `mcpServers` 形式的客户端都可以:
|
|
68
34
|
|
|
69
35
|
```json
|
|
70
36
|
{
|
|
71
|
-
"
|
|
72
|
-
"mcp": {
|
|
37
|
+
"mcpServers": {
|
|
73
38
|
"twine-play": {
|
|
74
|
-
"
|
|
75
|
-
"
|
|
76
|
-
"enabled": true
|
|
39
|
+
"command": "npx",
|
|
40
|
+
"args": ["-y", "twine-play-mcp"]
|
|
77
41
|
}
|
|
78
42
|
}
|
|
79
43
|
}
|
|
80
44
|
```
|
|
81
45
|
|
|
82
|
-
|
|
46
|
+
OpenCode 用自己的一套结构(`~/.config/opencode/opencode.json`):
|
|
83
47
|
|
|
84
48
|
```json
|
|
85
49
|
{
|
|
86
|
-
"
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
"args": ["-y", "twine-play-mcp"]
|
|
90
|
-
}
|
|
50
|
+
"$schema": "https://opencode.ai/config.json",
|
|
51
|
+
"mcp": {
|
|
52
|
+
"twine-play": { "type": "local", "command": ["npx", "-y", "twine-play-mcp"], "enabled": true }
|
|
91
53
|
}
|
|
92
54
|
}
|
|
93
55
|
```
|
|
94
56
|
|
|
95
|
-
|
|
57
|
+
现成配置文件见 [`examples/`](examples)。环境变量全部可选:
|
|
96
58
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
59
|
+
- `TWMCP_CHROME_PATH` —— `channel: 'chrome'` 找不到时的 Chrome 可执行文件路径
|
|
60
|
+
- `TWMCP_DOWNLOAD_DIR` —— 浏览器下载的捕获目录(默认 `~/.cache/twine-play-mcp/downloads`,不可写时自动降级)
|
|
61
|
+
- `TWMCP_VIEW_HOST` / `TWMCP_VIEW_PORT` —— 实时视图的绑定地址(默认 `127.0.0.1`)与起始端口(默认 `4571`,占用时递增)
|
|
62
|
+
- `TWMCP_BLOCK_TRACKERS` —— 设为 `0` 可不再拦截统计站点
|
|
63
|
+
|
|
64
|
+
## 快速开始
|
|
65
|
+
|
|
66
|
+
让 agent 做这件事即可——**游戏路径是 `open_game` 工具的入参,不是命令行参数**。
|
|
67
|
+
不存在 `twine-play-mcp game.html` 这种用法。
|
|
68
|
+
|
|
69
|
+
> 用 twine-play-mcp 打开 `/path/to/game.html`,告诉我第一段写了什么。
|
|
70
|
+
|
|
71
|
+
底层发生的事,以及 agent 看到的内容:
|
|
72
|
+
|
|
73
|
+
```
|
|
74
|
+
open_game({ source: "/path/to/game.html" })
|
|
75
|
+
Opened game "game_c5ac1a" (/path/to/game.html)
|
|
76
|
+
game_id: game_c5ac1a
|
|
77
|
+
Story: TS Ero Trap Dungeon · Format: sugarcube 2.31.1 · ifid: ...
|
|
78
|
+
Served from: http://127.0.0.1:41235/
|
|
79
|
+
[sugarcube 2.31.1 · step 0 · engine=idle · passage: Title]
|
|
80
|
+
...
|
|
81
|
+
Choices (1):
|
|
82
|
+
1. Start -> Prologue
|
|
83
|
+
|
|
84
|
+
choose({ choice: 1 }) # 或者 click_ui / interact / navigate
|
|
85
|
+
Clicked: "Start" -> Prologue
|
|
86
|
+
[sugarcube 2.31.1 · step 1 · engine=idle · passage: Prologue]
|
|
87
|
+
...
|
|
88
|
+
|
|
89
|
+
observe({ for_text: "你醒来" }) # 等待定时段落,然后读取
|
|
90
|
+
interact({ ref: "i1", value: "Shiori" }) # 填写表单
|
|
91
|
+
snapshot({ action: "save", name: "before-boss" })
|
|
92
|
+
live_view({}) # 把一个能实时观看真实页面的 URL 交给用户
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
只打开一个游戏时 `game_id` 可以省略,少些噪音;打开多个时必须传,报错会把候选列出来。
|
|
102
96
|
|
|
103
97
|
## 工具一览
|
|
104
98
|
|
|
99
|
+
工具面刻意保持很小:相关的动词合在一起,而不是各自开一个工具(`navigate` 管 back/restart/goto,
|
|
100
|
+
`snapshot` 管 save/load/list,`get_logs` 管 console + journal);只有一个开关的类型收进
|
|
101
|
+
`action:` / `kind:` 参数里。
|
|
102
|
+
|
|
103
|
+
<!-- tools:begin -->
|
|
104
|
+
**开局与阅读**
|
|
105
|
+
|
|
106
|
+
| 工具 | 作用 |
|
|
107
|
+
| --- | --- |
|
|
108
|
+
| `open_game` | 打开本地文件/文件夹或 http(s) 网址,返回第一次观测。 |
|
|
109
|
+
| `observe` | 当前段落文本、选项、输入框、对话框与状态栏。传 `for_text` 或 `wait_ms` 可先等待。 |
|
|
110
|
+
| `session` | `list` 列出已打开的游戏,`close` 关闭其中一个。 |
|
|
111
|
+
|
|
112
|
+
**操作**
|
|
113
|
+
|
|
114
|
+
| 工具 | 作用 |
|
|
115
|
+
| --- | --- |
|
|
116
|
+
| `choose` | 按 1-based 编号或标签点击选项,对话框按钮同样适用。 |
|
|
117
|
+
| `click_ui` | 按 ref、CSS 选择器或可见文本点击侧边栏按钮与菜单。 |
|
|
118
|
+
| `interact` | 按 ref 填写输入框/下拉框/复选框,或按键。 |
|
|
119
|
+
| `navigate` | `back` 回退一段、`restart` 重新开始,或 `goto` 直达指定段落。 |
|
|
120
|
+
|
|
121
|
+
**查看**
|
|
122
|
+
|
|
105
123
|
| 工具 | 作用 |
|
|
106
124
|
| --- | --- |
|
|
107
|
-
| `
|
|
108
|
-
| `
|
|
109
|
-
| `
|
|
110
|
-
| `
|
|
111
|
-
| `
|
|
112
|
-
| `find_ui` | 按可见文本或输入项 name 查找按钮/链接/**label**/输入框;返回 ref 供 `click_ui`/`interact` 使用。是触达单选/复选选项(SugarCube 宏标签)最快的方式 |
|
|
113
|
-
| `click_ui` | 点击对话框、侧边栏与菜单(可按 ref / CSS 选择器 / 可见文本),支持基于 `<label>` 的控件与 iframe |
|
|
114
|
-
| `upload_file` | 把本地文件上传到 `<input type=file>`(mod `.zip`、`.save` 导入),可通过触发按钮或直接指定输入框,支持 iframe |
|
|
115
|
-
| `download_file` | 浏览器文件控制(适用于任意游戏):把已捕获的下载复制到指定路径——可按 `trigger_text`/`trigger_ref`(点击游戏自己的下载按钮)、按下载目录中的 `name`/`index`,或默认取最新文件。目录中的副本会保留 |
|
|
116
|
-
| `list_downloads` | 列出捕获到工具持久下载目录中的文件(跨会话/重启保留),含文件名、大小、时间与绝对路径 |
|
|
117
|
-
| `inspect_ui` | 检查或发现段落之外的 UI 面板(mod 界面、后台);列出按钮/输入框与文件输入框 |
|
|
118
|
-
| `get_variables` | 按点路径读取剧情变量(`V.hairlength`),或给出顶层键的浅层摘要;避免倾倒整个变量状态 |
|
|
119
|
-
| `back` | 回退一个段落(SugarCube `Engine.backward`) |
|
|
120
|
-
| `restart` | 从头重新开始,可选择重新播种 PRNG |
|
|
121
|
-
| `save_state` / `load_state` | 会话内命名快照,用于探索分支 |
|
|
122
|
-
| `screenshot` | 视口 PNG 截图(canvas/视觉类游戏、视觉 QA);传 `path` 可存盘 |
|
|
123
|
-
| `live_view` | 让用户看到真实页面:本地 URL 流式输出真实 Playwright 标签页的 JPEG 帧(约 1 帧/秒)+ 段落/步数/日志;无头模式同样可用;`open:true` 会用默认浏览器打开 |
|
|
124
|
-
| `get_console_errors` | 页面捕获到的 JS 异常、console 错误与 HTTP 失败 |
|
|
125
|
-
| `get_journal` | 操作历史:访问过的段落、做过的选择、覆盖率统计 |
|
|
126
|
-
| `list_games` / `close_game` | 会话管理 |
|
|
127
|
-
|
|
128
|
-
### 观看页面(实时视图)
|
|
129
|
-
|
|
130
|
-
`live_view(game_id)` 会启动一个极小的本地服务(每个 MCP 进程只启动一次,端口 4571 起),返回形如
|
|
131
|
-
`http://127.0.0.1:4571/v/game_abc` 的网址。用任意浏览器打开它(或传 `open: true`),即可看到
|
|
132
|
-
**agent 正在操作的那个真实标签页**——约每秒一帧 JPEG,外加段落、步数、引擎状态、最近操作与段落文本。
|
|
133
|
-
它对无头游戏同样有效;只有有人观看时才抓帧;关闭游戏即停止。若想要一个原生的浏览器窗口,请改用
|
|
134
|
-
`headless: false` 打开游戏(`open_game`)。
|
|
135
|
-
|
|
136
|
-
实用组合:如果你的客户端能在侧边栏显示网页(例如 OpenCode 的 Review 面板 /
|
|
137
|
-
`browser.tabs.open`),把实时视图的网址指过去,就能一边看 agent 游玩一边跟进。
|
|
138
|
-
|
|
139
|
-
**只选一种显示方式(给 agent 的规则)。** 为了保持用户屏幕整洁,展示正在运行的游戏时只用一个渠道,
|
|
140
|
-
绝不叠加:
|
|
141
|
-
|
|
142
|
-
1. **默认:** `live_view`——把网址交给用户,或传一次 `open: true` 替他打开。重复调用会复用同一个视图,
|
|
143
|
-
不会新开标签页。
|
|
144
|
-
2. **仅在明确要求时:** 用户要真实浏览器窗口时才用 `open_game(headless: false)`。不要再叠加实时视图——
|
|
145
|
-
有头窗口本身已经可见了。
|
|
146
|
-
3. `screenshot` 是一次性的视觉检查,**不是流**——不要循环调用来「展示」游戏。
|
|
147
|
-
|
|
148
|
-
如果某个视图(实时视图标签页或有头窗口)已经打开,请复用它而不是再开一个。MCP 服务把这条策略也写进了
|
|
149
|
-
自己的 `instructions` 字段,因此 MCP 客户端可以自动把它传给模型;相关工具的说明里也重复了这一点
|
|
150
|
-
(`live_view`、`open_game.headless`、`screenshot`)。
|
|
151
|
-
|
|
152
|
-
### Agent 使用体验
|
|
153
|
-
|
|
154
|
-
- **输出**:每个游玩类工具都返回格式化后的文本观察结果(字符串)。传 `format:"json"` 则改为返回一个
|
|
155
|
-
JSON 字符串(用 `JSON.parse` 解析),包含 `passage`、`text`、`choices[{n,label,target}]`、
|
|
156
|
-
`inputs[{ref,kind,label,checked}]`、`inputsTotal`、`dialog`、`status`。
|
|
157
|
-
- **输入项是分页而非截断**:出现形如 `Inputs (41-80 of 140)` 的表头时,配合 `inputs_offset=80`
|
|
158
|
-
就能触达全部内容——不存在静默的硬上限。
|
|
159
|
-
- **标签匹配**:`click_ui(text)` 与 `find_ui(text)` 能理解 SugarCube `<<radiobutton>>` /
|
|
160
|
-
`<<checkbox>>` 的标签,所以「Jet black」这类选项或「Punch」这类战斗指令都能按文本点击。
|
|
161
|
-
- **错误信息精简**:失败时返回 `ERROR: code — message`、一条 `Hint`、当前段落与可用选项——
|
|
162
|
-
绝不倾倒完整的观察结果。
|
|
163
|
-
- **变量**:观察结果默认不内嵌变量数据块;用 `get_variables` 只取你关心的键。
|
|
164
|
-
需要(截断后的)全量数据时仍可用 `include_variables:true`。
|
|
165
|
-
- **对话框**:对话框按钮会以编号选项的形式出现并标记 `[dialog]`,同时有一行 `Dialog buttons:`
|
|
166
|
-
列出它们;复选框标签会显示在输入项那一行。
|
|
125
|
+
| `find_ui` | 按文本或 input name 查找控件;也可检查某个 DOM 子树或发现浮层面板。 |
|
|
126
|
+
| `get_variables` | 按点路径读取 SugarCube `State.variables`,或只看顶层键摘要。 |
|
|
127
|
+
| `get_logs` | 控制台报错/HTTP 失败,以及游玩日志。 |
|
|
128
|
+
| `screenshot` | 视口 PNG —— 用于 canvas 游戏与视觉检查。 |
|
|
129
|
+
| `live_view` | 让用户在浏览器里实时观看真实页面(约每秒一帧)。 |
|
|
167
130
|
|
|
131
|
+
**文件与状态**
|
|
132
|
+
|
|
133
|
+
| 工具 | 作用 |
|
|
134
|
+
| --- | --- |
|
|
135
|
+
| `snapshot` | 会话内状态快照的 `save`/`load`/`list`,用于分支探索。 |
|
|
136
|
+
| `upload_file` | 把 mod `.zip`、`.save` 或图片上传到 `<input type=file>`。 |
|
|
137
|
+
| `download_file` | `list` 列出持久下载目录,或用 `save`/`newest` 取出捕获的文件。 |
|
|
138
|
+
<!-- tools:end -->
|
|
139
|
+
|
|
140
|
+
每个工具的细节都在它自己的 description 里——调用一次、看看参数就清楚了。默认输出是给人看的
|
|
141
|
+
格式化文本;传 `format: "json"` 可拿到能 `JSON.parse` 的结果(`observe`、`choose`、
|
|
142
|
+
`click_ui`、`interact`、`navigate`、`snapshot`、`upload_file`、`download_file`、`open_game`)。
|
|
143
|
+
|
|
144
|
+
## 观看页面
|
|
145
|
+
|
|
146
|
+
`live_view` 会启动一个极小的本地服务(每个 MCP 进程只启动一次),返回类似
|
|
147
|
+
`http://127.0.0.1:4571/v/game_c5ac1a` 的地址。打开它就能看到 **agent 正在操作的那个真实标签页**:
|
|
148
|
+
约每秒一帧 JPEG,外加段落名、步数、引擎状态和最近的操作。无头模式同样可用,并且只有有人观看时
|
|
149
|
+
才会抓帧。
|
|
150
|
+
|
|
151
|
+
**给 agent 的约定:每个游戏只开一种视图。** 默认用 `live_view`(用户希望你直接打开时,只传一次
|
|
152
|
+
`open: true`)。只有用户明确要一个真实浏览器窗口时,才用 `open_game({ headless: false })`,
|
|
153
|
+
并且不要再叠加实时视图。`screenshot` 是一次性的视觉检查,不是视频流。这条策略也随 MCP 的
|
|
154
|
+
`instructions` 字段一起下发。
|
|
168
155
|
|
|
169
156
|
## 格式支持
|
|
170
157
|
|
|
171
|
-
| 格式 |
|
|
158
|
+
| 格式 | 识别 | 文本/选项 | `get_variables` | 段落名 | `navigate(back)` | `snapshot` |
|
|
172
159
|
| --- | --- | --- | --- | --- | --- | --- |
|
|
173
|
-
| **SugarCube 2.21+** | ✅ | ✅ | ✅ `State.variables` | ✅ | ✅ `Engine.backward` | ✅ `Save.base64
|
|
174
|
-
| **Harlowe 3** | ✅ | ✅ |
|
|
175
|
-
| **Snowman 2** | ✅ | ✅ |
|
|
176
|
-
| **Chapbook 1** | ✅ | ✅ |
|
|
160
|
+
| **SugarCube 2.21+** | ✅ | ✅ | ✅ `State.variables` | ✅ | ✅ `Engine.backward` | ✅ `Save.base64` / `Save.deserialize` |
|
|
161
|
+
| **Harlowe 3** | ✅ | ✅ | —(引擎内部不公开) | — | ✅ 侧边栏撤销 | — |
|
|
162
|
+
| **Snowman 2** | ✅ | ✅ | —(改用 `observe(include_variables:true)`) | ✅ | — | ✅ 状态 JSON |
|
|
163
|
+
| **Chapbook 1** | ✅ | ✅ | —(改用 `observe(include_variables:true)`) | ✅ `trail` | — | ✅ `restoreFromObject` |
|
|
177
164
|
| **未知 HTML** | 通用 | ✅ DOM 启发式 | — | — | — | — |
|
|
178
165
|
|
|
179
|
-
|
|
180
|
-
|
|
166
|
+
`observe` 同样能读到 Snowman(`story.state`)与 Chapbook(`engine.state`)的变量,只有
|
|
167
|
+
`get_variables` 的点路径查询是 SugarCube 专属。一切都会优雅降级:未知格式仍可走通用 DOM 路径
|
|
168
|
+
游玩,格式专属的工具会返回 `unsupported` 而不是直接失败。
|
|
181
169
|
|
|
182
|
-
##
|
|
170
|
+
## 疑难排查
|
|
183
171
|
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
172
|
+
- **`Could not launch Chrome`** —— 安装 Google Chrome,或用 `TWMCP_CHROME_PATH` 指定路径。
|
|
173
|
+
- **`Multiple HTML files in <dir>`** —— 该目录有多个 html,直接传具体的 `.html` 文件。
|
|
174
|
+
- **传了文件路径却毫无反应** —— 路径是给 `open_game` 的;命令行不接受参数。
|
|
175
|
+
- **实时视图端口被占用** —— 它会从 4571 起自动递增,用返回的 URL 即可。
|
|
176
|
+
- **没看到下载的文件** —— 看 `download_file(action:"list")` 打印的目录;不可写时会自动降级。
|
|
177
|
+
- **某个工具返回 `unsupported`** —— 该格式没有对应 API(见上表)。
|
|
187
178
|
|
|
188
|
-
|
|
189
|
-
1. Go deeper -> 070
|
|
190
|
-
2. Check the mirror
|
|
179
|
+
## 安全说明
|
|
191
180
|
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
```
|
|
181
|
+
- 页面脚本运行在 Chrome 沙箱里;页面桥不会把 Node 暴露给页面,也不向 agent 暴露任意 `eval` 工具。
|
|
182
|
+
- 默认拦截统计/追踪域名(`TWMCP_BLOCK_TRACKERS=0` 可关闭)。
|
|
183
|
+
- 除非传 `allow_external: true`,离开游戏的链接一律拦截。`open_game` 只用 `127.0.0.1` 提供本地游戏,且仅能读取被服务根目录下的文件。
|
|
196
184
|
|
|
197
|
-
##
|
|
198
|
-
|
|
199
|
-
- `src/bridge/bridge.js` 通过 `addInitScript` 注入每个页面,暴露 `window.__twineMCP`:
|
|
200
|
-
格式探测、段落/选项提取、点击/填写辅助、等待稳定、快照与随机种子。所有服务端调用都只经由这个桥。
|
|
201
|
-
- `src/session.ts` 持有浏览器,每个游戏一个 `BrowserContext`(存档互相隔离),并内置一个极小的
|
|
202
|
-
静态服务器,让本地游戏运行在 `http://127.0.0.1` 上(这样 localStorage 才能工作)。
|
|
203
|
-
- `src/render.ts` 把观察结果转成给模型看的精简 Markdown。
|
|
204
|
-
- 选项会被临时打上 `data-twmcp-ref` 属性;服务端优先使用真实的 Playwright 点击,对冷门宏生成的
|
|
205
|
-
链接则回退到 DOM 点击。
|
|
206
|
-
- 剧透策略:只返回玩家能看到的内容。不暴露段落列表或源码。
|
|
207
|
-
|
|
208
|
-
## 复杂游戏
|
|
209
|
-
|
|
210
|
-
真实游戏不只是段落和链接。本 MCP 处理了那些棘手的部分:
|
|
211
|
-
|
|
212
|
-
- **模态对话框**(SugarCube `#ui-dialog`、内容门禁、设置):其文本会以 `Dialog:` 块出现,
|
|
213
|
-
按钮/输入项像选项一样编号,因此 agent 可以勾选同意条款(`interact`)再点 `Enter`(`choose`)。
|
|
214
|
-
- **iframe**:mod 管理器与开发者面板常常位于子框架中。`inspect_ui` 会发现它们(标记 `[iframe]`),
|
|
215
|
-
`click_ui` 按文本、`upload_file` 都会搜索每个框架。
|
|
216
|
-
- **文件工作流**:上传走 `upload_file`(mod `.zip`、存档导入)——可点击触发元素
|
|
217
|
-
(`trigger_text` / `trigger_selector`,例如 `#saves-import`)或直接指向 `<input type=file>`。
|
|
218
|
-
下载则反向经过一个持久下载目录:浏览器每次下载都会被捕获到那里(`TWMCP_DOWNLOAD_DIR`
|
|
219
|
-
可覆盖位置),`list_downloads` 显示目录内容,`download_file` 可把它复制到任意位置(`path`,
|
|
220
|
-
默认 `<cwd>/downloads/<name>`)——既可点击游戏自己的导出按钮,也可事后再按 `name`/`index` 取。
|
|
221
|
-
无需手动复制临时目录,且文件在 `close_game` 与 MCP 重启后依然保留。
|
|
222
|
-
- **DoL 案例研究**:除 `test/fixtures` 外,`scripts/dol-mcp-test.ts` 端到端驱动
|
|
223
|
-
Degrees of Lewdity——同意门禁 → 通过游戏内 ModLoader 界面导入 `ModI18N.mod.zip` 与
|
|
224
|
-
`GameOriginalImagePack.mod.zip` → 页面重载 → 通过 SAVES 对话框导入真实 `.save` →
|
|
225
|
-
正常游玩若干回合。
|
|
226
|
-
|
|
227
|
-
## 测试
|
|
185
|
+
## 开发
|
|
228
186
|
|
|
229
187
|
```bash
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
npm
|
|
233
|
-
npm
|
|
234
|
-
npm run fixtures # 用 Tweego 重新构建 test/fixtures/compiled/*.html(见 test/fixtures/build.sh)
|
|
235
|
-
npx tsx scripts/dol-mcp-test.ts # Degrees of Lewdity:门禁、mod 导入、存档导入、游玩
|
|
188
|
+
git clone https://github.com/adorablelovelymia/twine-play-mcp.git
|
|
189
|
+
cd twine-play-mcp
|
|
190
|
+
npm install
|
|
191
|
+
npm test # 构建 + 四格式夹具检查 + 工具面快照/预算
|
|
236
192
|
```
|
|
237
193
|
|
|
238
|
-
`
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
- [x] M1:SugarCube 适配器、通用 DOM 兜底、观察/选项/输入/等待/截图、快照、回退、
|
|
243
|
-
console+网络 QA 捕获、stdio MCP、spike + smoke 测试
|
|
244
|
-
- [x] M2:Harlowe / Chapbook / Snowman 适配器,已针对编译夹具验证
|
|
245
|
-
- [x] M2:游玩日志(`get_journal`),用于运行摘要、续玩与 QA 覆盖率
|
|
246
|
-
- [x] M3:对话框/iframe 感知的 UI 控制(`click_ui`、`inspect_ui`、`upload_file`)——
|
|
247
|
-
已在 Degrees of Lewdity 上验证(mod 导入 + 存档导入 + 游玩)
|
|
248
|
-
- [x] M4:agent 使用体验——输入分页 + 总数、`find_ui` 标签搜索、`get_variables`、
|
|
249
|
-
`format:"json"`、精简错误(源自一次「天真 agent」试玩,它在 DoL 角色创建处卡住)
|
|
250
|
-
- [x] M4:双向文件工作流——`upload_file` 处理 mod/存档,`download_file` + `list_downloads`
|
|
251
|
-
提供持久下载目录(无需复制临时目录)
|
|
252
|
-
- [x] M5:实时视图——在任意浏览器中观看真实页面(约 1 fps 帧 + 段落/步数/日志);
|
|
253
|
-
有头模式通过 `open_game(headless: false)`
|
|
254
|
-
- [x] M5:npm 打包——已发布为 [`twine-play-mcp`](https://www.npmjs.com/package/twine-play-mcp)
|
|
255
|
-
- [ ] M3:面向 canvas 游戏的 `click_at`、受剧透限制的剧情地图分析
|
|
256
|
-
|
|
257
|
-
## 安全说明
|
|
194
|
+
`npm test` 不需要任何外部游戏——夹具就在仓库里。更重的检查(`npm run smoke`、
|
|
195
|
+
`npm run spike`、`npm run clarity`)会驱动真实游戏,需要
|
|
196
|
+
`TWMCP_GAME=/path/to/game.html`;没设置就自动跳过。
|
|
258
197
|
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
- 默认拦截分析/追踪类主机(可用 `block_trackers: false` 关闭)。
|
|
262
|
-
- 除非传入 `allow_external: true`,否则外链一律拦截。
|
|
198
|
+
架构说明、新增 story format 适配器的步骤、脚本索引与路线图都在
|
|
199
|
+
**[CONTRIBUTING.md](CONTRIBUTING.md)**。
|