twine-play-mcp 0.2.1 → 0.3.0

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 CHANGED
@@ -51,12 +51,13 @@ Then update the support matrix in both READMEs.
51
51
 
52
52
  | Script | Needs | What it covers |
53
53
  | --- | --- | --- |
54
- | `npm test` | nothing | Build, 4-format fixture checks, tool-surface snapshot + byte budget, doc check |
54
+ | `npm test` | nothing | Build, 4-format fixture checks, tool-surface snapshot + byte budget, runtime output budget, doc check |
55
55
  | `npm run smoke` | `TWMCP_GAME` | Full MCP round trip over stdio: open, play, snapshots, downloads, live view |
56
56
  | `npm run spike` | `TWMCP_GAME` | Longer single-format play: variables, N steps, back, screenshot |
57
57
  | `npm run clarity` | `TWMCP_GAME` | Agent-ergonomics regressions: input pagination, label matching, error shape |
58
58
  | `npm run formats` | nothing | Just the fixture checks |
59
59
  | `npm run tools` | nothing | Print the tool surface; refresh `test/tools.snapshot.json` |
60
+ | `npm run economy` | nothing | Print what the tools actually return; `--check` fails when output grows past budget |
60
61
  | `npm run docs` | nothing | Regenerate the README tool tables |
61
62
  | `npm run debug` | varies | Ad-hoc tools — see `npx tsx scripts/debug.ts` for the subcommands |
62
63
  | `npm run fixtures` | Tweego in `.tools/` | Rebuild `test/fixtures/compiled/*.html` from the `.twee` sources |
@@ -81,6 +82,29 @@ npx tsx scripts/tools.ts --budget # fail if the surface or a description grew
81
82
  After an intentional change: refresh the snapshot, bump `SURFACE_BUDGET_BYTES` if the new tool is
82
83
  worth it, and update `scripts/docs.ts` (it fails on an undocumented tool).
83
84
 
85
+ ### The runtime output budget
86
+
87
+ The surface is the small half of the bill. A 20-step run through a real game used to cost
88
+ ~100 KB of observations against a 12 KB surface — the tools were cheap and what they *said*
89
+ was expensive. `scripts/economy.ts` measures the other half: it drives the fixtures through a
90
+ real MCP client and asserts a byte ceiling per case.
91
+
92
+ ```bash
93
+ npx tsx scripts/economy.ts # show the table
94
+ npx tsx scripts/economy.ts --check # fail when a case grows past its budget
95
+ ```
96
+
97
+ Two rules keep this honest:
98
+
99
+ - **Every case opens its own session.** Sharing one lets an earlier case play the story
100
+ forward, so a later case measures an error message instead of the thing it claims to.
101
+ - **Budgets are ceilings, not descriptions.** They were measured once and given headroom;
102
+ a failure means either the renderer regressed or the budget deserves a deliberate bump.
103
+
104
+ The renderer does the work those budgets protect: action results stay lean (story variables are
105
+ opt-in), `observe` prints a delta rather than the whole variable tree, a revisited passage
106
+ collapses to a one-line handle, and unchanged status/UI print as `unchanged`.
107
+
84
108
  ## Docs are generated
85
109
 
86
110
  The tool tables in both READMEs are produced from the live tool list:
package/README-zh.md CHANGED
@@ -97,8 +97,8 @@ live_view({}) # 把一个能实时观看真实页面的 URL 交
97
97
  ## 工具一览
98
98
 
99
99
  工具面刻意保持很小:相关的动词合在一起,而不是各自开一个工具(`navigate` 管 back/restart/goto,
100
- `snapshot` 管 save/load/list,`get_logs` 管 console + journal);只有一个开关的类型收进
101
- `action:` / `kind:` 参数里。
100
+ `snapshot` 管 save/load/list);只有一个开关的类型收进 `action:` / `kind:` 参数里。每个工具只负责
101
+ 一类真相来源:`get_logs` 报告页面报了什么错,`engine` 报告游戏和本会话做了什么。
102
102
 
103
103
  <!-- tools:begin -->
104
104
  **开局与阅读**
@@ -117,6 +117,7 @@ live_view({}) # 把一个能实时观看真实页面的 URL 交
117
117
  | `click_ui` | 按 ref、CSS 选择器或可见文本点击侧边栏按钮与菜单。 |
118
118
  | `interact` | 按 ref 填写输入框/下拉框/复选框,或按键。 |
119
119
  | `navigate` | `back` 回退一段、`restart` 重新开始,或 `goto` 直达指定段落。 |
120
+ | `play` | 一次调用执行多步:只返回紧凑日志 + 最后一次观测,省掉每步的全量观测。写法:`3`、`"标签"`、`wait 800`、`back`、`goto Hall`、`click SAVES`、`fill i1 = hi`、`# 注释`。遇错即停。 |
120
121
 
121
122
  **查看**
122
123
 
@@ -124,7 +125,8 @@ live_view({}) # 把一个能实时观看真实页面的 URL 交
124
125
  | --- | --- |
125
126
  | `find_ui` | 按文本或 input name 查找控件;也可检查某个 DOM 子树或发现浮层面板。 |
126
127
  | `get_variables` | 按点路径读取 SugarCube `State.variables`,或只看顶层键摘要。 |
127
- | `get_logs` | 控制台报错/HTTP 失败,以及游玩日志。 |
128
+ | `engine` | 直接问引擎:段落、回合数、变量数、段落总数、已访问段落、指定变量路径,或本会话做过的动作 —— 约 160 字节,而一次观测约 1.5 KB。 |
129
+ | `get_logs` | 页面产生的 JS 异常、控制台报错与 HTTP 失败。 |
128
130
  | `screenshot` | 视口 PNG —— 用于 canvas 游戏与视觉检查。 |
129
131
  | `live_view` | 让用户在浏览器里实时观看真实页面(约每秒一帧)。 |
130
132
 
@@ -157,16 +159,37 @@ live_view({}) # 把一个能实时观看真实页面的 URL 交
157
159
 
158
160
  | 格式 | 识别 | 文本/选项 | `get_variables` | 段落名 | `navigate(back)` | `snapshot` |
159
161
  | --- | --- | --- | --- | --- | --- | --- |
160
- | **SugarCube 2.21+** | ✅ | ✅ | ✅ `State.variables` | ✅ | ✅ `Engine.backward` | ✅ `Save.base64` / `Save.deserialize` |
161
- | **Harlowe 3** | ✅ | ✅ | —(引擎内部不公开) | — | ✅ 侧边栏撤销 | — |
162
+ | **SugarCube 2.21+** | ✅ | ✅ | ✅ `State.variables` | ✅ | ✅ `Engine.backward` | ✅ `Save.base64` / `Save.deserialize`(遵循 `Config.saves.isAllowed`) |
163
+ | **Harlowe 3** | ✅ | ✅ | ✅ `Saved Session` 轨迹(首段之后) | ✅ `Saved Session` 轨迹 | ✅ 侧边栏撤销(游戏显示时) | — |
162
164
  | **Snowman 2** | ✅ | ✅ | —(改用 `observe(include_variables:true)`) | ✅ | — | ✅ 状态 JSON |
163
165
  | **Chapbook 1** | ✅ | ✅ | —(改用 `observe(include_variables:true)`) | ✅ `trail` | — | ✅ `restoreFromObject` |
164
166
  | **未知 HTML** | 通用 | ✅ DOM 启发式 | — | — | — | — |
165
167
 
168
+ 当游戏自己禁止存档时(SugarCube 的 `Config.saves.isAllowed()`,通常来自 `NoSave` 标签),
169
+ `snapshot` 会返回 `saving-disallowed`,而不是把引擎的异常直接抛给调用方。
170
+
166
171
  `observe` 同样能读到 Snowman(`story.state`)与 Chapbook(`engine.state`)的变量,只有
167
172
  `get_variables` 的点路径查询是 SugarCube 专属。一切都会优雅降级:未知格式仍可走通用 DOM 路径
168
173
  游玩,格式专属的工具会返回 `unsupported` 而不是直接失败。
169
174
 
175
+ `engine` 直接向故事引擎取状态 —— 段落、回合数、变量数、已访问段落、指定变量路径 —— 支持
176
+ SugarCube/Chapbook/Snowman。Harlowe 把引擎藏在模块作用域里,因此明确返回 `unsupported`;
177
+ 它仍可用 `observe(include_variables:true)` 读会话轨迹。
178
+
179
+ ## Token 经济
180
+
181
+ 工具**说了什么**比工具本身贵得多,所以输出和工具面一样有预算(`npm run economy`):
182
+
183
+ - **故事变量改为按需索取。** 动作结果不再附带变量,需要时用 `observe(include_variables:true)`。
184
+ 在 302 个变量的游戏里,这部分曾占一次点击的 43%。
185
+ - **变量按差异输出。** `Variables Δ (1): coins: 7 -> 12` 取代整棵树 —— 这也意味着真正变化的那个
186
+ 键不会再被 2000 字符截断埋掉。
187
+ - **回访段落只给句柄。** Twine 每个段落都会重渲染 PassageHeader/Footer,所以回到看过的段落时只输出
188
+ `(text unchanged since step 3 — cached)`。
189
+ - **未变化的状态栏与侧边栏折叠**为 `Status: unchanged` / `UI: unchanged (6 controls)`。
190
+ - **`engine` 用约 160 字节回答**,而一次完整观测约 1.5 KB。
191
+ - **`play` 批量执行动作**,只返回一份日志加最后一次观测。
192
+
170
193
  ## 疑难排查
171
194
 
172
195
  - **`Could not launch Chrome`** —— 安装 Google Chrome,或用 `TWMCP_CHROME_PATH` 指定路径。
package/README.md CHANGED
@@ -100,8 +100,9 @@ open you must pass it, and the error lists the candidates.
100
100
  ## Tools
101
101
 
102
102
  The surface is deliberately small: related verbs live together rather than each getting a
103
- tool (`navigate` covers back/restart/goto, `snapshot` covers save/load/list, `get_logs` covers
104
- console + journal). Types with one knob fold into `action:` / `kind:` parameters.
103
+ tool (`navigate` covers back/restart/goto, `snapshot` covers save/load/list). Types with one
104
+ knob fold into `action:` / `kind:` parameters. Each tool owns one source of truth: `get_logs`
105
+ reports what the page complained about, `engine` reports what the game and the session did.
105
106
 
106
107
  <!-- tools:begin -->
107
108
  **Open & read**
@@ -120,6 +121,7 @@ console + journal). Types with one knob fold into `action:` / `kind:` parameters
120
121
  | `click_ui` | Click sidebar buttons and menus by ref, CSS selector or visible text. |
121
122
  | `interact` | Fill an input/select/checkbox by ref, or press a key. |
122
123
  | `navigate` | `back` one passage, `restart` the story, or `goto` a named passage. |
124
+ | `play` | Run several actions in one call: one compact log plus the final observation instead of a full observation per step. Tokens: `3`, `"label"`, `wait 800`, `back`, `goto Hall`, `click SAVES`, `fill i1 = hi`, `# note`. Stops at the first failure. |
123
125
 
124
126
  **Inspect**
125
127
 
@@ -127,7 +129,8 @@ console + journal). Types with one knob fold into `action:` / `kind:` parameters
127
129
  | --- | --- |
128
130
  | `find_ui` | Find controls by text or input name; inspect a DOM subtree or discover overlay panels. |
129
131
  | `get_variables` | Read SugarCube `State.variables` by dot path, or a shallow key summary. |
130
- | `get_logs` | Console errors/HTTP failures and the play journal. |
132
+ | `engine` | Ask the story engine directly: passage, turns, variable count, passage total, visited passages, named variable paths, or what this session did — ~160 bytes where an observation costs ~1.5 KB. |
133
+ | `get_logs` | JS exceptions, console errors and HTTP failures the page produced. |
131
134
  | `screenshot` | PNG of the viewport — canvas games and visual QA. |
132
135
  | `live_view` | Let the user watch the real page in their browser (~1 fps). |
133
136
 
@@ -161,17 +164,45 @@ check, never a stream. The server ships this policy in its MCP `instructions` fi
161
164
 
162
165
  | Format | Detect | Text / choices | `get_variables` | Passage name | `navigate(back)` | `snapshot` |
163
166
  | --- | --- | --- | --- | --- | --- | --- |
164
- | **SugarCube 2.21+** | ✅ | ✅ | ✅ `State.variables` | ✅ | ✅ `Engine.backward` | ✅ `Save.base64` / `Save.deserialize` |
165
- | **Harlowe 3** | ✅ | ✅ | — (engine internals are private) | — | ✅ sidebar undo | — |
167
+ | **SugarCube 2.21+** | ✅ | ✅ | ✅ `State.variables` | ✅ | ✅ `Engine.backward` | ✅ `Save.base64` / `Save.deserialize` (respects `Config.saves.isAllowed`) |
168
+ | **Harlowe 3** | ✅ | ✅ | ✅ `Saved Session` trail (after the first passage) | ✅ `Saved Session` trail | ✅ sidebar undo (when the game shows it) | — |
166
169
  | **Snowman 2** | ✅ | ✅ | — (use `observe(include_variables:true)`) | ✅ | — | ✅ state JSON |
167
170
  | **Chapbook 1** | ✅ | ✅ | — (use `observe(include_variables:true)`) | ✅ `trail` | — | ✅ `restoreFromObject` |
168
171
  | **Unknown HTML** | generic | ✅ DOM heuristics | — | — | — | — |
169
172
 
173
+ `snapshot` refuses with `saving-disallowed` on a passage the game itself blocks (SugarCube's
174
+ `Config.saves.isAllowed()`, typically a `NoSave` tag) instead of surfacing the engine's own throw.
175
+
170
176
  `observe` reads variables for Snowman (`story.state`) and Chapbook (`engine.state`) as well; only
171
177
  `get_variables`' dot-path lookup is SugarCube-specific. Everything degrades gracefully: an unknown
172
178
  format still plays through the generic DOM path, and format-specific tools report `unsupported`
173
179
  instead of failing.
174
180
 
181
+ `engine` reads state straight from the story engine — passage, turns, variable count, passage
182
+ total, visited passages, named variable paths — for SugarCube, Chapbook and Snowman. Harlowe keeps
183
+ its engine in module scope and reports `unsupported` there; `observe(include_variables:true)` still
184
+ reads its session trail.
185
+
186
+ `engine(include:"actions")` is the exception: it reports what *this session* did (choices taken,
187
+ snapshots loaded, passages jumped to), not what the game says. It lives here rather than in
188
+ `get_logs` because those are two unrelated questions — "what did the page complain about" and
189
+ "what did I just do" — and answering both in one call cost 2.5 KB.
190
+
191
+ ## Token economy
192
+
193
+ What the tools *say* costs far more than the tools themselves, so the output is budgeted the same
194
+ way the surface is (`npm run economy`):
195
+
196
+ - **Story variables are opt-in.** An action result no longer carries them; ask with
197
+ `observe(include_variables:true)`. On a game with 302 variables that alone was 43% of a click.
198
+ - **Variables print as a diff.** `Variables Δ (1): coins: 7 -> 12` instead of the whole tree —
199
+ which also means the one key that changed is no longer buried by the 2000-char cap.
200
+ - **A revisited passage is a handle.** Twine re-renders PassageHeader/Footer on every passage, so
201
+ going back to a passage you have seen prints `(text unchanged since step 3 — cached)`.
202
+ - **Unchanged status and sidebar collapse** to `Status: unchanged` / `UI: unchanged (6 controls)`.
203
+ - **`engine` answers in ~160 bytes** where a full observation costs ~1.5 KB.
204
+ - **`play` runs a batch** of actions and returns one log plus the final observation.
205
+
175
206
  ## Troubleshooting
176
207
 
177
208
  - **`Could not launch Chrome`** — install Google Chrome, or point `TWMCP_CHROME_PATH` at the binary.