@tarve/mcp 0.0.0-stage → 0.11.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/src/tools.ts ADDED
@@ -0,0 +1,406 @@
1
+ import { readFileSync, rmSync } from "node:fs";
2
+ import { join } from "node:path";
3
+ import type { NodeSnapshot, Snapshot } from "@tarve/core/protocol";
4
+ import { textResult, type Tool, type ToolResult } from "./server";
5
+ import type { AppSession } from "./session";
6
+
7
+ /** The app's tree as `controlTree` sends it (packages/core/src/devtools/control.ts). */
8
+ export interface ControlNode {
9
+ id: string;
10
+ kind: string;
11
+ text?: string;
12
+ value?: string;
13
+ placeholder?: string;
14
+ disabled?: boolean;
15
+ src?: string;
16
+ style?: Record<string, unknown>;
17
+ children: ControlNode[];
18
+ }
19
+
20
+ interface Point { x: number; y: number }
21
+
22
+ const KEYS: Record<string, string> = {
23
+ enter: "Enter", return: "Enter", tab: "Tab", esc: "Escape", escape: "Escape", space: "Space",
24
+ backspace: "Backspace", delete: "Delete", del: "Delete", home: "Home", end: "End",
25
+ pageup: "PageUp", pagedown: "PageDown", up: "ArrowUp", down: "ArrowDown", left: "ArrowLeft", right: "ArrowRight",
26
+ arrowup: "ArrowUp", arrowdown: "ArrowDown", arrowleft: "ArrowLeft", arrowright: "ArrowRight", selectall: "SelectAll",
27
+ };
28
+ export const keyName = (key: string): string => KEYS[key.trim().toLowerCase()] ?? key.trim();
29
+
30
+ const label = (node: NodeSnapshot): string => node.control?.label ?? node.text ?? "";
31
+ const visible = (node: NodeSnapshot): boolean => node.width > 0 && node.height > 0;
32
+ const round = (value: number): number => Math.round(value * 10) / 10;
33
+ const box = (node: { x: number; y: number; width: number; height: number }): string => `${round(node.x)},${round(node.y)} ${round(node.width)}x${round(node.height)}`;
34
+ const quote = (text: string, max = 80): string => JSON.stringify(text.length > max ? `${text.slice(0, max - 1)}…` : text);
35
+ const json = (value: unknown): ToolResult => textResult(JSON.stringify(value, null, 2));
36
+
37
+ /** The node for `text`: exact label first, then substring; the smallest box wins (as `--tarve-script click:`). */
38
+ export function findByText(snapshot: Snapshot, text: string, exact = false): NodeSnapshot | undefined {
39
+ const shown = snapshot.nodes.filter(visible);
40
+ const same = shown.filter(node => label(node) === text);
41
+ const matches = same.length || exact ? same : shown.filter(node => label(node).includes(text));
42
+ return matches.sort((a, b) => a.width * a.height - b.width * b.height)[0];
43
+ }
44
+
45
+ /** An indented outline of the tree, one node per line, with each node's window box. */
46
+ export function outline(root: ControlNode, snapshot: Snapshot | undefined, options: { maxDepth?: number; maxNodes?: number; styles?: boolean; visibleOnly?: boolean } = {}): string {
47
+ const maxDepth = options.maxDepth ?? 12, maxNodes = options.maxNodes ?? 400;
48
+ const boxes = new Map(snapshot?.nodes.map(node => [node.id, node]) ?? []);
49
+ const lines: string[] = [];
50
+ let omitted = 0;
51
+ const walk = (node: ControlNode, depth: number) => {
52
+ const shot = boxes.get(node.id);
53
+ if (options.visibleOnly && shot && !visible(shot)) return;
54
+ if (lines.length >= maxNodes) { omitted++; return; }
55
+ const parts = [`${node.kind}#${node.id}`];
56
+ const content = shot?.text || node.text;
57
+ if (content) parts.push(quote(content));
58
+ if (node.value !== undefined) parts.push(`value=${quote(String(node.value))}`);
59
+ if (node.placeholder) parts.push(`placeholder=${quote(node.placeholder)}`);
60
+ if (shot?.control?.label && shot.control.label !== content) parts.push(`label=${quote(shot.control.label)}`);
61
+ if (node.disabled) parts.push("disabled");
62
+ if (node.src) parts.push(`src=${quote(node.src, 60)}`);
63
+ if (shot) parts.push(`[${box(shot)}]`);
64
+ if (shot && shot.scrollMax > 0) parts.push(`scroll=${round(shot.scroll)}/${round(shot.scrollMax)}`);
65
+ if (snapshot?.focused === node.id) parts.push("(focused)");
66
+ if (snapshot?.hovered === node.id) parts.push("(hovered)");
67
+ if (options.styles && node.style) parts.push(`style=${JSON.stringify(node.style)}`);
68
+ lines.push(`${" ".repeat(depth)}${parts.join(" ")}`);
69
+ if (depth + 1 > maxDepth) {
70
+ if (node.children.length) lines.push(`${" ".repeat(depth + 1)}… ${node.children.length} children (raise maxDepth)`);
71
+ return;
72
+ }
73
+ for (const child of node.children) walk(child, depth + 1);
74
+ };
75
+ walk(root, 0);
76
+ if (omitted) lines.push(`… ${omitted} more nodes (raise maxNodes or pass root)`);
77
+ return lines.join("\n");
78
+ }
79
+
80
+ function findNode(node: ControlNode, id: string): ControlNode | undefined {
81
+ if (node.id === id) return node;
82
+ for (const child of node.children) {
83
+ const found = findNode(child, id);
84
+ if (found) return found;
85
+ }
86
+ return undefined;
87
+ }
88
+
89
+ const str = (value: unknown): string | undefined => typeof value === "string" && value !== "" ? value : undefined;
90
+ const num = (value: unknown): number | undefined => typeof value === "number" && Number.isFinite(value) ? value : undefined;
91
+ const int = (value: unknown, fallback: number, max: number): number => Math.max(1, Math.min(max, Math.floor(num(value) ?? fallback)));
92
+
93
+ const TARGET = {
94
+ text: { type: "string", description: "Visible text or control label of the node (exact match first, then substring; the smallest node wins)" },
95
+ id: { type: "string", description: "Node id (from inspect_tree or query_nodes)" },
96
+ x: { type: "number", description: "Window x in logical px (with y, instead of text/id)" },
97
+ y: { type: "number", description: "Window y in logical px" },
98
+ } as const;
99
+
100
+ /** The window point a tool acts on: `x,y`, else the centre of the node by `id` or `text`. */
101
+ async function resolvePoint(session: AppSession, args: Record<string, unknown>, prefix = ""): Promise<{ point: Point; node?: NodeSnapshot }> {
102
+ const x = num(args[`${prefix}x`]), y = num(args[`${prefix}y`]);
103
+ if (x !== undefined && y !== undefined) return { point: { x, y } };
104
+ const id = str(args[`${prefix}id`]), text = str(args[`${prefix}text`]);
105
+ if (!id && !text) throw new Error(`Give ${prefix}text, ${prefix}id or ${prefix}x and ${prefix}y`);
106
+ const snapshot = await session.request<Snapshot>("inspect");
107
+ const node = id ? snapshot.nodes.find(candidate => candidate.id === id) : findByText(snapshot, text!);
108
+ if (!node) throw new Error(id ? `No node has id ${JSON.stringify(id)}` : `No visible node shows ${JSON.stringify(text)}`);
109
+ if (!visible(node)) throw new Error(`Node ${node.id} is not laid out (zero size)`);
110
+ return { point: { x: node.x + node.width / 2, y: node.y + node.height / 2 }, node };
111
+ }
112
+
113
+ /** Waits for the frame after an input, then reports where focus and the pointer are. */
114
+ async function settled(session: AppSession, done: Record<string, unknown>): Promise<ToolResult> {
115
+ const snapshot = await session.request<Snapshot>("settle", {}, 10_000);
116
+ return json({ ...done, focused: snapshot.focused, hovered: snapshot.hovered });
117
+ }
118
+
119
+ const input = (session: AppSession, params: Record<string, unknown>) => session.request("input", params);
120
+ const describe = (node: NodeSnapshot | undefined) => node ? { id: node.id, kind: node.kind, text: label(node) } : undefined;
121
+
122
+ export function createTools(session: AppSession): Tool[] {
123
+ let shots = 0;
124
+ const readOnly = { readOnlyHint: true, openWorldHint: false } as const;
125
+ const acts = { readOnlyHint: false, destructiveHint: false, openWorldHint: false } as const;
126
+ return [
127
+ // Reading the app.
128
+ {
129
+ name: "app_status",
130
+ description: "Whether the app is running and connected, its pid and runtime, window size and scale, fps, and the focused and hovered nodes.",
131
+ inputSchema: { type: "object", properties: {}, additionalProperties: false },
132
+ annotations: { title: "App status", ...readOnly },
133
+ async run() {
134
+ const status = session.status();
135
+ if (!status.connected) return json(status);
136
+ const snapshot = await session.request<Snapshot>("inspect");
137
+ return json({ ...status, window: { width: snapshot.width, height: snapshot.height, scale: snapshot.scale }, fps: snapshot.fps, focused: snapshot.focused, hovered: snapshot.hovered, nodes: snapshot.nodes.length });
138
+ },
139
+ },
140
+ {
141
+ name: "inspect_tree",
142
+ description: "The app's node tree as an indented outline: `kind#id \"text\" [x,y wxh]` per node (window coordinates, logical px), with values, labels, scroll, focus and hover. Use the ids with the other tools.",
143
+ inputSchema: {
144
+ type: "object",
145
+ properties: {
146
+ root: { type: "string", description: "Only the subtree of this node id" },
147
+ maxDepth: { type: "number", description: "Default 12" },
148
+ maxNodes: { type: "number", description: "Default 400" },
149
+ styles: { type: "boolean", description: "Include each node's style (verbose)" },
150
+ visibleOnly: { type: "boolean", description: "Skip nodes with no size" },
151
+ },
152
+ additionalProperties: false,
153
+ },
154
+ annotations: { title: "Inspect node tree", ...readOnly },
155
+ async run(args) {
156
+ const styles = args.styles === true;
157
+ const [tree, snapshot] = await Promise.all([session.request<ControlNode | null>("tree", { styles }), session.request<Snapshot>("inspect")]);
158
+ if (!tree) return textResult("The app has not rendered a tree yet.", true);
159
+ const rootId = str(args.root);
160
+ const root = rootId ? findNode(tree, rootId) : tree;
161
+ if (!root) return textResult(`No node has id ${JSON.stringify(rootId)}`, true);
162
+ const header = `window ${snapshot.width}x${snapshot.height} @${snapshot.scale}x, focused=${snapshot.focused ?? "none"}, hovered=${snapshot.hovered ?? "none"}`;
163
+ return textResult(`${header}\n${outline(root, snapshot, { maxDepth: int(args.maxDepth, 12, 200), maxNodes: int(args.maxNodes, 400, 5000), styles, visibleOnly: args.visibleOnly === true })}`);
164
+ },
165
+ },
166
+ {
167
+ name: "query_nodes",
168
+ description: "Finds laid-out nodes by text/label (substring unless exact), id or kind, with their boxes, scroll and control state.",
169
+ inputSchema: {
170
+ type: "object",
171
+ properties: {
172
+ text: { type: "string" },
173
+ exact: { type: "boolean", description: "Text must match the whole label" },
174
+ id: { type: "string" },
175
+ kind: { type: "string", description: "Node kind: view, text, pressable, input, textarea, scroll, image…" },
176
+ includeHidden: { type: "boolean", description: "Also nodes with no size" },
177
+ limit: { type: "number", description: "Default 20" },
178
+ },
179
+ additionalProperties: false,
180
+ },
181
+ annotations: { title: "Query nodes", ...readOnly },
182
+ async run(args) {
183
+ const snapshot = await session.request<Snapshot>("inspect");
184
+ const text = str(args.text), id = str(args.id), kind = str(args.kind);
185
+ const matches = snapshot.nodes.filter(node =>
186
+ (args.includeHidden === true || visible(node))
187
+ && (!id || node.id === id)
188
+ && (!kind || node.kind === kind)
189
+ && (!text || (args.exact === true ? label(node) === text : label(node).includes(text))));
190
+ const limit = int(args.limit, 20, 500);
191
+ return json({ total: matches.length, nodes: matches.slice(0, limit) });
192
+ },
193
+ },
194
+ {
195
+ name: "screenshot",
196
+ description: "A PNG of the app window as it is drawn now.",
197
+ inputSchema: { type: "object", properties: {}, additionalProperties: false },
198
+ annotations: { title: "Screenshot", ...readOnly },
199
+ async run() {
200
+ const path = join(session.directory, `shot-${++shots}.png`);
201
+ await session.request("capture", { path }, 20_000);
202
+ try {
203
+ const data = readFileSync(path).toString("base64");
204
+ const snapshot = await session.request<Snapshot>("inspect");
205
+ return { content: [{ type: "image", data, mimeType: "image/png" }, { type: "text", text: `${snapshot.width}x${snapshot.height} logical px @${snapshot.scale}x` }] };
206
+ } finally {
207
+ rmSync(path, { force: true });
208
+ }
209
+ },
210
+ },
211
+ // Driving it.
212
+ {
213
+ name: "click",
214
+ description: "Moves the pointer to a node (by text or id) or a window point and clicks there, through native hit testing like a user. Waits for the next frame.",
215
+ inputSchema: { type: "object", properties: { ...TARGET, double: { type: "boolean", description: "Double click" } }, additionalProperties: false },
216
+ annotations: { title: "Click", ...acts },
217
+ async run(args) {
218
+ const { point, node } = await resolvePoint(session, args);
219
+ await input(session, { action: "move", ...point });
220
+ for (let count = args.double === true ? 2 : 1; count > 0; count--) {
221
+ await input(session, { action: "down" });
222
+ await input(session, { action: "up" });
223
+ }
224
+ return settled(session, { clicked: describe(node), at: point });
225
+ },
226
+ },
227
+ {
228
+ name: "hover",
229
+ description: "Moves the pointer over a node (by text or id) or to a window point.",
230
+ inputSchema: { type: "object", properties: TARGET, additionalProperties: false },
231
+ annotations: { title: "Hover", ...acts },
232
+ async run(args) {
233
+ const { point, node } = await resolvePoint(session, args);
234
+ await input(session, { action: "move", ...point });
235
+ return settled(session, { hovering: describe(node), at: point });
236
+ },
237
+ },
238
+ {
239
+ name: "type_text",
240
+ description: "Types text into the focused field, or first focuses the node given by id (or clicks the node given by text).",
241
+ inputSchema: {
242
+ type: "object",
243
+ properties: { text: { type: "string", description: "What to type" }, id: TARGET.id, target: { type: "string", description: "Text or label of the field to click first" }, clear: { type: "boolean", description: "Select all and delete first" } },
244
+ required: ["text"],
245
+ additionalProperties: false,
246
+ },
247
+ annotations: { title: "Type text", ...acts },
248
+ async run(args) {
249
+ if (typeof args.text !== "string") throw new Error("text must be a string");
250
+ const id = str(args.id), target = str(args.target);
251
+ if (id) await session.request("focus", { id });
252
+ else if (target) {
253
+ const { point } = await resolvePoint(session, { text: target });
254
+ await input(session, { action: "move", ...point });
255
+ await input(session, { action: "down" });
256
+ await input(session, { action: "up" });
257
+ await session.request("settle");
258
+ }
259
+ if (args.clear === true) {
260
+ await input(session, { action: "key", text: "SelectAll" });
261
+ await input(session, { action: "key", text: "Backspace" });
262
+ }
263
+ if (args.text) await input(session, { action: "text", text: args.text });
264
+ return settled(session, { typed: args.text });
265
+ },
266
+ },
267
+ {
268
+ name: "press_key",
269
+ description: "Presses a key (Enter, Tab, Escape, Space, Backspace, Delete, Home, End, PageUp, PageDown, ArrowUp/Down/Left/Right, SelectAll or a character), optionally focusing a node id first.",
270
+ inputSchema: { type: "object", properties: { key: { type: "string" }, id: TARGET.id, repeat: { type: "number", description: "Times to press it. Default 1" } }, required: ["key"], additionalProperties: false },
271
+ annotations: { title: "Press key", ...acts },
272
+ async run(args) {
273
+ const key = str(args.key);
274
+ if (!key) throw new Error("key must be a non-empty string");
275
+ const id = str(args.id);
276
+ if (id) await session.request("focus", { id });
277
+ const name = keyName(key);
278
+ for (let count = int(args.repeat, 1, 100); count > 0; count--) await input(session, { action: "key", text: name });
279
+ return settled(session, { pressed: name });
280
+ },
281
+ },
282
+ {
283
+ name: "scroll",
284
+ description: "Scrolls with the wheel over a node (by text or id) or a window point; positive deltaY scrolls down. With `to` and an id, jumps a scroll container to start or end instead.",
285
+ inputSchema: {
286
+ type: "object",
287
+ properties: { ...TARGET, deltaY: { type: "number", description: "Pixels, positive is down" }, deltaX: { type: "number", description: "Pixels, positive is right" }, to: { type: "string", enum: ["start", "end"], description: "With id: scroll that container to its start or end" } },
288
+ additionalProperties: false,
289
+ },
290
+ annotations: { title: "Scroll", ...acts },
291
+ async run(args) {
292
+ const id = str(args.id);
293
+ if (args.to === "start" || args.to === "end") {
294
+ if (!id) throw new Error("to needs the id of a scroll container");
295
+ await session.request("scrollTo", { id, y: args.to });
296
+ return settled(session, { scrolled: id, to: args.to });
297
+ }
298
+ const deltaY = num(args.deltaY) ?? 0, deltaX = num(args.deltaX) ?? 0;
299
+ if (!deltaY && !deltaX) throw new Error("Give deltaY or deltaX (or to)");
300
+ const { point, node } = await resolvePoint(session, args);
301
+ await input(session, { action: "move", ...point });
302
+ await input(session, { action: "wheel", ...(deltaY ? { deltaY } : {}), ...(deltaX ? { deltaX } : {}) });
303
+ return settled(session, { scrolled: describe(node), at: point, deltaX, deltaY });
304
+ },
305
+ },
306
+ {
307
+ name: "drag",
308
+ description: "Presses on one node or point, moves to another and releases (sliders, splitters, drag and drop). Targets: fromText/fromId/fromX+fromY and toText/toId/toX+toY.",
309
+ inputSchema: {
310
+ type: "object",
311
+ properties: {
312
+ fromText: { type: "string" }, fromId: { type: "string" }, fromX: { type: "number" }, fromY: { type: "number" },
313
+ toText: { type: "string" }, toId: { type: "string" }, toX: { type: "number" }, toY: { type: "number" },
314
+ steps: { type: "number", description: "Intermediate moves. Default 8" },
315
+ },
316
+ additionalProperties: false,
317
+ },
318
+ annotations: { title: "Drag", ...acts },
319
+ async run(args) {
320
+ const from = (await resolvePoint(session, args, "from")).point;
321
+ const to = (await resolvePoint(session, args, "to")).point;
322
+ const steps = int(args.steps, 8, 100);
323
+ await input(session, { action: "move", ...from });
324
+ await input(session, { action: "down" });
325
+ for (let step = 1; step <= steps; step++) {
326
+ await input(session, { action: "move", x: from.x + (to.x - from.x) * step / steps, y: from.y + (to.y - from.y) * step / steps });
327
+ }
328
+ await input(session, { action: "up" });
329
+ return settled(session, { from, to });
330
+ },
331
+ },
332
+ {
333
+ name: "focus",
334
+ description: "Gives keyboard focus to a node by id.",
335
+ inputSchema: { type: "object", properties: { id: TARGET.id }, required: ["id"], additionalProperties: false },
336
+ annotations: { title: "Focus", ...acts },
337
+ async run(args) {
338
+ const id = str(args.id);
339
+ if (!id) throw new Error("id must be a non-empty string");
340
+ await session.request("focus", { id });
341
+ return settled(session, { focusing: id });
342
+ },
343
+ },
344
+ {
345
+ name: "wait_for",
346
+ description: "Waits until a node showing the text appears (or, with gone, disappears).",
347
+ inputSchema: { type: "object", properties: { text: { type: "string" }, gone: { type: "boolean" }, exact: { type: "boolean" }, timeoutMs: { type: "number", description: "Default 5000, at most 60000" } }, required: ["text"], additionalProperties: false },
348
+ annotations: { title: "Wait for text", ...readOnly },
349
+ async run(args) {
350
+ const text = str(args.text);
351
+ if (!text) throw new Error("text must be a non-empty string");
352
+ const deadline = Date.now() + Math.min(num(args.timeoutMs) ?? 5000, 60_000);
353
+ for (;;) {
354
+ const node = findByText(await session.request<Snapshot>("inspect"), text, args.exact === true);
355
+ if (args.gone === true ? !node : node) return json(args.gone === true ? { gone: text } : { found: describe(node), box: node && box(node) });
356
+ if (Date.now() >= deadline) return textResult(`Timed out: ${JSON.stringify(text)} ${args.gone === true ? "is still shown" : "never appeared"}`, true);
357
+ await new Promise(resolve => setTimeout(resolve, 100));
358
+ }
359
+ },
360
+ },
361
+ // Development loop.
362
+ {
363
+ name: "reload",
364
+ description: "Restarts the app process (a clean start: state is lost). Edits already hot-reload in dev mode; use this after a crash, a closed window or changes hot reload cannot apply.",
365
+ inputSchema: { type: "object", properties: {}, additionalProperties: false },
366
+ annotations: { title: "Reload app", readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
367
+ async run() {
368
+ await session.restart();
369
+ await session.request("settle", {}, 15_000).catch(() => {});
370
+ return json(session.status());
371
+ },
372
+ },
373
+ {
374
+ name: "get_metrics",
375
+ description: "Performance: percentiles (ms) of the JS update phases (render, diff, shadow, send, update) and native frame phases (apply, layout, paint, present, frame, gpu), memory, fps and frame/layout/paint counters.",
376
+ inputSchema: { type: "object", properties: { reset: { type: "boolean", description: "Clear the samples after reading them" } }, additionalProperties: false },
377
+ annotations: { title: "Metrics", ...readOnly },
378
+ async run(args) {
379
+ const [stats, snapshot] = await Promise.all([session.request("stats", { reset: args.reset === true }), session.request<Snapshot>("inspect")]);
380
+ const { nodes: _nodes, ...counters } = snapshot;
381
+ return json({ counters, ...(stats as Record<string, unknown>) });
382
+ },
383
+ },
384
+ {
385
+ name: "get_events",
386
+ description: "Recent native events of the app (clicks, keys, focus, size, window…), oldest first. Pass `since` (the `last` of a previous call) for only new ones.",
387
+ inputSchema: { type: "object", properties: { since: { type: "number" }, limit: { type: "number", description: "Default 50" } }, additionalProperties: false },
388
+ annotations: { title: "Events", ...readOnly },
389
+ async run(args) {
390
+ return json(session.events(num(args.since), int(args.limit, 50, 500)));
391
+ },
392
+ },
393
+ {
394
+ name: "get_logs",
395
+ description: "The app's stdout and stderr (console output, errors, stack traces), oldest first. Pass `since` (the `last` of a previous call) for only new lines.",
396
+ inputSchema: { type: "object", properties: { since: { type: "number" }, limit: { type: "number", description: "Default 100" }, stream: { type: "string", enum: ["stdout", "stderr"] } }, additionalProperties: false },
397
+ annotations: { title: "Logs", ...readOnly },
398
+ async run(args) {
399
+ const { lines, last } = session.logs(num(args.since), int(args.limit, 100, 1000));
400
+ const stream = args.stream === "stdout" || args.stream === "stderr" ? args.stream : undefined;
401
+ const shown = stream ? lines.filter(line => line.stream === stream) : lines;
402
+ return textResult(`${shown.map(line => `${line.seq} ${line.stream === "stderr" ? "!" : " "} ${line.text}`).join("\n") || "(no output)"}\nlast=${last}`);
403
+ },
404
+ },
405
+ ];
406
+ }