@shipvo/mcp 0.0.2 → 0.0.4

package/README.md

@@ -8,9 +8,9 @@ Lets AI agents (Claude, Cursor, Claude Code, PiPilot…) **use a Shipvo app with
   "env": { "PN_SIM": "http://localhost:4545", "PN_OWNER_TOKEN": "…optional…" } } } }
 ```
 
-Start the simulator first (`node sim/server.mjs` in the app, or `shipvo sim` soon). The hosted version at `sim.shipvo.dev` needs no local setup.
+Start the simulator first (`shipvo sim` in the app). The hosted version needs no local setup: `{ "url": "https://<host>/mcp/<key>" }`.
 
-Tools: `list_apps`, `open_app`, `screen`, `tap`, `type`, `scroll`, `back`, `screenshot`, `set_device`, `push_notification`, `device_log`, `end_session`, `owner_describe`, `owner_command`.
+Tools: `list_apps`, `open_app`, `screen`, `tap`, `type`, `scroll`, `back`, `screenshot`, `set_device`, `push_notification`, `notifications`, `open_notification`, `device_log`, `end_session`, `owner_describe`, `owner_command`.
 
 Native features work with no phone: the simulated device (see `@shipvo/device`) shows permission dialogs, the camera, the fingerprint prompt, payment prompts, notification banners and the share sheet as real dialogs in the tree; `set_device` decides what the phone has (location, a barcode in view, whether the fingerprint matches, whether a payment is approved, network off).
 

package/dist/server.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Shipvo MCP: agents use Shipvo apps with no phone.
-//   PN_SIM=http://localhost:4545  PN_CONTROL=https://purenative-control.purenative.workers.dev  PN_OWNER_TOKEN=...  shipvo-mcp
+//   PN_SIM=http://localhost:4545  PN_CONTROL=https://api.shipvo.dev  PN_OWNER_TOKEN=...  shipvo-mcp
 // Remote (Streamable HTTP, what Claude, ChatGPT, Cursor connect to over the network):
 //   shipvo-mcp --http 8787  with PN_API_KEYS="key1,key2" (Authorization: Bearer <key>) → POST/GET/DELETE /mcp
 // Tools: list_apps, open_app, screen, tap, type, scroll, back, screenshot, end_session (UI simulator);
@@ -13,7 +13,7 @@ import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { z } from "zod";
 const SIM = (process.env.PN_SIM ?? "http://localhost:4545").replace(/\/$/, "");
-const CONTROL = (process.env.PN_CONTROL ?? "https://purenative-control.purenative.workers.dev").replace(/\/$/, "");
+const CONTROL = (process.env.PN_CONTROL ?? "https://api.shipvo.dev").replace(/\/$/, "");
 const OWNER_TOKEN = process.env.PN_OWNER_TOKEN ?? "";
 // Apps this server can open. Hosted: the account's apps. Local: one app served by the simulator.
 const APPS = process.env.PN_APPS ? JSON.parse(process.env.PN_APPS)
@@ -27,16 +27,37 @@ async function sim(path, body) {
 const sessions = new Map();
 const text = (t) => ({ content: [{ type: "text", text: t }] });
 const result = (sid, r) => { const s = sessions.get(sid); if (s)
-    s.steps++; return text(r.ok ? (r.screen ?? "") : `Error: ${r.error}\n\nScreen now:\n${r.screen ?? ""}`); };
-const need = (sid) => { if (!sessions.has(sid))
-    throw new Error(`no session "${sid}". Call open_app first.`); };
-function makeServer() {
-    const server = new McpServer({ name: "shipvo", version: "0.0.1" }, { instructions: `You can use Shipvo apps the way a person uses them on a phone, without a phone.
+    s.steps++; return text(r.ok ? (r.screen ?? "") : `Error: ${r.error}${/no session/.test(String(r.error)) ? " (sessions expire with the phone; call open_app again)" : ""}\n\nScreen now:\n${r.screen ?? ""}`); };
+// 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) => { };
+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.
 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.
 Finish a task by checking the final screen says what you expected (for example "Order placed"). Call end_session when done to get a report.` });
-    server.tool("list_apps", "Apps this server can open, with what each one does.", {}, async () => text(Object.entries(APPS).map(([id, a]) => `${id}: ${a.name}. ${a.description}`).join("\n")));
+    // ctx.app: the app(s) this key opens, comma-separated (the beta app plus any the key owner has registered).
+    const keyApps = ctx.app ? ctx.app.split(",").map((s) => s.trim()).filter(Boolean) : null;
+    const allowed = (id) => (keyApps ? keyApps.includes(id) : !!APPS[id]);
+    server.tool("list_apps", "Apps this server can open, with what each one does. Optional query filters by name, description or category (e.g. 'shop', 'douala').", { query: z.string().optional() }, async ({ query }) => {
+        const ids = keyApps ?? Object.keys(APPS);
+        const q = (query ?? "").toLowerCase();
+        let dir = {};
+        try {
+            const r = await fetch(`${CONTROL}/apps/public${q ? `?q=${encodeURIComponent(q)}` : ""}`);
+            if (r.ok)
+                for (const a of (await r.json()).apps)
+                    dir[a.app_id] = a;
+        }
+        catch { }
+        const lines = ids.map((id) => {
+            const d = dir[id] ?? APPS[id];
+            const desc = d ? `${d.name}. ${d.description}${"category" in d ? ` [${d.category}]` : ""}` : `published with shipvo`;
+            return q && !`${id} ${desc}`.toLowerCase().includes(q) ? null : `${id}: ${desc} (open_app("${id}@latest"))`;
+        }).filter(Boolean);
+        return text(lines.join("\n") || `no apps match "${query}"`);
+    });
     server.tool("open_app", "Open an app in a fresh phone-sized session and return its first screen.", {
         app: z.string().describe("App id from list_apps, optionally with a release: 'tide' (local build), 'tide@latest' or 'tide@r13' (the published release phones run)"),
         session: z.string().optional().describe("Session name (default: generated). One session is one phone."),
@@ -44,13 +65,20 @@ Finish a task by checking the final screen says what you expected (for example "
         dark: z.boolean().optional().describe("Dark mode"),
     }, async ({ app, session, seed_cart, dark }) => {
         const id = app.split("@")[0];
-        if (!APPS[id])
-            throw new Error(`unknown app "${id}". Apps: ${Object.keys(APPS).join(", ")}`);
+        if (!allowed(id))
+            throw new Error(keyApps ? `this key opens: ${keyApps.join(", ")}` : `unknown app "${id}". Apps: ${Object.keys(APPS).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 r = await sim("/session", { session: sid, app, seed_cart, dark });
         sessions.set(sid, { app: id, steps: 0, startedAt: Date.now() });
         return text(`session: ${sid}\napp: ${id} release: ${r.release ?? "local"}\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.", {}, async () => {
+        const r = await sim("/sessions", {});
+        const rows = (r.sessions ?? []).filter((s) => !keyApps || keyApps.includes(s.app));
+        return text(rows.length ? rows.map((s) => `${s.session}: ${s.app} release ${s.release}${s.started_at ? ` since ${s.started_at}` : ""}`).join("\n") : "no open sessions");
+    });
     const sid = z.string().describe("Session from open_app");
     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 }, async ({ session }) => { need(session); return result(session, await sim("/act", { session, action: "screen" })); });
@@ -76,11 +104,13 @@ Finish a task by checking the final screen says what you expected (for example "
         online: z.boolean().optional(),
     }, async ({ session, ...device }) => { need(session); return result(session, await sim("/act", { session, action: "set_device", device })); });
     server.tool("push_notification", "Deliver a push notification to the simulated phone; it appears as a banner the agent can tap.", { session: sid, title: z.string(), body: z.string(), data: z.record(z.unknown()).optional() }, async ({ session, title, body, data }) => { need(session); return result(session, await sim("/act", { session, action: "push_notification", title, body, data })); });
+    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 }, async ({ session }) => { need(session); return text(JSON.stringify((await sim("/act", { session, action: "notifications" })).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() }, async ({ session, id }) => { need(session); return result(session, await sim("/act", { session, action: "open_notification", id })); });
     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 }, async ({ session }) => { need(session); const r = await sim("/act", { session, action: "device_log" }); 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() }, async ({ session, ...device }) => { need(session); return result(session, await sim("/act", { session, action: "device_reset", device })); });
     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 }, async ({ session }) => {
         need(session);
-        const s = sessions.get(session);
+        const s = sessions.get(session) ?? { app: session.split("-")[0], steps: 0, startedAt: Date.now() };
         sessions.delete(session);
         let orders = [];
         try {
@@ -95,9 +125,14 @@ Finish a task by checking the final screen says what you expected (for example "
         return text(await r.text());
     });
     server.tool("owner_command", "Run an owner command against the live app (changes are audited; `publish` makes them live on every phone within seconds).", { app: z.string(), command: z.string(), args: z.record(z.unknown()).optional() }, async ({ app, command, args }) => {
-        if (!OWNER_TOKEN)
-            throw new Error("PN_OWNER_TOKEN is not set: owner commands are disabled.");
-        const r = await fetch(`${CONTROL}/app/${app}/api/command`, { method: "POST", headers: { "content-type": "application/json", authorization: `Bearer ${OWNER_TOKEN}` }, body: JSON.stringify({ command, args: args ?? {} }) });
+        if (ctx.scope && ctx.scope !== "owner")
+            throw new Error(`this key has scope "${ctx.scope}": owner commands need an owner key`);
+        if (keyApps && !keyApps.includes(app))
+            throw new Error(`this key is for: ${keyApps.join(", ")}`);
+        const token = ctx.ownerToken || OWNER_TOKEN;
+        if (!token)
+            throw new Error("owner commands are not enabled on this server.");
+        const r = await fetch(`${CONTROL}/app/${app}/api/command`, { method: "POST", headers: { "content-type": "application/json", authorization: `Bearer ${token}` }, body: JSON.stringify({ name: command, args: args ?? {} }) });
         return text(await r.text());
     });
     return server;
@@ -140,8 +175,10 @@ else {
             transport.onclose = () => { for (const [id, t] of transports)
                 if (t === transport)
                     transports.delete(id); };
-            // One McpServer per client connection, same tools.
-            await makeServer().connect(transport);
+            // One McpServer per client connection. 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.
+            const scope = req.headers["x-shipvo-scope"];
+            await makeServer({ app: req.headers["x-shipvo-app"] || undefined, publicApps: req.headers["x-shipvo-public"] || undefined, scope, ownerToken: req.headers["x-shipvo-owner-token"] || undefined }).connect(transport);
         }
         let body = undefined;
         if (req.method === "POST") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipvo/mcp",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "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.",