@shipvo/mcp 0.0.1 → 0.0.3
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/README.md +18 -2
- package/dist/server.js +141 -68
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -8,10 +8,26 @@ Lets AI agents (Claude, Cursor, Claude Code, PiPilot…) **use a Shipvo app with
|
|
|
8
8
|
"env": { "PN_SIM": "http://localhost:4545", "PN_OWNER_TOKEN": "…optional…" } } } }
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
-
Start the simulator first (`
|
|
11
|
+
Start the simulator first (`shipvo sim` in the app). The hosted version needs no local setup: `{ "url": "https://<host>/mcp/<key>" }`.
|
|
12
12
|
|
|
13
|
-
Tools: `list_apps`, `open_app`, `screen`, `tap`, `type`, `scroll`, `back`, `screenshot`, `set_device`, `push_notification`, `device_log`, `end_session`, `owner_describe`, `owner_command`.
|
|
13
|
+
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`.
|
|
14
14
|
|
|
15
15
|
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).
|
|
16
16
|
|
|
17
17
|
The simulator shows only what a phone would: a horizontal rail lists the visible items, so agents swipe it (`scroll right` with the rail's ref) exactly as on a device. Measured against a real Android emulator and iPhone simulator, see `docs/parity-results.md`.
|
|
18
|
+
|
|
19
|
+
## Remote (Streamable HTTP)
|
|
20
|
+
|
|
21
|
+
Run the server where the simulator runs and put it behind HTTPS (a Cloudflare Tunnel is enough):
|
|
22
|
+
|
|
23
|
+
```
|
|
24
|
+
PN_API_KEYS="key-for-claude,key-for-pipilot" shipvo-mcp --http 8787
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Clients connect with a URL instead of a command:
|
|
28
|
+
|
|
29
|
+
```json
|
|
30
|
+
{ "mcpServers": { "shipvo": { "url": "https://sim.shipvo.dev/mcp", "headers": { "Authorization": "Bearer key-for-claude" } } } }
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Each client connection gets its own MCP session; each `open_app` gets its own phone. 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/server.js
CHANGED
|
@@ -1,10 +1,15 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
// Shipvo MCP: agents use Shipvo apps with no phone.
|
|
3
3
|
// PN_SIM=http://localhost:4545 PN_CONTROL=https://purenative-control.purenative.workers.dev PN_OWNER_TOKEN=... shipvo-mcp
|
|
4
|
+
// Remote (Streamable HTTP, what Claude, ChatGPT, Cursor connect to over the network):
|
|
5
|
+
// shipvo-mcp --http 8787 with PN_API_KEYS="key1,key2" (Authorization: Bearer <key>) → POST/GET/DELETE /mcp
|
|
4
6
|
// Tools: list_apps, open_app, screen, tap, type, scroll, back, screenshot, end_session (UI simulator);
|
|
5
7
|
// owner_describe, owner_command (the app's live content, prices, orders: owner token required).
|
|
6
8
|
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
7
9
|
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
|
10
|
+
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
|
|
11
|
+
import http from "node:http";
|
|
12
|
+
import { randomUUID } from "node:crypto";
|
|
8
13
|
import { readFileSync } from "node:fs";
|
|
9
14
|
import { z } from "zod";
|
|
10
15
|
const SIM = (process.env.PN_SIM ?? "http://localhost:4545").replace(/\/$/, "");
|
|
@@ -22,75 +27,143 @@ async function sim(path, body) {
|
|
|
22
27
|
const sessions = new Map();
|
|
23
28
|
const text = (t) => ({ content: [{ type: "text", text: t }] });
|
|
24
29
|
const result = (sid, r) => { const s = sessions.get(sid); if (s)
|
|
25
|
-
s.steps++; return text(r.ok ? (r.screen ?? "") : `Error: ${r.error}\n\nScreen now:\n${r.screen ?? ""}`); };
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
const
|
|
30
|
+
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 ?? ""}`); };
|
|
31
|
+
// Sessions live in the simulator; this map only tracks step counts. A client may reconnect between calls
|
|
32
|
+
// (ChatGPT does), so an unknown id is forwarded and the simulator answers if it knows it.
|
|
33
|
+
const need = (_sid) => { };
|
|
34
|
+
function makeServer(ctx = {}) {
|
|
35
|
+
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.
|
|
29
36
|
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.
|
|
30
37
|
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.
|
|
31
38
|
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.
|
|
32
39
|
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.` });
|
|
33
|
-
|
|
34
|
-
server.tool("
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
})
|
|
47
|
-
const
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
server.tool("
|
|
54
|
-
server.tool("
|
|
55
|
-
need(session);
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
});
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
need(session);
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
});
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
});
|
|
96
|
-
|
|
40
|
+
const allowed = (id) => (ctx.app ? id === ctx.app : !!APPS[id]);
|
|
41
|
+
server.tool("list_apps", "Apps this server can open, with what each one does.", {}, async () => text(Object.entries(APPS).filter(([id]) => allowed(id)).map(([id, a]) => `${id}: ${a.name}. ${a.description}`).join("\n") || `(this key opens ${ctx.app})`));
|
|
42
|
+
server.tool("open_app", "Open an app in a fresh phone-sized session and return its first screen.", {
|
|
43
|
+
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)"),
|
|
44
|
+
session: z.string().optional().describe("Session name (default: generated). One session is one phone."),
|
|
45
|
+
seed_cart: z.array(z.object({ id: z.string(), qty: z.number().int().positive() })).optional().describe("Start with these items already in the cart (test shortcuts)."),
|
|
46
|
+
dark: z.boolean().optional().describe("Dark mode"),
|
|
47
|
+
}, async ({ app, session, seed_cart, dark }) => {
|
|
48
|
+
const id = app.split("@")[0];
|
|
49
|
+
if (!allowed(id))
|
|
50
|
+
throw new Error(ctx.app ? `this key opens "${ctx.app}" only` : `unknown app "${id}". Apps: ${Object.keys(APPS).join(", ")}`);
|
|
51
|
+
if (ctx.scope === "read")
|
|
52
|
+
throw new Error("this key is read-only: it cannot open sessions");
|
|
53
|
+
const sid = session ?? `${id}-${Date.now().toString(36)}`;
|
|
54
|
+
const r = await sim("/session", { session: sid, app, seed_cart, dark });
|
|
55
|
+
sessions.set(sid, { app: id, steps: 0, startedAt: Date.now() });
|
|
56
|
+
return text(`session: ${sid}\napp: ${id} release: ${r.release ?? "local"}\n\n${r.screen ?? ""}`);
|
|
57
|
+
});
|
|
58
|
+
const sid = z.string().describe("Session from open_app");
|
|
59
|
+
const ref = z.string().regex(/^e\d+$/).describe("Element ref from the screen, e.g. e42");
|
|
60
|
+
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" })); });
|
|
61
|
+
server.tool("tap", "Tap a button, link or choice by ref. Returns the new screen.", { session: sid, ref }, async ({ session, ref }) => { need(session); return result(session, await sim("/act", { session, action: "tap", ref })); });
|
|
62
|
+
server.tool("type", "Type into a text field by ref (replaces its content). Returns the new screen.", { session: sid, ref, text: z.string(), enter: z.boolean().optional().describe("Press Enter afterwards") }, async ({ session, ref, text: t, enter }) => { need(session); return result(session, await sim("/act", { session, action: "type", ref, text: t, enter })); });
|
|
63
|
+
server.tool("scroll", "Scroll the page (down/up) or a horizontal rail (right/left, give the rail's ref). Returns the new screen.", { 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") }, async ({ session, direction, ref }) => { need(session); return result(session, await sim("/act", { session, action: "scroll", direction, ref })); });
|
|
64
|
+
server.tool("back", "Go back one screen.", { session: sid }, async ({ session }) => { need(session); return result(session, await sim("/act", { session, action: "back" })); });
|
|
65
|
+
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 }, async ({ session }) => {
|
|
66
|
+
need(session);
|
|
67
|
+
const r = await sim("/act", { session, action: "screenshot" });
|
|
68
|
+
if (!r.ok || !r.path)
|
|
69
|
+
throw new Error(r.error ?? "no screenshot");
|
|
70
|
+
return { content: [{ type: "image", data: readFileSync(r.path).toString("base64"), mimeType: "image/png" }, { type: "text", text: r.screen ?? "" }] };
|
|
71
|
+
});
|
|
72
|
+
// The simulated device: what the phone has, and what happens to it.
|
|
73
|
+
server.tool("set_device", "Change what the simulated phone has: location, a barcode in front of the camera, permission states, whether the fingerprint will match, whether a payment will be approved, network on/off. Takes effect for the next action.", {
|
|
74
|
+
session: sid,
|
|
75
|
+
location: z.object({ latitude: z.number(), longitude: z.number(), accuracy: z.number().optional() }).optional(),
|
|
76
|
+
camera: z.object({ barcode: z.object({ type: z.string(), data: z.string() }).nullable().optional(), delayMs: z.number().optional() }).optional(),
|
|
77
|
+
permissions: z.object({ camera: z.enum(["granted", "denied", "undetermined"]).optional(), location: z.enum(["granted", "denied", "undetermined"]).optional(), notifications: z.enum(["granted", "denied", "undetermined"]).optional() }).optional(),
|
|
78
|
+
biometrics: z.object({ enrolled: z.boolean().optional(), nextResult: z.enum(["success", "fail", "cancel"]).optional() }).optional(),
|
|
79
|
+
payment: z.object({ nextResult: z.enum(["approve", "decline", "timeout", "insufficient_funds"]).optional(), pin: z.string().optional() }).optional(),
|
|
80
|
+
online: z.boolean().optional(),
|
|
81
|
+
}, async ({ session, ...device }) => { need(session); return result(session, await sim("/act", { session, action: "set_device", device })); });
|
|
82
|
+
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 })); });
|
|
83
|
+
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)); });
|
|
84
|
+
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 })); });
|
|
85
|
+
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)); });
|
|
86
|
+
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 })); });
|
|
87
|
+
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 }) => {
|
|
88
|
+
need(session);
|
|
89
|
+
const s = sessions.get(session) ?? { app: session.split("-")[0], steps: 0, startedAt: Date.now() };
|
|
90
|
+
sessions.delete(session);
|
|
91
|
+
let orders = [];
|
|
92
|
+
try {
|
|
93
|
+
orders = JSON.parse(readFileSync(`${process.env.PN_SIM_DIR ?? "/tmp/pn-ui"}/${session}.json`, "utf8")).orders;
|
|
94
|
+
}
|
|
95
|
+
catch { }
|
|
96
|
+
return text(JSON.stringify({ session, app: s.app, steps: s.steps, seconds: Math.round((Date.now() - s.startedAt) / 1000), orders }, null, 2));
|
|
97
|
+
});
|
|
98
|
+
// Owner side: the same typed commands the admin at /app/<id>/admin uses.
|
|
99
|
+
server.tool("owner_describe", "List the owner commands of an app (content, prices, offers, orders, publish). Needs PN_OWNER_TOKEN.", { app: z.string() }, async ({ app }) => {
|
|
100
|
+
const r = await fetch(`${CONTROL}/app/${app}/api/describe`);
|
|
101
|
+
return text(await r.text());
|
|
102
|
+
});
|
|
103
|
+
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 }) => {
|
|
104
|
+
if (ctx.scope && ctx.scope !== "owner")
|
|
105
|
+
throw new Error(`this key has scope "${ctx.scope}": owner commands need an owner key`);
|
|
106
|
+
if (ctx.app && app !== ctx.app)
|
|
107
|
+
throw new Error(`this key is for "${ctx.app}"`);
|
|
108
|
+
const token = ctx.ownerToken || OWNER_TOKEN;
|
|
109
|
+
if (!token)
|
|
110
|
+
throw new Error("owner commands are not enabled on this server.");
|
|
111
|
+
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 ?? {} }) });
|
|
112
|
+
return text(await r.text());
|
|
113
|
+
});
|
|
114
|
+
return server;
|
|
115
|
+
}
|
|
116
|
+
// ---- transport: stdio (local) or Streamable HTTP (remote) ----
|
|
117
|
+
const argi = process.argv.indexOf("--http");
|
|
118
|
+
if (argi < 0) {
|
|
119
|
+
await makeServer().connect(new StdioServerTransport());
|
|
120
|
+
}
|
|
121
|
+
else {
|
|
122
|
+
const port = Number(process.argv[argi + 1] || 8787);
|
|
123
|
+
const keys = new Set((process.env.PN_API_KEYS ?? "").split(",").map((k) => k.trim()).filter(Boolean));
|
|
124
|
+
const transports = new Map();
|
|
125
|
+
const httpServer = http.createServer(async (req, res) => {
|
|
126
|
+
const url = new URL(req.url ?? "/", "http://x");
|
|
127
|
+
if (url.pathname === "/health") {
|
|
128
|
+
res.writeHead(200, { "content-type": "application/json" });
|
|
129
|
+
return res.end(JSON.stringify({ ok: true, sessions: transports.size }));
|
|
130
|
+
}
|
|
131
|
+
if (url.pathname !== "/mcp") {
|
|
132
|
+
res.writeHead(404);
|
|
133
|
+
return res.end();
|
|
134
|
+
}
|
|
135
|
+
// Keys: Bearer <key>. With no keys configured, the server is open (local use behind a tunnel you control).
|
|
136
|
+
if (keys.size) {
|
|
137
|
+
const k = (req.headers.authorization ?? "").replace(/^Bearer\s+/i, "");
|
|
138
|
+
if (!keys.has(k)) {
|
|
139
|
+
res.writeHead(401, { "content-type": "application/json" });
|
|
140
|
+
return res.end(JSON.stringify({ error: "invalid_api_key" }));
|
|
141
|
+
}
|
|
142
|
+
}
|
|
143
|
+
const sid = req.headers["mcp-session-id"];
|
|
144
|
+
let transport = sid ? transports.get(sid) : undefined;
|
|
145
|
+
if (!transport) {
|
|
146
|
+
if (req.method !== "POST") {
|
|
147
|
+
res.writeHead(400);
|
|
148
|
+
return res.end("missing session");
|
|
149
|
+
}
|
|
150
|
+
transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID(), onsessioninitialized: (id) => { transports.set(id, transport); } });
|
|
151
|
+
transport.onclose = () => { for (const [id, t] of transports)
|
|
152
|
+
if (t === transport)
|
|
153
|
+
transports.delete(id); };
|
|
154
|
+
// One McpServer per client connection. Behind sim.shipvo.dev the Worker has checked the key and says which
|
|
155
|
+
// app and scope it grants; locally there are no such headers and every app is allowed.
|
|
156
|
+
const scope = req.headers["x-shipvo-scope"];
|
|
157
|
+
await makeServer({ app: req.headers["x-shipvo-app"] || undefined, scope, ownerToken: req.headers["x-shipvo-owner-token"] || undefined }).connect(transport);
|
|
158
|
+
}
|
|
159
|
+
let body = undefined;
|
|
160
|
+
if (req.method === "POST") {
|
|
161
|
+
let raw = "";
|
|
162
|
+
for await (const ch of req)
|
|
163
|
+
raw += ch;
|
|
164
|
+
body = raw ? JSON.parse(raw) : undefined;
|
|
165
|
+
}
|
|
166
|
+
await transport.handleRequest(req, res, body);
|
|
167
|
+
});
|
|
168
|
+
httpServer.listen(port, () => console.error(`Shipvo MCP over HTTP on http://localhost:${port}/mcp (${keys.size ? keys.size + " key(s)" : "no auth"})`));
|
|
169
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@shipvo/mcp",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.3",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"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.",
|