@shipvo/mcp 0.0.8 → 0.0.9

package/README.md

@@ -35,6 +35,9 @@ The result gets a line `Waited: matched | timed out after <ms> ms` and `structur
 | `needs_confirm` | An owner command that cannot be undone did nothing and returned a plan. | Show the plan to the owner, then call again with `confirm: true`. |
 | `bad_url` | `open_url` got a URL the app cannot take. | Fix the URL and call again. |
 | `no_url_listener` | The app is not listening for URLs. | Use the app's screens instead. |
+| `phone_locked` | The phone is locked, so tap, type, scroll and back were not sent. | Call `unlock`, then try again. |
+| `already_locked` | `lock` was called on a locked phone. | Call `unlock` if you want to use the app. |
+| `not_locked` | `unlock` was called on a phone that is not locked. | Carry on; nothing to do. |
 | `mock_invalid` | A network mock rule is not valid. | Fix the rule. |
 
 Tools: `list_apps`, `open_app`, `screen`, `tap`, `type`, `scroll`, `back`, `screenshot`, `set_device`, `push_notification`, `notifications`, `open_notification`, `device_log`, `export_test`, `end_session`, `owner_describe`, `owner_command`.
@@ -76,7 +79,7 @@ The HTTP endpoint is stateless. There is no protocol session: each POST is handl
 ### Protocol versions
 
 - **2025-era clients** (`initialize`, then calls, with or without `Mcp-Session-Id`): work. `initialize` is answered, no session id is issued, and any `Mcp-Session-Id` a client sends is ignored.
-- **2026-07-28 clients**: `tools/list` and `tools/call` work with no session and no `initialize`. Not done yet: `server/discover`, the `Mcp-Method`/`Mcp-Name` headers, `ttlMs`/`cacheScope` on list results. `tools/list` order is fixed (registration order).
-- This package uses `@modelcontextprotocol/sdk` 1.x. Stdio is unchanged.
+- **2026-07-28 clients**: `tools/list` and `tools/call` work with no session and no `initialize`. `server/discover` is answered (supported versions, tools capability, server info). A request counts as 2026-era if it calls `server/discover`, sends `Mcp-Method`, or names a 2026 protocol version in `params._meta`; those must carry `Mcp-Method` (and `Mcp-Name` for `tools/call`, `prompts/get`, `resources/read`) matching the body, or get a 400 JSON-RPC error. Requests with no 2026 marker are not checked. Not done yet: `ttlMs`/`cacheScope` on list results. `tools/list` order is fixed (registration order).
+- This package uses `@modelcontextprotocol/sdk` 1.x (the TypeScript SDK v2 is not stable on npm yet; 1.32.2 is `latest`). Tested by `test/http-stateless.test.ts`: discover without `initialize`, header/body mismatch, scope per request, 2025-era `initialize` clients. Stdio is unchanged.
 
  Requests without a valid key are refused. The hosted version at `sim.shipvo.dev` will issue keys per account with scopes (test, owner, read).

package/dist/attach.d.ts

@@ -0,0 +1,30 @@
+export type RunInfo = {
+    port: number;
+    platform: "android" | "ios";
+    app: string;
+    token: string;
+    pid: number;
+};
+export type DriverMessage = {
+    id: number;
+    type: string;
+    [key: string]: unknown;
+};
+export type ScreenMessage = {
+    id?: number;
+    type?: string;
+    ok?: boolean;
+    error?: string;
+    code?: string;
+    screen?: string | null;
+    [key: string]: unknown;
+};
+/** Finds `.shipvo/run.json` in `cwd` or a parent, stopping after the git root. Returns it only if the pid is alive and the app matches. */
+export declare function findLiveRun(app: string, cwd?: string): RunInfo | undefined;
+export type Driver = {
+    request(type: string, args?: Record<string, unknown>, ms?: number): Promise<ScreenMessage>;
+    close(): void;
+    closed: boolean;
+};
+/** Connects as `driver`. Rejects if the socket cannot open within `ms`. */
+export declare function connectDriver(info: RunInfo, ms?: number): Promise<Driver>;

package/dist/attach.js

@@ -0,0 +1,81 @@
+// Attach to a live `shipvo run` phone. `open_app` reads `.shipvo/run.json`, and if the run is alive and is the
+// same app, drives it over the agent channel as the `driver`. The types below mirror
+// packages/cli/src/run-protocol.ts: MCP cannot import from the CLI (rootDir is src, and the CLI is not a dependency).
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+const alive = (pid) => { try {
+    process.kill(pid, 0);
+    return true;
+}
+catch (e) {
+    return e.code === "EPERM";
+} };
+// Safety: run.json may come from a parent directory, but we only ever connect to 127.0.0.1 and send its token there.
+/** Finds `.shipvo/run.json` in `cwd` or a parent, stopping after the git root. Returns it only if the pid is alive and the app matches. */
+export function findLiveRun(app, cwd = process.cwd()) {
+    let dir = resolve(cwd);
+    for (;;) {
+        const file = join(dir, ".shipvo", "run.json");
+        if (existsSync(file)) {
+            try {
+                const i = JSON.parse(readFileSync(file, "utf8"));
+                if (typeof i.port === "number" && typeof i.token === "string" && typeof i.pid === "number" && typeof i.app === "string" && i.app === app && alive(i.pid))
+                    return i;
+            }
+            catch { }
+            return undefined; // the nearest run.json decides
+        }
+        if (existsSync(join(dir, ".git")) || dirname(dir) === dir)
+            return undefined;
+        dir = dirname(dir);
+    }
+}
+/** Connects as `driver`. Rejects if the socket cannot open within `ms`. */
+export function connectDriver(info, ms = 3000) {
+    return new Promise((ok, fail) => {
+        if (typeof WebSocket === "undefined")
+            return fail(new Error("attach needs Node 22+ (no global WebSocket in this Node version)"));
+        const ws = new WebSocket(`ws://127.0.0.1:${info.port}/__shipvo/agent?role=driver&token=${encodeURIComponent(info.token)}`);
+        const pending = new Map();
+        let next = 1, opened = false;
+        const d = {
+            closed: false,
+            close: () => { try {
+                ws.close();
+            }
+            catch { } },
+            request: (type, args = {}, limit = 10000) => new Promise((res) => {
+                if (d.closed)
+                    return res({ ok: false, code: "attach_closed", error: "the shipvo run phone is gone: call open_app again" });
+                const id = next++;
+                const t = setTimeout(() => { pending.delete(id); res({ ok: false, code: "sim_timeout", error: `the live phone did not answer "${type}" within ${limit} ms. The action may still have run: call screen to see where it is.` }); }, limit);
+                pending.set(id, (m) => { clearTimeout(t); res(m); });
+                ws.send(JSON.stringify({ ...args, id, type }));
+            }),
+        };
+        const timer = setTimeout(() => { ws.close(); fail(new Error("timed out connecting to the shipvo run phone")); }, ms);
+        ws.onopen = () => { opened = true; clearTimeout(timer); ok(d); };
+        ws.onmessage = (e) => {
+            try {
+                const m = JSON.parse(String(e.data));
+                if (m.id !== undefined) {
+                    pending.get(m.id)?.(m);
+                    pending.delete(m.id);
+                }
+            }
+            catch { }
+        };
+        ws.onclose = () => {
+            d.closed = true;
+            for (const [id, f] of pending) {
+                f({ ok: false, code: "attach_closed", error: "the shipvo run phone closed the connection: call open_app again" });
+                pending.delete(id);
+            }
+            if (!opened) {
+                clearTimeout(timer);
+                fail(new Error("could not connect to the shipvo run phone"));
+            }
+        };
+        ws.onerror = () => { };
+    });
+}

package/dist/recorder.d.ts

@@ -0,0 +1,52 @@
+export type Format = "9:16" | "16:9" | "1:1";
+export declare const SIZES: Record<Format, {
+    width: number;
+    height: number;
+}>;
+export type Chapter = {
+    t: number;
+    caption: string;
+};
+export type Recording = {
+    file: string;
+    duration_s: number;
+    width: number;
+    height: number;
+    chapters: Chapter[];
+};
+export declare class RecorderError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+export declare class Recorder {
+    private browser?;
+    private page?;
+    private ff?;
+    private loop?;
+    private t0;
+    private running;
+    private starting;
+    private stopping;
+    private ffErr;
+    private done?;
+    private chapters;
+    private file;
+    private size;
+    private fps;
+    get active(): boolean;
+    start(o: {
+        url: string;
+        format?: Format;
+        fps?: 30 | 60;
+        title?: string;
+        dir?: string;
+    }): Promise<{
+        file: string;
+        width: number;
+        height: number;
+    }>;
+    private grab;
+    marker(caption: string): Chapter;
+    stop(): Promise<Recording>;
+    private cleanup;
+}

package/dist/recorder.js

@@ -0,0 +1,143 @@
+// Records the phone frame page to an MP4. Playwright takes screenshots while a session runs; ffmpeg encodes them.
+// Frames carry wall-clock timestamps, so the video lasts as long as the recording even when screenshots are slow.
+// The recording clock (duration_s, chapter times) and the video both start at the first frame.
+import { spawn } from "node:child_process";
+import { mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+export const SIZES = {
+    "9:16": { width: 1080, height: 1920 }, "16:9": { width: 1920, height: 1080 }, "1:1": { width: 1080, height: 1080 },
+};
+export class RecorderError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export class Recorder {
+    browser;
+    page;
+    ff;
+    loop;
+    t0 = 0;
+    running = false;
+    starting = false;
+    stopping = false;
+    ffErr = "";
+    done;
+    chapters = [];
+    file = "";
+    size = SIZES["9:16"];
+    fps = 30;
+    get active() { return this.running || this.starting || this.stopping; }
+    async start(o) {
+        if (this.active)
+            throw new RecorderError("recording_active", "a recording is already running: call record_stop first");
+        this.starting = true;
+        try {
+            this.size = SIZES[o.format ?? "9:16"];
+            this.fps = o.fps ?? 30;
+            this.chapters = [];
+            this.ffErr = "";
+            const dir = resolve(o.dir ?? join(process.cwd(), ".shipvo", "recordings"));
+            mkdirSync(dir, { recursive: true });
+            const slug = (o.title ?? "recording").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "recording";
+            this.file = join(dir, `${slug}-${new Date().toISOString().replace(/[-:T]/g, "").slice(0, 14)}.mp4`);
+            let pw;
+            try {
+                const mod = "playwright";
+                pw = await import(mod);
+            }
+            catch {
+                throw new RecorderError("recorder_unavailable", "recording needs Playwright: run `npm i -D playwright && npx playwright install chromium`");
+            }
+            try {
+                this.browser = await pw.chromium.launch(process.env.SHIPVO_CHROMIUM ? { executablePath: process.env.SHIPVO_CHROMIUM } : {});
+            }
+            catch (e) {
+                throw new RecorderError("recorder_unavailable", `could not launch Chromium: run \`npx playwright install chromium\` (${e.message.split("\n")[0]})`);
+            }
+            this.page = await this.browser.newPage({ viewport: this.size });
+            try {
+                await this.page.goto(o.url, { waitUntil: "load" });
+            }
+            catch (e) {
+                throw new RecorderError("frame_unreachable", `could not open the phone frame page ${o.url}: ${e.message.split("\n")[0]}`);
+            }
+            this.ff = spawn("ffmpeg", ["-y", "-loglevel", "error", "-use_wallclock_as_timestamps", "1", "-f", "image2pipe", "-c:v", "mjpeg", "-i", "-",
+                "-vf", `fps=${this.fps},scale=${this.size.width}:${this.size.height},format=yuv420p`, "-c:v", "libx264", "-preset", "veryfast", "-movflags", "+faststart", this.file], { stdio: ["pipe", "ignore", "pipe"] });
+            this.ff.stderr.on("data", (d) => { this.ffErr += d; });
+            this.ff.stdin.on("error", () => { });
+            this.done = new Promise((r) => { this.ff.on("error", (e) => { this.ffErr += e.message; r(-1); }); this.ff.on("close", r); });
+            await this.grab();
+            // The video timeline starts when ffmpeg gets the first frame, not before the first (slow) screenshot.
+            this.t0 = Date.now();
+            this.running = true;
+            this.starting = false;
+            this.loop = (async () => { while (this.running)
+                await this.grab(); })();
+            return { file: this.file, ...this.size };
+        }
+        catch (e) {
+            await this.cleanup();
+            throw e;
+        }
+    }
+    async grab() {
+        try {
+            const b = await this.page.screenshot({ type: "jpeg", quality: 90 });
+            if (this.ff?.stdin?.writable)
+                this.ff.stdin.write(b);
+        }
+        catch { }
+    }
+    marker(caption) {
+        if (!this.running)
+            throw new RecorderError("no_recording", "no recording is running: call record_start first");
+        const last = this.chapters.at(-1)?.t ?? -0.001;
+        const c = { t: Math.max(Math.round(Date.now() - this.t0) / 1000, Math.round((last + 0.001) * 1000) / 1000), caption };
+        this.chapters.push(c);
+        return c;
+    }
+    async stop() {
+        if (!this.running)
+            throw new RecorderError("no_recording", "no recording is running: call record_start first");
+        this.running = false;
+        this.stopping = true;
+        try {
+            const { file, size, chapters, ff, done, t0 } = this;
+            await this.loop;
+            await this.grab();
+            const duration_s = Math.round((Date.now() - t0)) / 1000;
+            ff.stdin.end();
+            const code = await done;
+            const err = this.ffErr;
+            const out = { file, duration_s, ...size, chapters };
+            await this.cleanup();
+            if (code !== 0)
+                throw new RecorderError("encode_failed", `ffmpeg failed${code === -1 ? " to start (is it installed?)" : ""}: ${err.trim().slice(0, 300)}`);
+            return out;
+        }
+        finally {
+            this.stopping = false;
+        }
+    }
+    async cleanup() {
+        this.running = false;
+        this.starting = false;
+        try {
+            await this.loop;
+        }
+        catch { }
+        try {
+            this.ff?.stdin?.end();
+            this.ff?.kill();
+        }
+        catch { }
+        try {
+            await this.browser?.close();
+        }
+        catch { }
+        this.browser = this.page = this.ff = this.loop = undefined;
+    }
+}

package/dist/server.js

@@ -16,6 +16,8 @@ import { z } from "zod";
 import { classify, compactDiff, fieldValue } from "./change.js";
 import { exportTest } from "./export.js";
 import { findTarget } from "./record.js";
+import { Recorder, RecorderError } from "./recorder.js";
+import { connectDriver, findLiveRun } from "./attach.js";
 import { satisfied, sameTree, wantsMatch } from "./wait.js";
 const SIM = (process.env.PN_SIM ?? "http://localhost:4545").replace(/\/$/, "");
 const CONTROL = (process.env.PN_CONTROL ?? "https://api.shipvo.dev").replace(/\/$/, "");
@@ -59,6 +61,21 @@ async function sim(path, body) {
         return { ok: false, code: "sim_timeout", error: `the simulator did not answer ${what} within ${ms} ms. The action may still have run and the session may still be alive: call screen to see where it is.` };
     }
 }
+const recorder = new Recorder();
+// Sessions attached to a live `shipvo run` phone. Module level: HTTP mode builds a server per request.
+const attached = new Map();
+const ATTACH_TYPES = new Set(["screen", "tap", "type", "scroll", "back"]);
+// One action on a session: through the driver connection when attached, else the simulator.
+async function act(body) {
+    const d = attached.get(String(body.session));
+    if (!d)
+        return sim("/act", body);
+    const { session: _s, action, ...args } = body;
+    if (!ATTACH_TYPES.has(String(action)))
+        return { ok: false, code: "not_supported_attached", error: `"${action}" is not available on the live shipvo run phone yet. Use screen, tap, type, scroll or back, or open a headless session with attach: "never".` };
+    const m = await d.request(String(action), args);
+    return { ok: m.ok !== false && !m.error, screen: m.screen ?? null, error: m.error, code: m.code };
+}
 const sessions = new Map();
 // Last tree per session id. Separate from `sessions` so it works for ids this server never opened.
 const trees = new Map();
@@ -103,8 +120,10 @@ const result = (sid, r) => {
 // Sessions live in the simulator; this map only tracks step counts. A client may reconnect between calls
 // (ChatGPT does), so an unknown id is forwarded and the simulator answers if it knows it.
 const need = (_sid) => { };
+const SERVER_VERSION = "0.0.4";
+const SUPPORTED_VERSIONS = ["2026-07-28", "2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
 function makeServer(ctx = {}) {
-    const server = new McpServer({ name: "shipvo", version: "0.0.4" }, { instructions: `You can use Shipvo apps the way a person uses them on a phone, without a phone.
+    const server = new McpServer({ name: "shipvo", version: SERVER_VERSION }, { instructions: `You can use Shipvo apps the way a person uses them on a phone, without a phone.
 Call open_app to get a session and the first screen. The screen is an accessibility tree: every button, field and text, with a [ref=eN]. Act with tap/type/scroll/back using refs, and read the screen that comes back each time.
 Only what is on screen is listed, like a phone: a horizontal product rail shows a few items, so "scroll right" on the rail (its ref) to see more; "scroll down" the page for the rest.
 System sheets (permission dialogs, the camera, the fingerprint prompt, payment prompts, notification banners, the share sheet) appear in the tree like any other screen: answer them by tapping, as a person would. Use set_device to decide what the phone has (a barcode in front of the camera, a location, whether the fingerprint matches, whether the payment is approved, network off) before the app asks for it.
@@ -136,13 +155,48 @@ Finish a task by checking the final screen says what you expected (for example "
         session: z.string().optional().describe("Session name (default: generated). One session is one phone."),
         seed_cart: z.array(z.object({ product_id: z.string().optional(), id: z.string().optional(), quantity: z.number().int().positive().optional(), qty: z.number().int().positive().optional() }).refine((l) => (l.product_id ?? l.id) && (l.quantity ?? l.qty), "each line needs product_id (or id) and quantity (or qty)")).optional().describe("Start with these items already in the cart (test shortcut). Each line: { product_id, quantity }; { id, qty } also works."),
         dark: z.boolean().optional().describe("Dark mode"),
-    }, WR, async ({ app, session, seed_cart, dark }) => {
+        attach: z.enum(["auto", "never", "always"]).optional().describe("'auto' (default): drive the phone of a live `shipvo run` in this project if there is one, else a headless session. 'never': always headless. 'always': error if there is no live `shipvo run`."),
+    }, WR, async ({ app, session, seed_cart, dark, attach }) => {
         const id = app.split("@")[0];
         if (!(await allowed(id)))
             return result("", { ok: false, code: "unknown_app", error: keyApps ? `this key opens: ${keyApps.join(", ")}` : `unknown app "${id}". Apps: ${Object.keys(await localApps()).join(", ")}` });
         if (ctx.scope === "read")
             throw new Error("this key is read-only: it cannot open sessions");
         const sid = session ?? `${id}-${Date.now().toString(36)}`;
+        const mode = attach ?? "auto";
+        const live = mode === "never" ? undefined : findLiveRun(id);
+        if (mode === "always" && !live)
+            return result("", { ok: false, code: "no_live_run", error: `no live shipvo run for "${id}" found in this directory or its parents (.shipvo/run.json missing, stale, or for another app). Start \`shipvo run android\` or \`shipvo run ios\`, or use attach: "auto".` });
+        let attachNote = "";
+        if (live) {
+            try {
+                const d = await connectDriver(live);
+                attached.get(sid)?.close();
+                attached.set(sid, d);
+                const r = await act({ session: sid, action: "screen" });
+                if (!r.ok) {
+                    attached.delete(sid);
+                    d.close();
+                    if (mode === "always")
+                        return result(sid, r);
+                    attachNote = ` (live run found but attach failed: ${r.error ?? r.code ?? "unknown error"})`;
+                }
+                else {
+                    sessions.set(sid, { app: id, steps: 0, startedAt: Date.now() });
+                    steps.set(sid, [{ action: "open" }]);
+                    if (r.screen != null)
+                        trees.set(sid, r.screen);
+                    else
+                        trees.delete(sid);
+                    return text(`session: ${sid}\napp: ${id} release: local\nmode: attached to the live shipvo run phone\n\n${r.screen ?? ""}`);
+                }
+            }
+            catch (e) {
+                if (mode === "always")
+                    return result("", { ok: false, code: "attach_failed", error: e.message });
+                attachNote = ` (live run found but attach failed: ${e.message})`;
+            }
+        }
         const r = await sim("/session", { session: sid, app, seed_cart: seed_cart?.map((l) => ({ ...l, product_id: l.product_id ?? l.id, quantity: l.quantity ?? l.qty })), dark });
         if (r.code === "sim_timeout")
             return result(sid, r);
@@ -152,7 +206,7 @@ Finish a task by checking the final screen says what you expected (for example "
             trees.set(sid, r.screen);
         else
             trees.delete(sid);
-        return text(`session: ${sid}\napp: ${id} release: ${r.release ?? "local"}\n\n${r.screen ?? ""}`);
+        return text(`session: ${sid}\napp: ${id} release: ${r.release ?? "local"}\nmode: headless session${attachNote}\n\n${r.screen ?? ""}`);
     });
     server.tool("list_sessions", "Open simulator sessions (phones) on this server: id, app, release and when each started. Use to resume after a reconnect.", {}, RO, async () => {
         const r = await sim("/sessions", {});
@@ -164,11 +218,12 @@ Finish a task by checking the final screen says what you expected (for example "
     const sid = z.string().describe("Session from open_app");
     const compact = z.boolean().optional().describe("When the change is 'content changed', return only the added/removed lines, not the whole screen");
     const CH = " The result starts with 'Change: none | content changed | new screen | scrolled'.";
+    const ASYNC = " Work that starts on a tap (paying, saving, loading) can finish after this returns, so the screen may show 'Paying...' or a spinner. Do not report that as the result: pass wait_for with the text you expect (and gone: true for the spinner), or settle: true, before you read the outcome or do anything else.";
     const waitFor = z.object({ ref: z.string().regex(/^e\d+$/).optional(), text: z.string().optional(), role: z.string().optional(), name: z.string().optional(), gone: z.boolean().optional() })
         .refine((w) => wantsMatch(w), "give ref, text, or role and name").optional()
-        .describe("After the action, wait until this appears (a ref, a text, or role+name), or disappears with gone: true. The result says Waited: matched or timed out.");
+        .describe("Use after any action that starts work. Wait until this appears (a ref, a text, or role+name), or disappears with gone: true. The result says Waited: matched or timed out.");
     const timeoutMs = z.number().int().min(0).max(30000).optional().describe("How long wait_for and settle may take, in ms (default 2000)");
-    const settle = z.boolean().optional().describe("Wait until the screen stops changing (two equal reads 100 ms apart), up to timeout_ms");
+    const settle = z.boolean().optional().describe("Wait until the screen stops changing (two equal reads 100 ms apart), up to timeout_ms. Use after any action that starts work. A slow result can still follow a pause, so prefer wait_for when you know the expected text.");
     const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
     // Poll the screen after an action. Returns the latest result and what happened. On timeout the action result is kept as is.
     async function waiting(session, r, w) {
@@ -176,7 +231,7 @@ Finish a task by checking the final screen says what you expected (for example "
             return { r };
         const t0 = Date.now(), limit = w.timeout_ms ?? 2000, left = () => limit - (Date.now() - t0);
         let cur = r, matched = true;
-        const read = async () => { const n = await sim("/act", { session, action: "screen" }); if (n.ok && n.screen != null)
+        const read = async () => { const n = await act({ session, action: "screen" }); if (n.ok && n.screen != null)
             cur = { ...cur, screen: n.screen }; return n.ok && n.screen != null; };
         if (w.wait_for) {
             matched = satisfied(cur.screen, w.wait_for);
@@ -200,15 +255,15 @@ Finish a task by checking the final screen says what you expected (for example "
         return { r: cur, waited: { matched, ms: Date.now() - t0 } };
     }
     const ref = z.string().regex(/^e\d+$/).describe("Element ref from the screen, e.g. e42");
-    server.tool("screen", "The current screen as an accessibility tree with refs.", { session: sid }, RO, async ({ session }) => { need(session); const r = await sim("/act", { session, action: "screen" }); if (r.ok && r.screen != null)
+    server.tool("screen", "The current screen as an accessibility tree with refs.", { session: sid }, RO, async ({ session }) => { need(session); const r = await act({ session, action: "screen" }); if (r.ok && r.screen != null)
         trees.set(session, r.screen); return result(session, r); });
-    server.tool("tap", "Tap a button, link or choice by ref. Returns the new screen." + CH, { session: sid, ref, compact, wait_for: waitFor, timeout_ms: timeoutMs, settle }, WR, async ({ session, ref, compact, wait_for, timeout_ms, settle }) => { need(session); const w = await waiting(session, await sim("/act", { session, action: "tap", ref }), { wait_for, timeout_ms, settle }); return acted(session, "tap", w.r, { waited: w.waited, compact, step: { action: "tap", target: findTarget(trees.get(session), ref) } }); });
-    server.tool("type", "Type into a text field by ref (replaces its content). Returns the new screen." + CH + " Also gives the field's value after typing.", { session: sid, ref, text: z.string(), enter: z.boolean().optional().describe("Press Enter afterwards"), compact, wait_for: waitFor, timeout_ms: timeoutMs, settle }, WR, async ({ session, ref, text: t, enter, compact, wait_for, timeout_ms, settle }) => { need(session); const tgt = findTarget(trees.get(session), ref); const w = await waiting(session, await sim("/act", { session, action: "type", ref, text: t, enter }), { wait_for, timeout_ms, settle }); return acted(session, "type", w.r, { waited: w.waited, compact, ref, step: { action: "type", target: tgt, fieldLabel: tgt?.text, passwordLike: tgt?.passwordLike, text: t } }); });
-    server.tool("scroll", "Scroll the page (down/up) or a horizontal rail (right/left, give the rail's ref). Returns the new screen." + CH, { session: sid, direction: z.enum(["down", "up", "left", "right"]), ref: ref.optional().describe("Scroll inside this element (a rail or list); omit for the page"), compact, wait_for: waitFor, timeout_ms: timeoutMs, settle }, WR, async ({ session, direction, ref, compact, wait_for, timeout_ms, settle }) => { need(session); const w = await waiting(session, await sim("/act", { session, action: "scroll", direction, ref }), { wait_for, timeout_ms, settle }); return acted(session, "scroll", w.r, { waited: w.waited, compact, step: { action: "scroll", direction } }); });
-    server.tool("back", "Go back one screen." + CH, { session: sid, compact, wait_for: waitFor, timeout_ms: timeoutMs, settle }, WR, async ({ session, compact, wait_for, timeout_ms, settle }) => { need(session); const w = await waiting(session, await sim("/act", { session, action: "back" }), { wait_for, timeout_ms, settle }); return acted(session, "back", w.r, { waited: w.waited, compact, step: { action: "back" } }); });
+    server.tool("tap", "Tap a button, link or choice by ref. Returns the new screen." + CH + ASYNC, { session: sid, ref, compact, wait_for: waitFor, timeout_ms: timeoutMs, settle }, WR, async ({ session, ref, compact, wait_for, timeout_ms, settle }) => { need(session); const w = await waiting(session, await act({ session, action: "tap", ref }), { wait_for, timeout_ms, settle }); return acted(session, "tap", w.r, { waited: w.waited, compact, step: { action: "tap", target: findTarget(trees.get(session), ref) } }); });
+    server.tool("type", "Type into a text field by ref (replaces its content). Returns the new screen." + CH + " Also gives the field's value after typing.", { session: sid, ref, text: z.string(), enter: z.boolean().optional().describe("Press Enter afterwards"), compact, wait_for: waitFor, timeout_ms: timeoutMs, settle }, WR, async ({ session, ref, text: t, enter, compact, wait_for, timeout_ms, settle }) => { need(session); const tgt = findTarget(trees.get(session), ref); const w = await waiting(session, await act({ session, action: "type", ref, text: t, enter }), { wait_for, timeout_ms, settle }); return acted(session, "type", w.r, { waited: w.waited, compact, ref, step: { action: "type", target: tgt, fieldLabel: tgt?.text, passwordLike: tgt?.passwordLike, text: t } }); });
+    server.tool("scroll", "Scroll the page (down/up) or a horizontal rail (right/left, give the rail's ref). Returns the new screen." + CH, { session: sid, direction: z.enum(["down", "up", "left", "right"]), ref: ref.optional().describe("Scroll inside this element (a rail or list); omit for the page"), compact, wait_for: waitFor, timeout_ms: timeoutMs, settle }, WR, async ({ session, direction, ref, compact, wait_for, timeout_ms, settle }) => { need(session); const w = await waiting(session, await act({ session, action: "scroll", direction, ref }), { wait_for, timeout_ms, settle }); return acted(session, "scroll", w.r, { waited: w.waited, compact, step: { action: "scroll", direction } }); });
+    server.tool("back", "Go back one screen." + CH, { session: sid, compact, wait_for: waitFor, timeout_ms: timeoutMs, settle }, WR, async ({ session, compact, wait_for, timeout_ms, settle }) => { need(session); const w = await waiting(session, await act({ session, action: "back" }), { wait_for, timeout_ms, settle }); return acted(session, "back", w.r, { waited: w.waited, compact, step: { action: "back" } }); });
     server.tool("screenshot", "A PNG of the phone screen (for checking layout, colours, images). The tree from `screen` is usually enough to act.", { session: sid }, RO, async ({ session }) => {
         need(session);
-        const r = await sim("/act", { session, action: "screenshot" });
+        const r = await act({ session, action: "screenshot" });
         if (!r.ok)
             return result(session, r);
         if (!r.path)
@@ -227,23 +282,28 @@ Finish a task by checking the final screen says what you expected (for example "
         biometrics: z.object({ enrolled: z.boolean().optional(), nextResult: z.enum(["success", "fail", "cancel"]).optional() }).optional(),
         payment: z.object({ nextResult: z.enum(["approve", "decline", "timeout", "insufficient_funds"]).optional(), pin: z.string().optional() }).optional(),
         online: z.boolean().optional(),
-    }, WR, async ({ session, ...device }) => { need(session); const r = await sim("/act", { session, action: "set_device", device }); if (r.ok)
+        source: z.enum(["auto", "simulated"]).optional().describe("\"simulated\" forces the simulated camera, microphone and location even when a person could grant the real ones, for reproducible runs"),
+        microphone: z.object({ level: z.number().min(0).max(1).optional() }).optional(),
+    }, WR, async ({ session, ...device }) => { need(session); const r = await act({ session, action: "set_device", device }); if (r.ok)
         steps.get(session)?.push({ action: "set_device", device: device.payment?.pin === undefined ? device : { ...device, payment: { ...device.payment, pin: undefined } } }); return result(session, r); });
     server.tool("push_notification", "Deliver a push notification to the simulated phone; it appears as a banner the agent can tap. The app receives it only if notification permission is granted; otherwise nothing is delivered.", { session: sid, title: z.string(), body: z.string(), data: z.record(z.unknown()).optional() }, WR, async ({ session, title, body, data }) => {
         need(session);
-        const r = await sim("/act", { session, action: "push_notification", title, body, data });
+        const r = await act({ session, action: "push_notification", title, body, data });
         // The simulator answers ok when permission blocks the push, so say so: otherwise it looks like a delivery.
         if (r.ok && r.delivered === false)
             return result(session, { ...r, screen: `Not delivered: notification permission is not granted (use set_device permissions.notifications).\n\n${r.screen ?? ""}` });
         return result(session, r);
     });
-    server.tool("notifications", "The notification shade: notifications delivered to the simulated phone in this session (their banners vanish after 5 s, like a heads-up on a real phone).", { session: sid }, RO, async ({ session }) => { need(session); const r = await sim("/act", { session, action: "notifications" }); if (!r.ok)
+    server.tool("notifications", "The notification shade: notifications delivered to the simulated phone in this session (their banners vanish after 5 s, like a heads-up on a real phone).", { session: sid }, RO, async ({ session }) => { need(session); const r = await act({ session, action: "notifications" }); if (!r.ok)
         return result(session, r); return text(JSON.stringify(r.notifications ?? [], null, 2)); });
-    server.tool("open_notification", "Tap a notification from the shade (newest if no id is given): the app handles it exactly as if its banner was tapped.", { session: sid, id: z.string().optional() }, WR, async ({ session, id }) => { need(session); return result(session, await sim("/act", { session, action: "open_notification", id })); });
-    server.tool("open_url", "Open a deep link (such as myapp://item/3) in the running app, as a push tap, auth callback or share link would. Fails with no_url_listener if the app does not listen for URLs.", { session: sid, url: z.string().describe("The URL to deliver, e.g. myapp://item/3") }, { title: "Open a deep link", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }, async ({ session, url }) => { need(session); return result(session, await sim("/act", { session, action: "open_url", url })); });
-    server.tool("device_log", "What the app did with the device in this session: permission prompts and answers, location reads, scans, fingerprint checks, payments, notifications, shares.", { session: sid }, RO, async ({ session }) => { need(session); const r = await sim("/act", { session, action: "device_log" }); if (!r.ok)
-        return result(session, r); return text(JSON.stringify({ note: "Everything here is simulated: no real biometric check or money movement took place.", capabilities: r.capabilities, log: r.log ?? [] }, null, 2)); });
-    server.tool("device_reset", "Put the simulated phone back to a known state (permissions undetermined, default location, nothing in front of the camera, log cleared), optionally with a new profile.", { session: sid, platform: z.enum(["android", "ios"]).optional(), api: z.number().optional() }, WR, async ({ session, ...device }) => { need(session); return result(session, await sim("/act", { session, action: "device_reset", device })); });
+    server.tool("open_notification", "Tap a notification from the shade (newest if no id is given): the app handles it exactly as if its banner was tapped.", { session: sid, id: z.string().optional() }, WR, async ({ session, id }) => { need(session); return result(session, await act({ session, action: "open_notification", id })); });
+    server.tool("open_url", "Open a deep link (such as myapp://item/3) in the running app, as a push tap, auth callback or share link would. Fails with no_url_listener if the app does not listen for URLs.", { session: sid, url: z.string().describe("The URL to deliver, e.g. myapp://item/3") }, { title: "Open a deep link", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }, async ({ session, url }) => { need(session); return result(session, await act({ session, action: "open_url", url })); });
+    server.tool("lock", "Press the power button: the simulated phone locks and shows the lock screen. The app and its screen are kept. While locked, tap, type, scroll and back fail with phone_locked. Logged in device_log as simulated.", { session: sid }, WR, async ({ session }) => { need(session); return result(session, await act({ session, action: "lock" })); });
+    server.tool("unlock", "Swipe up on the lock screen. Returns to the same screen as before the lock. Fails with not_locked if the phone is not locked. Logged in device_log as simulated.", { session: sid }, WR, async ({ session }) => { need(session); return result(session, await act({ session, action: "unlock" })); });
+    server.tool("restart", "Restart the simulated phone from the power menu: a boot screen, then the app starts fresh (cold start). Storage is kept. Returns the first screen. Logged in device_log as simulated.", { session: sid }, WR, async ({ session }) => { need(session); return result(session, await act({ session, action: "restart" })); });
+    server.tool("device_log", "What the app did with the device in this session: permission prompts and answers, location reads, scans, fingerprint checks, payments, notifications, shares.", { session: sid }, RO, async ({ session }) => { need(session); const r = await act({ session, action: "device_log" }); if (!r.ok)
+        return result(session, r); return text(JSON.stringify({ note: "Entries marked source \"simulated\" are simulated: no real biometric check or money movement took place. Camera, microphone and location readings marked source \"real\" came from the browser's hardware.", capabilities: r.capabilities, log: r.log ?? [] }, null, 2)); });
+    server.tool("device_reset", "Put the simulated phone back to a known state (permissions undetermined, default location, nothing in front of the camera, log cleared), optionally with a new profile.", { session: sid, platform: z.enum(["android", "ios"]).optional(), api: z.number().optional() }, WR, async ({ session, ...device }) => { need(session); return result(session, await act({ session, action: "device_reset", device })); });
     server.tool("export_test", "Turn the steps taken in this session (tap, type, scroll, back, set_device) into a @shipvo/test script and return its source. Read-only. Targets are named by their visible text; ambiguous ones become TODO comments and password fields use an environment variable instead of the typed value.", { session: sid }, RO, async ({ session }) => {
         const rec = steps.get(session), s = sessions.get(session);
         if (!rec || !s)
@@ -252,6 +312,16 @@ Finish a task by checking the final screen says what you expected (for example "
     });
     server.tool("end_session", "Close the session and get a report: steps taken, and the orders the app sent to its backend during the session.", { session: sid }, DEST, async ({ session }) => {
         need(session);
+        const live = attached.get(session);
+        if (live) {
+            const s = sessions.get(session);
+            live.close();
+            attached.delete(session);
+            sessions.delete(session);
+            trees.delete(session);
+            steps.delete(session);
+            return text(JSON.stringify({ session, app: s?.app, mode: "attached", steps: s?.steps ?? 0, seconds: Math.round((Date.now() - (s?.startedAt ?? Date.now())) / 1000) }, null, 2));
+        }
         // The simulator is the source of truth: end a session it lists even if this server did not open it; otherwise no_session.
         const listed = await sim("/sessions", {});
         if (!listed.ok)
@@ -269,6 +339,40 @@ Finish a task by checking the final screen says what you expected (for example "
         catch { }
         return text(JSON.stringify({ session, app: s.app, steps: s.steps, seconds: Math.round((Date.now() - s.startedAt) / 1000), orders }, null, 2));
     });
+    // Record the phone frame page to an MP4 (one recording per server). Page: SHIPVO_FRAME_URL, default the simulator's root.
+    const recFail = (e) => { if (e instanceof RecorderError)
+        return result("", { ok: false, code: e.code, error: e.message }); throw e; };
+    server.tool("record_start", "Start recording the phone frame to an MP4 under .shipvo/recordings/. Use record_marker for chapters and record_stop to finish.", {
+        format: z.enum(["9:16", "16:9", "1:1"]).optional().describe("Video shape (default 9:16: 1080x1920; 16:9 is 1920x1080; 1:1 is 1080x1080)"),
+        fps: z.union([z.literal(30), z.literal(60)]).optional().describe("Frames per second (default 30)"),
+        title: z.string().optional().describe("Used in the file name"),
+    }, WR, async ({ format, fps, title }) => {
+        try {
+            const r = await recorder.start({ url: process.env.SHIPVO_FRAME_URL ?? SIM + "/", format, fps, title });
+            return { ...text(`recording to ${r.file} (${r.width}x${r.height})`), structuredContent: r };
+        }
+        catch (e) {
+            return recFail(e);
+        }
+    });
+    server.tool("record_marker", "Add a chapter at the current time of the running recording.", { caption: z.string().min(1) }, WR, async ({ caption }) => {
+        try {
+            const c = recorder.marker(caption);
+            return { ...text(`marker at ${c.t}s: ${c.caption}`), structuredContent: c };
+        }
+        catch (e) {
+            return recFail(e);
+        }
+    });
+    server.tool("record_stop", "Stop the recording and write the MP4. Returns the file, duration in seconds, size and chapters.", {}, WR, async () => {
+        try {
+            const r = await recorder.stop();
+            return { ...text(JSON.stringify(r, null, 2)), structuredContent: r };
+        }
+        catch (e) {
+            return recFail(e);
+        }
+    });
     // Publish the app's web build to here.now (no account) through the CLI, which builds, wraps and checks for secrets.
     server.tool("publish_preview", "Build the app in PN_APP_DIR (or the current folder) with the simulated device and publish a shareable web preview to here.now, no account. The link is PUBLIC and expires in 24 hours; claimUrl keeps it. Returns { url, claimUrl, expiresAt }. Needs @shipvo/cli (npx).", {}, { title: "Publish a public preview", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }, async () => {
         if (ctx.scope && ctx.scope !== "owner" && ctx.scope !== "test")
@@ -357,6 +461,31 @@ else {
             res.writeHead(400, { "content-type": "application/json" });
             return res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32700, message: "Parse error" }, id: null }));
         }
+        // MCP 2026-07-28: answer server/discover, and refuse requests whose Mcp-Method/Mcp-Name headers disagree with the body.
+        const bad = (code, message, id = null) => { res.writeHead(400, { "content-type": "application/json" }); return res.end(JSON.stringify({ jsonrpc: "2.0", error: { code, message }, id })); };
+        const msg = body && typeof body === "object" && !Array.isArray(body) ? body : undefined;
+        if (msg && typeof msg.method === "string") {
+            const hm = req.headers["mcp-method"], hn = req.headers["mcp-name"];
+            const meta = (msg.params?._meta ?? {});
+            const pv = Object.entries(meta).find(([k]) => /protocolversion$/i.test(k))?.[1];
+            const era2026 = msg.method === "server/discover" || hm !== undefined || (typeof pv === "string" && pv >= "2026-07-28");
+            if (era2026) {
+                if (hm === undefined)
+                    return bad(-32001, "Missing Mcp-Method header", msg.id ?? null);
+                if (hm !== msg.method)
+                    return bad(-32001, `Header mismatch: Mcp-Method is '${hm}' but the body method is '${msg.method}'`, msg.id ?? null);
+                const nameKey = msg.method === "tools/call" || msg.method === "prompts/get" ? "name" : msg.method === "resources/read" ? "uri" : undefined;
+                const want = nameKey ? msg.params?.[nameKey] : undefined;
+                if (nameKey && hn === undefined)
+                    return bad(-32001, "Missing Mcp-Name header", msg.id ?? null);
+                if (hn !== undefined && hn !== want)
+                    return bad(-32001, `Header mismatch: Mcp-Name is '${hn}' but the body says '${String(want)}'`, msg.id ?? null);
+            }
+            if (msg.method === "server/discover") {
+                res.writeHead(200, { "content-type": "application/json" });
+                return res.end(JSON.stringify({ jsonrpc: "2.0", id: msg.id ?? null, result: { supportedVersions: SUPPORTED_VERSIONS, capabilities: { tools: { listChanged: false } }, serverInfo: { name: "shipvo", version: SERVER_VERSION } } }));
+            }
+        }
         // Behind sim.shipvo.dev the Worker has checked the key and says which app and scope it grants; locally
         // there are no such headers and every app is allowed. A client's mcp-session-id header is ignored.
         const h = (n) => req.headers[n] || undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipvo/mcp",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "type": "module",
   "license": "Apache-2.0",
   "description": "MCP server that lets AI agents open, see and operate Shipvo apps without a phone: a phone-sized simulator of the real app, plus the app's typed commands and owner API.",
@@ -15,7 +15,8 @@
   "devDependencies": {
     "typescript": "^5.6.3",
     "@types/node": "^22.8.0",
-    "vitest": "^2.1.4"
+    "vitest": "^2.1.4",
+    "playwright": "1.63.0"
   },
   "keywords": [
     "mcp",
@@ -45,6 +46,14 @@
     "node": ">=20"
   },
   "mcpName": "io.github.shipvo/shipvo",
+  "peerDependencies": {
+    "playwright": ">=1.50"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    }
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "test": "vitest run"