@buoy-gg/mcp 7.0.65 → 7.0.67

package/dist/cli.mjs

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
-import{createRequire as d}from"module";const R=d(import.meta.url);import{runInit as m}from"./chunk-WVVRNHPL.mjs";import{SyncClient as u,createMcpServer as w,stopAllHidStreamsNow as f,stopAllRecordingsNow as g}from"./chunk-SY6CJRCL.mjs";import"./chunk-QW2BPKIP.mjs";import"./chunk-6EOB4FHJ.mjs";import"./chunk-SWS5NTYM.mjs";import"./chunk-OPHPYPJD.mjs";import"./chunk-MTTWR4T7.mjs";import{StdioServerTransport as b}from"@modelcontextprotocol/sdk/server/stdio.js";console.log=(...e)=>console.error(...e);console.info=(...e)=>console.error(...e);console.debug=(...e)=>console.error(...e);async function v(){const e=process.env.BUOY_BROKER_PORT;const s=new u({url:process.env.BUOY_BROKER_URL,port:e?Number(e):void 0,autoSpawnBroker:process.env.BUOY_NO_SPAWN!=="1"});const r=w(s);const o=new b;let n=false;const c=t=>{if(n)return;n=true;process.stderr.write(`[buoy-mcp] shutting down (${t})
+import{createRequire as d}from"module";const R=d(import.meta.url);import{runInit as m}from"./chunk-7XCEVM3W.mjs";import{SyncClient as u,createMcpServer as w,stopAllHidStreamsNow as f,stopAllRecordingsNow as g}from"./chunk-LDULNQCZ.mjs";import"./chunk-2MSKDRYW.mjs";import"./chunk-VKWX4XAY.mjs";import"./chunk-AMU2EOGE.mjs";import"./chunk-OPHPYPJD.mjs";import"./chunk-MTTWR4T7.mjs";import{StdioServerTransport as b}from"@modelcontextprotocol/sdk/server/stdio.js";console.log=(...e)=>console.error(...e);console.info=(...e)=>console.error(...e);console.debug=(...e)=>console.error(...e);async function v(){const e=process.env.BUOY_BROKER_PORT;const s=new u({url:process.env.BUOY_BROKER_URL,port:e?Number(e):void 0,autoSpawnBroker:process.env.BUOY_NO_SPAWN!=="1"});const r=w(s);const o=new b;let n=false;const c=t=>{if(n)return;n=true;process.stderr.write(`[buoy-mcp] shutting down (${t})
 `);g();f();setTimeout(()=>process.exit(0),2e3).unref();void(async()=>{await s.stop().catch(()=>{});await r.close().catch(()=>{});process.exit(0)})()};process.stdin.once("end",()=>c("stdin closed"));process.stdin.once("close",()=>c("stdin closed"));r.server.onclose=()=>c("transport closed");process.on("SIGINT",()=>c("SIGINT"));process.on("SIGTERM",()=>c("SIGTERM"));process.on("SIGHUP",()=>c("SIGHUP"));await r.connect(o);process.stderr.write(`[buoy-mcp] serving MCP over stdio; connecting to broker\u2026
 `);s.start().then(t=>process.stderr.write(`[buoy-mcp] broker ${t}
 `)).catch(t=>process.stderr.write(`[buoy-mcp] broker connection failed: ${t?.message??t} \u2014 tools will report no devices until it recovers
-`))}async function y(){const e=process.env.BUOY_BROKER_PORT;const s=new u({url:process.env.BUOY_BROKER_URL,port:e?Number(e):void 0,autoSpawnBroker:false});try{const r=await Promise.race([s.start().then(()=>true,()=>false),new Promise(o=>setTimeout(()=>o(false),4e3))]);if(!r)return false;for(let o=0;o<10;o++){if(s.connectedDevices().some(n=>n.tier==="pro"))return true;await new Promise(n=>setTimeout(n,300))}return false}finally{await Promise.race([s.stop().catch(()=>{}),new Promise(r=>setTimeout(r,2e3))])}}if(process.argv[2]==="web-bench"){void(async()=>{try{const e=process.argv.slice(3);const s=e.find(a=>!a.startsWith("--"));if(!s)throw new Error("usage: buoy-mcp web-bench <config.json> [--json]");const{readFileSync:r}=await import("fs");const{runWebBench:o,formatWebBenchMarkdown:n}=await import("./webBench-QCHYXYCA.mjs");const{readEntitlement:c}=await import("./camera-JI2FMAKN.mjs");if(!c().isPro&&!await y()){throw new Error("web-bench is a Buoy Pro feature. Sign in to Buoy Desktop with a Pro account, or open an app signed in to Pro. See https://buoy.gg/pricing.")}const t=JSON.parse(r(s,"utf8"));const i=await o({...t,durationMs:t.durationMs??t.perCaseDurationMs},a=>process.stderr.write(`[web-bench] ${a}
+`))}async function y(){const e=process.env.BUOY_BROKER_PORT;const s=new u({url:process.env.BUOY_BROKER_URL,port:e?Number(e):void 0,autoSpawnBroker:false});try{const r=await Promise.race([s.start().then(()=>true,()=>false),new Promise(o=>setTimeout(()=>o(false),4e3))]);if(!r)return false;for(let o=0;o<10;o++){if(s.connectedDevices().some(n=>n.tier==="pro"))return true;await new Promise(n=>setTimeout(n,300))}return false}finally{await Promise.race([s.stop().catch(()=>{}),new Promise(r=>setTimeout(r,2e3))])}}if(process.argv[2]==="web-bench"){void(async()=>{try{const e=process.argv.slice(3);const s=e.find(a=>!a.startsWith("--"));if(!s)throw new Error("usage: buoy-mcp web-bench <config.json> [--json]");const{readFileSync:r}=await import("fs");const{runWebBench:o,formatWebBenchMarkdown:n}=await import("./webBench-QCHYXYCA.mjs");const{readEntitlement:c}=await import("./camera-F5Q7WMHF.mjs");if(!c().isPro&&!await y()){throw new Error("web-bench is a Buoy Pro feature. Sign in to Buoy Desktop with a Pro account, or open an app signed in to Pro. See https://buoy.gg/pricing.")}const t=JSON.parse(r(s,"utf8"));const i=await o({...t,durationMs:t.durationMs??t.perCaseDurationMs},a=>process.stderr.write(`[web-bench] ${a}
 `));const p=i.status==="failed"||i.browserLeftRunning?1:0;const l=(e.includes("--json")?JSON.stringify(i,null,2):n(i))+"\n";setTimeout(()=>process.exit(p),5e3).unref();process.stdout.write(l,()=>process.exit(p))}catch(e){process.stderr.write(`[buoy-mcp] web-bench failed: ${e?.message??e}
-`,()=>process.exit(1));setTimeout(()=>process.exit(1),5e3).unref()}})()}else if(process.argv[2]==="flow"&&process.argv[3]==="run"){void(async()=>{try{const{parseFlowRunArgs:e,runFlows:s,formatFlowResults:r}=await import("./flowRun-NGLENLWW.mjs");const o=e(process.argv.slice(4));const n=await s(o);const c=o.json?JSON.stringify(n,null,2):r(n);const t=n.every(i=>i.passed)?0:1;setTimeout(()=>process.exit(t),5e3).unref();process.stdout.write(`${c}
+`,()=>process.exit(1));setTimeout(()=>process.exit(1),5e3).unref()}})()}else if(process.argv[2]==="flow"&&process.argv[3]==="run"){void(async()=>{try{const{parseFlowRunArgs:e,runFlows:s,formatFlowResults:r}=await import("./flowRun-WBOCHITQ.mjs");const o=e(process.argv.slice(4));const n=await s(o);const c=o.json?JSON.stringify(n,null,2):r(n);const t=n.every(i=>i.passed)?0:1;setTimeout(()=>process.exit(t),5e3).unref();process.stdout.write(`${c}
 `,()=>process.exit(t))}catch(e){process.stderr.write(`[buoy-mcp] flow run failed: ${e?.message??e}
-`,()=>process.exit(1));setTimeout(()=>process.exit(1),5e3).unref()}})()}else if(process.argv[2]==="farmd"){void import("./simFarm-HLOW7LIW.mjs").then(e=>e.runFarmd()).catch(e=>{process.stderr.write(`[buoy-mcp] farmd failed: ${e?.message??e}
+`,()=>process.exit(1));setTimeout(()=>process.exit(1),5e3).unref()}})()}else if(process.argv[2]==="farmd"){void import("./simFarm-OFT42BGC.mjs").then(e=>e.runFarmd()).catch(e=>{process.stderr.write(`[buoy-mcp] farmd failed: ${e?.message??e}
 `);process.exit(1)})}else if(process.argv[2]==="init"){try{const e=process.argv.slice(3);let s="auto";if(e.includes("--local"))s="local";else if(e.includes("--npx"))s="npx";const r=e.indexOf("--registry");const o=r!==-1?e[r+1]:void 0;m({mode:s,registry:o});process.exit(0)}catch(e){process.stderr.write(`[buoy-mcp] init failed: ${e?.message??e}
 `);process.exit(1)}}else{v().catch(e=>{process.stderr.write(`[buoy-mcp] fatal: ${e?.message??e}
 `);process.exit(1)})}

package/dist/flowRun-WBOCHITQ.mjs

@@ -0,0 +1,2 @@
+import{createRequire as v}from"module";const E=v(import.meta.url);import{SyncClient as y,createMcpServer as R}from"./chunk-LDULNQCZ.mjs";import"./chunk-2MSKDRYW.mjs";import"./chunk-VKWX4XAY.mjs";import"./chunk-AMU2EOGE.mjs";import"./chunk-OPHPYPJD.mjs";import"./chunk-MTTWR4T7.mjs";import{promises as S}from"fs";import $ from"path";import{Client as _}from"@modelcontextprotocol/sdk/client/index.js";import{InMemoryTransport as B}from"@modelcontextprotocol/sdk/inMemory.js";function I(e){const o={names:[]};for(let n=0;n<e.length;n++){const t=e[n];if(t==="--device")o.deviceId=e[++n];else if(t==="--update-snapshots")o.updateSnapshots=true;else if(t==="--json")o.json=true;else if(t==="--wait")o.waitMs=Number(e[++n])*1e3;else if(t==="--all")continue;else if(!t.startsWith("--"))o.names.push(t);else throw new Error(`Unknown option ${t}.`)}return o}async function P(){const e=$.join(process.cwd(),".buoy","flows");return(await S.readdir(e).catch(()=>[])).filter(o=>o.endsWith(".json")).map(o=>o.replace(/\.json$/,"")).sort()}async function g(e,o=n=>process.stderr.write(`${n}
+`)){const n=e.names.length?e.names:await P();if(n.length===0)throw new Error('No saved flows. Save one with run_flow and save:"name", or pass a flow name.');const t=process.env.BUOY_BROKER_PORT;const s=new y({url:process.env.BUOY_BROKER_URL,port:t?Number(t):void 0,autoSpawnBroker:process.env.BUOY_NO_SPAWN!=="1"});const w=R(s);const[d,f]=B.createLinkedPair();const i=new _({name:"buoy-flow-run",version:"1"});try{await w.connect(f);await i.connect(d);await s.start();const a=Date.now()+(e.waitMs??6e4);while(Date.now()<a&&!s.connectedDevices().some(r=>(r.isPro||r.tier==="free")&&(!e.deviceId||r.deviceId===e.deviceId))){await new Promise(r=>setTimeout(r,500))}if(!s.connectedDevices().some(r=>r.isPro||r.tier==="free")){throw new Error("No app on a Buoy account is connected. Start the app (with Buoy) on a simulator or device, then run again.")}const u=[];for(const r of n){const m=Date.now();o(`\u25B6 ${r}`);const l=await i.callTool({name:"run_flow",arguments:{flow:r,include:"none",...e.deviceId?{deviceId:e.deviceId}:{},...e.updateSnapshots?{updateSnapshots:true}:{}}},void 0,{timeout:10*6e4});const h=(l.content??[]).filter(c=>c.type==="text").map(c=>c.text).join("\n");const p=l.isError!==true;u.push({name:r,passed:p,ms:Date.now()-m,report:h});o(`${p?"\u2713":"\u2717"} ${r} (${((Date.now()-m)/1e3).toFixed(1)}s)`)}return u}finally{await i.close().catch(()=>void 0);await Promise.race([s.stop().catch(()=>void 0),new Promise(a=>setTimeout(a,2e3))])}}function j(e){const o=e.filter(t=>!t.passed);const n=[`${e.length-o.length} of ${e.length} flows passed.`];for(const t of o){n.push("",`\u2717 ${t.name}`,t.report.trim(),`  Rerun: npx @buoy-gg/mcp flow run ${t.name}`)}return n.join("\n")}export{j as formatFlowResults,I as parseFlowRunArgs,g as runFlows};

package/dist/index.d.mts

@@ -1,6 +1,8 @@
 import { ToolCapability } from '@buoy-gg/sync-broker';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 
+type AccessLevel = "free" | "pro";
+
 interface SyncClientOptions {
     /** Broker URL to connect to. @default http://localhost:42831 */
     url?: string;
@@ -24,14 +26,14 @@ interface DeviceInfo {
     /** Whether the connected app reported an active Buoy Pro license. */
     isPro: boolean;
     /**
-     * The app's tier once the broker has admitted its account, or "locked"
-     * until then. Apps older than the tier split report only `isPro`, which
-     * maps exactly — a key could only ever grant Pro back then.
+     * The app's tier after admission. New sockets are "checking"; an account
+     * lock is "locked". Older apps report only `isPro`, which maps to Pro
+     * or locked because keys could only grant Pro before the tier split.
      *
      * Surfaced so `list_devices` can say WHY the MCP is blocked: "signed in on
      * the free tier" and "no admitted account" are different problems.
      */
-    tier: "locked" | "free" | "pro";
+    tier: "checking" | "locked" | "free" | "pro";
     /**
      * More than one app is registered under this id right now (a pinned
      * `externalSync.deviceId` copied onto two devices). Actions sent to it
@@ -116,7 +118,10 @@ declare class SyncClient {
      * with every simulator erase and fresh dev client, and each one can hold
      * multi-MB snapshots, so a long-lived server has to forget eventually.
      */
+    /** Whether the broker admitted this host's Buoy account. */
+    isAdmitted(): boolean;
     private requireAdmission;
+    private transportLost;
     private setAdmission;
     private requireDeviceAccount;
     private lockDevice;
@@ -145,22 +150,53 @@ declare class SyncClient {
      */
     resolveDevice(deviceId?: string): string;
     /**
-     * Resolve a target device AND require it to be on Buoy Pro. The Buoy MCP is a
-     * Pro feature: data/action tools call this so a free app can't be driven
-     * through the MCP. The app's Keygen-validated license is the source of truth
-     * (the device reports it over the broker); this just reads that flag.
+     * Resolve a target device AND require the tier the current tool call needs.
+     * Most tools need Buoy Pro; the free ones (access/policy.ts) also take an app
+     * on the free tier. The level comes from the call's scope, set centrally in
+     * server.ts before any handler runs, so a handler can't pick its own. With no
+     * scope (work outside any tool call) the level is Pro. The app's own license
+     * check is the source of truth (the device reports it over the broker); this
+     * just reads it.
      *
-     * `list_devices` deliberately does NOT call this — a free user can still see
-     * their device and that it's unlicensed, which explains why everything else
-     * is blocked.
+     * `list_devices` deliberately does NOT call this — a user without access can
+     * still see their device and its tier, which explains what is blocked.
      */
     requireProDevice(deviceId?: string): string;
     /**
-     * Where a device stands on access: connected and Pro ("ready"), not
-     * connected ("offline"), connected but its account not announced yet
-     * ("pending"), or announced on a tier without MCP access ("denied").
+     * The check under every app call (callAction, getSnapshot, the snapshot
+     * cache, lastSync), on top of requireProDevice. A call to a Pro app always
+     * passes. A call to any other app passes only inside a free tool call and
+     * only for the app calls listed in access/policy.ts, so a Pro tool that
+     * forgot requireProDevice still can't act on a free app, and a free tool
+     * can't reach Pro data by any path. Work outside any tool call (reconnects,
+     * health pings) is plumbing and passes.
+     */
+    private checkAppCall;
+    /**
+     * A free app's tap must land on the app, not on Buoy's own panels: their
+     * controls do what Pro tools do. The app side leaves Buoy out of fuzzy
+     * matches but lets an exact testID or nativeTag through, so on a free app an
+     * exact tap goes through only when the app-only screen list shows that
+     * target. Anything this can't prove (a Buoy control, an off-screen target, a
+     * failed read, a broadcast to "All") is refused. Resolves to replacement
+     * params when it narrows the tap (never edits the caller's object, which a
+     * flow reuses on retries). Returns null, without an await, for every call it
+     * doesn't apply to.
+     */
+    private refuseBuoyPanelTap;
+    /**
+     * Whether this device was seen on a tier good enough for the current call,
+     * connected or not. For host controls that keep working after the app
+     * quits or crashes (see hostKit), and for the last-sync fallback.
+     */
+    deviceWasAllowed(deviceId: string): boolean;
+    /**
+     * Where a device stands for `level` (the current call's by default):
+     * connected and allowed ("ready"), not connected ("offline"), connected but
+     * its account not announced yet ("pending"), or announced on a tier without
+     * this access ("denied").
      */
-    accessState(deviceId: string): "ready" | "offline" | "pending" | "denied";
+    accessState(deviceId: string, level?: AccessLevel): "ready" | "offline" | "pending" | "denied";
     private healthOf;
     /** The device answered — it's alive. */
     private noteOk;
@@ -408,94 +444,6 @@ declare function runInit(opts?: InitOptions): void;
  */
 declare function registerGenericTools(server: McpServer, sync: SyncClient): void;
 
-/**
- * The perf-monitor tool pack: ergonomic, workflow-level tools that wrap the
- * generic call_action/get_snapshot for benchmarking. Headlined by
- * run_benchmark_batch — feed a case matrix, get back a ranked winner.
- */
-declare function registerPerfMonitorTools(server: McpServer, sync: SyncClient): void;
-
-/**
- * The events tool pack: a compact, token-bounded view of the app's captured
- * events. Drives the device's existing "Copy Settings" formatter (the heavy raw
- * payloads stay on the device unless asked for), so the model gets a compact
- * log by default and opts into detail when needed.
- */
-declare function registerEventsTools(server: McpServer, sync: SyncClient): void;
-
-/**
- * The react-query pack: a compact current-CACHE reader (the activity log is
- * already covered by get_events) plus the cache-mutating actions, which reuse
- * the adapter's existing handlers verbatim.
- */
-declare function registerReactQueryTools(server: McpServer, sync: SyncClient): void;
-
-/**
- * The zustand pack: a compact current-STATE reader (the change log is already
- * covered by get_events sources:['zustand']) plus a setState action that reuses
- * the adapter's existing handler.
- */
-declare function registerZustandTools(server: McpServer, sync: SyncClient): void;
-
-/**
- * The jotai pack: a compact current-VALUE reader (the change log is already
- * covered by get_events sources:['jotai']) plus a setAtom action for writable
- * atoms.
- */
-declare function registerJotaiTools(server: McpServer, sync: SyncClient): void;
-
-/**
- * The redux pack: a compact current-STATE reader (redux is action-based, so the
- * current state isn't in the action-log snapshot — get_events sources:['redux']
- * covers the action history) plus a dispatch action, both driving the live
- * instrumented store.
- */
-declare function registerReduxTools(server: McpServer, sync: SyncClient): void;
-
-/**
- * The storage pack: a friendly, compact reader + writer over the app's
- * storage backends — AsyncStorage, MMKV (all registered instances), and Expo
- * SecureStore (registered keys). Reuses the storage adapter's async.*, mmkv.*
- * and secure.* actions; the device already strips Buoy's own devtool keys at
- * the source, so only real app keys are returned.
- */
-declare function registerStorageTools(server: McpServer, sync: SyncClient): void;
-
-/**
- * The routes pack: current route + navigation stack (compact) with an optional
- * sitemap, plus a navigate action — all reusing the route-events adapter's
- * existing snapshot and `navigate` action.
- */
-declare function registerRoutesTools(server: McpServer, sync: SyncClient): void;
-
-/**
- * The console pack: a compact, token-bounded tail of the app's captured
- * console.* logs, reusing the console adapter's snapshot (each entry carries a
- * pre-rendered single-line `message`, so no heavy args cross into context).
- */
-declare function registerConsoleTools(server: McpServer, sync: SyncClient): void;
-
-/**
- * The screenshot pack: capture a tight, focused PNG of a single RN component,
- * reusing the same flow the desktop app's Screenshot tool uses — the device's
- * highlight-updates `locateComponent` action resolves a testID/name to a live
- * on-screen rect (scrolling it into view first), and the MCP server itself
- * captures + crops the iOS Simulator's framebuffer via `xcrun simctl` + `sips`
- * (no desktop app required, as long as the MCP server runs on the same Mac as
- * the booted Simulator).
- */
-declare function registerScreenshotTools(server: McpServer, sync: SyncClient): void;
-
-/**
- * A one-line update notice if a newer version is published, else null. Safe to
- * await inline — bounded by the fetch timeout and short-circuited by the cache.
- */
-declare function getUpdateNotice(now?: number): Promise<string | null>;
-
-declare const VERSION: string;
-/** The published npm package name — used by init + the update check. */
-declare const PACKAGE_NAME = "@buoy-gg/mcp";
-
 /** One row in an automation batch (MCP-friendly input; `id` added internally). */
 interface PerfCaseInput {
     /** Display name; becomes the saved report's metadata.name. */
@@ -691,6 +639,94 @@ interface RenderCapture {
     }[];
 }
 
+/**
+ * The perf-monitor tool pack: ergonomic, workflow-level tools that wrap the
+ * generic call_action/get_snapshot for benchmarking. Headlined by
+ * run_benchmark_batch — feed a case matrix, get back a ranked winner.
+ */
+declare function registerPerfMonitorTools(server: McpServer, sync: SyncClient): void;
+
+/**
+ * The events tool pack: a compact, token-bounded view of the app's captured
+ * events. Drives the device's existing "Copy Settings" formatter (the heavy raw
+ * payloads stay on the device unless asked for), so the model gets a compact
+ * log by default and opts into detail when needed.
+ */
+declare function registerEventsTools(server: McpServer, sync: SyncClient): void;
+
+/**
+ * The react-query pack: a compact current-CACHE reader (the activity log is
+ * already covered by get_events) plus the cache-mutating actions, which reuse
+ * the adapter's existing handlers verbatim.
+ */
+declare function registerReactQueryTools(server: McpServer, sync: SyncClient): void;
+
+/**
+ * The zustand pack: a compact current-STATE reader (the change log is already
+ * covered by get_events sources:['zustand']) plus a setState action that reuses
+ * the adapter's existing handler.
+ */
+declare function registerZustandTools(server: McpServer, sync: SyncClient): void;
+
+/**
+ * The jotai pack: a compact current-VALUE reader (the change log is already
+ * covered by get_events sources:['jotai']) plus a setAtom action for writable
+ * atoms.
+ */
+declare function registerJotaiTools(server: McpServer, sync: SyncClient): void;
+
+/**
+ * The redux pack: a compact current-STATE reader (redux is action-based, so the
+ * current state isn't in the action-log snapshot — get_events sources:['redux']
+ * covers the action history) plus a dispatch action, both driving the live
+ * instrumented store.
+ */
+declare function registerReduxTools(server: McpServer, sync: SyncClient): void;
+
+/**
+ * The storage pack: a friendly, compact reader + writer over the app's
+ * storage backends — AsyncStorage, MMKV (all registered instances), and Expo
+ * SecureStore (registered keys). Reuses the storage adapter's async.*, mmkv.*
+ * and secure.* actions; the device already strips Buoy's own devtool keys at
+ * the source, so only real app keys are returned.
+ */
+declare function registerStorageTools(server: McpServer, sync: SyncClient): void;
+
+/**
+ * The routes pack: current route + navigation stack (compact) with an optional
+ * sitemap, plus a navigate action — all reusing the route-events adapter's
+ * existing snapshot and `navigate` action.
+ */
+declare function registerRoutesTools(server: McpServer, sync: SyncClient): void;
+
+/**
+ * The console pack: a compact, token-bounded tail of the app's captured
+ * console.* logs, reusing the console adapter's snapshot (each entry carries a
+ * pre-rendered single-line `message`, so no heavy args cross into context).
+ */
+declare function registerConsoleTools(server: McpServer, sync: SyncClient): void;
+
+/**
+ * The screenshot pack: capture a tight, focused PNG of a single RN component,
+ * reusing the same flow the desktop app's Screenshot tool uses — the device's
+ * highlight-updates `locateComponent` action resolves a testID/name to a live
+ * on-screen rect (scrolling it into view first), and the MCP server itself
+ * captures + crops the iOS Simulator's framebuffer via `xcrun simctl` + `sips`
+ * (no desktop app required, as long as the MCP server runs on the same Mac as
+ * the booted Simulator).
+ */
+declare function registerScreenshotTools(server: McpServer, sync: SyncClient): void;
+
+/**
+ * A one-line update notice if a newer version is published, else null. Safe to
+ * await inline — bounded by the fetch timeout and short-circuited by the cache.
+ */
+declare function getUpdateNotice(now?: number): Promise<string | null>;
+
+declare const VERSION: string;
+/** The published npm package name — used by init + the update check. */
+declare const PACKAGE_NAME = "@buoy-gg/mcp";
+
 interface BuildConfigInput {
     targetRoute: string;
     bounceRoute?: string;

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 import { ToolCapability } from '@buoy-gg/sync-broker';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 
+type AccessLevel = "free" | "pro";
+
 interface SyncClientOptions {
     /** Broker URL to connect to. @default http://localhost:42831 */
     url?: string;
@@ -24,14 +26,14 @@ interface DeviceInfo {
     /** Whether the connected app reported an active Buoy Pro license. */
     isPro: boolean;
     /**
-     * The app's tier once the broker has admitted its account, or "locked"
-     * until then. Apps older than the tier split report only `isPro`, which
-     * maps exactly — a key could only ever grant Pro back then.
+     * The app's tier after admission. New sockets are "checking"; an account
+     * lock is "locked". Older apps report only `isPro`, which maps to Pro
+     * or locked because keys could only grant Pro before the tier split.
      *
      * Surfaced so `list_devices` can say WHY the MCP is blocked: "signed in on
      * the free tier" and "no admitted account" are different problems.
      */
-    tier: "locked" | "free" | "pro";
+    tier: "checking" | "locked" | "free" | "pro";
     /**
      * More than one app is registered under this id right now (a pinned
      * `externalSync.deviceId` copied onto two devices). Actions sent to it
@@ -116,7 +118,10 @@ declare class SyncClient {
      * with every simulator erase and fresh dev client, and each one can hold
      * multi-MB snapshots, so a long-lived server has to forget eventually.
      */
+    /** Whether the broker admitted this host's Buoy account. */
+    isAdmitted(): boolean;
     private requireAdmission;
+    private transportLost;
     private setAdmission;
     private requireDeviceAccount;
     private lockDevice;
@@ -145,22 +150,53 @@ declare class SyncClient {
      */
     resolveDevice(deviceId?: string): string;
     /**
-     * Resolve a target device AND require it to be on Buoy Pro. The Buoy MCP is a
-     * Pro feature: data/action tools call this so a free app can't be driven
-     * through the MCP. The app's Keygen-validated license is the source of truth
-     * (the device reports it over the broker); this just reads that flag.
+     * Resolve a target device AND require the tier the current tool call needs.
+     * Most tools need Buoy Pro; the free ones (access/policy.ts) also take an app
+     * on the free tier. The level comes from the call's scope, set centrally in
+     * server.ts before any handler runs, so a handler can't pick its own. With no
+     * scope (work outside any tool call) the level is Pro. The app's own license
+     * check is the source of truth (the device reports it over the broker); this
+     * just reads it.
      *
-     * `list_devices` deliberately does NOT call this — a free user can still see
-     * their device and that it's unlicensed, which explains why everything else
-     * is blocked.
+     * `list_devices` deliberately does NOT call this — a user without access can
+     * still see their device and its tier, which explains what is blocked.
      */
     requireProDevice(deviceId?: string): string;
     /**
-     * Where a device stands on access: connected and Pro ("ready"), not
-     * connected ("offline"), connected but its account not announced yet
-     * ("pending"), or announced on a tier without MCP access ("denied").
+     * The check under every app call (callAction, getSnapshot, the snapshot
+     * cache, lastSync), on top of requireProDevice. A call to a Pro app always
+     * passes. A call to any other app passes only inside a free tool call and
+     * only for the app calls listed in access/policy.ts, so a Pro tool that
+     * forgot requireProDevice still can't act on a free app, and a free tool
+     * can't reach Pro data by any path. Work outside any tool call (reconnects,
+     * health pings) is plumbing and passes.
+     */
+    private checkAppCall;
+    /**
+     * A free app's tap must land on the app, not on Buoy's own panels: their
+     * controls do what Pro tools do. The app side leaves Buoy out of fuzzy
+     * matches but lets an exact testID or nativeTag through, so on a free app an
+     * exact tap goes through only when the app-only screen list shows that
+     * target. Anything this can't prove (a Buoy control, an off-screen target, a
+     * failed read, a broadcast to "All") is refused. Resolves to replacement
+     * params when it narrows the tap (never edits the caller's object, which a
+     * flow reuses on retries). Returns null, without an await, for every call it
+     * doesn't apply to.
+     */
+    private refuseBuoyPanelTap;
+    /**
+     * Whether this device was seen on a tier good enough for the current call,
+     * connected or not. For host controls that keep working after the app
+     * quits or crashes (see hostKit), and for the last-sync fallback.
+     */
+    deviceWasAllowed(deviceId: string): boolean;
+    /**
+     * Where a device stands for `level` (the current call's by default):
+     * connected and allowed ("ready"), not connected ("offline"), connected but
+     * its account not announced yet ("pending"), or announced on a tier without
+     * this access ("denied").
      */
-    accessState(deviceId: string): "ready" | "offline" | "pending" | "denied";
+    accessState(deviceId: string, level?: AccessLevel): "ready" | "offline" | "pending" | "denied";
     private healthOf;
     /** The device answered — it's alive. */
     private noteOk;
@@ -408,94 +444,6 @@ declare function runInit(opts?: InitOptions): void;
  */
 declare function registerGenericTools(server: McpServer, sync: SyncClient): void;
 
-/**
- * The perf-monitor tool pack: ergonomic, workflow-level tools that wrap the
- * generic call_action/get_snapshot for benchmarking. Headlined by
- * run_benchmark_batch — feed a case matrix, get back a ranked winner.
- */
-declare function registerPerfMonitorTools(server: McpServer, sync: SyncClient): void;
-
-/**
- * The events tool pack: a compact, token-bounded view of the app's captured
- * events. Drives the device's existing "Copy Settings" formatter (the heavy raw
- * payloads stay on the device unless asked for), so the model gets a compact
- * log by default and opts into detail when needed.
- */
-declare function registerEventsTools(server: McpServer, sync: SyncClient): void;
-
-/**
- * The react-query pack: a compact current-CACHE reader (the activity log is
- * already covered by get_events) plus the cache-mutating actions, which reuse
- * the adapter's existing handlers verbatim.
- */
-declare function registerReactQueryTools(server: McpServer, sync: SyncClient): void;
-
-/**
- * The zustand pack: a compact current-STATE reader (the change log is already
- * covered by get_events sources:['zustand']) plus a setState action that reuses
- * the adapter's existing handler.
- */
-declare function registerZustandTools(server: McpServer, sync: SyncClient): void;
-
-/**
- * The jotai pack: a compact current-VALUE reader (the change log is already
- * covered by get_events sources:['jotai']) plus a setAtom action for writable
- * atoms.
- */
-declare function registerJotaiTools(server: McpServer, sync: SyncClient): void;
-
-/**
- * The redux pack: a compact current-STATE reader (redux is action-based, so the
- * current state isn't in the action-log snapshot — get_events sources:['redux']
- * covers the action history) plus a dispatch action, both driving the live
- * instrumented store.
- */
-declare function registerReduxTools(server: McpServer, sync: SyncClient): void;
-
-/**
- * The storage pack: a friendly, compact reader + writer over the app's
- * storage backends — AsyncStorage, MMKV (all registered instances), and Expo
- * SecureStore (registered keys). Reuses the storage adapter's async.*, mmkv.*
- * and secure.* actions; the device already strips Buoy's own devtool keys at
- * the source, so only real app keys are returned.
- */
-declare function registerStorageTools(server: McpServer, sync: SyncClient): void;
-
-/**
- * The routes pack: current route + navigation stack (compact) with an optional
- * sitemap, plus a navigate action — all reusing the route-events adapter's
- * existing snapshot and `navigate` action.
- */
-declare function registerRoutesTools(server: McpServer, sync: SyncClient): void;
-
-/**
- * The console pack: a compact, token-bounded tail of the app's captured
- * console.* logs, reusing the console adapter's snapshot (each entry carries a
- * pre-rendered single-line `message`, so no heavy args cross into context).
- */
-declare function registerConsoleTools(server: McpServer, sync: SyncClient): void;
-
-/**
- * The screenshot pack: capture a tight, focused PNG of a single RN component,
- * reusing the same flow the desktop app's Screenshot tool uses — the device's
- * highlight-updates `locateComponent` action resolves a testID/name to a live
- * on-screen rect (scrolling it into view first), and the MCP server itself
- * captures + crops the iOS Simulator's framebuffer via `xcrun simctl` + `sips`
- * (no desktop app required, as long as the MCP server runs on the same Mac as
- * the booted Simulator).
- */
-declare function registerScreenshotTools(server: McpServer, sync: SyncClient): void;
-
-/**
- * A one-line update notice if a newer version is published, else null. Safe to
- * await inline — bounded by the fetch timeout and short-circuited by the cache.
- */
-declare function getUpdateNotice(now?: number): Promise<string | null>;
-
-declare const VERSION: string;
-/** The published npm package name — used by init + the update check. */
-declare const PACKAGE_NAME = "@buoy-gg/mcp";
-
 /** One row in an automation batch (MCP-friendly input; `id` added internally). */
 interface PerfCaseInput {
     /** Display name; becomes the saved report's metadata.name. */
@@ -691,6 +639,94 @@ interface RenderCapture {
     }[];
 }
 
+/**
+ * The perf-monitor tool pack: ergonomic, workflow-level tools that wrap the
+ * generic call_action/get_snapshot for benchmarking. Headlined by
+ * run_benchmark_batch — feed a case matrix, get back a ranked winner.
+ */
+declare function registerPerfMonitorTools(server: McpServer, sync: SyncClient): void;
+
+/**
+ * The events tool pack: a compact, token-bounded view of the app's captured
+ * events. Drives the device's existing "Copy Settings" formatter (the heavy raw
+ * payloads stay on the device unless asked for), so the model gets a compact
+ * log by default and opts into detail when needed.
+ */
+declare function registerEventsTools(server: McpServer, sync: SyncClient): void;
+
+/**
+ * The react-query pack: a compact current-CACHE reader (the activity log is
+ * already covered by get_events) plus the cache-mutating actions, which reuse
+ * the adapter's existing handlers verbatim.
+ */
+declare function registerReactQueryTools(server: McpServer, sync: SyncClient): void;
+
+/**
+ * The zustand pack: a compact current-STATE reader (the change log is already
+ * covered by get_events sources:['zustand']) plus a setState action that reuses
+ * the adapter's existing handler.
+ */
+declare function registerZustandTools(server: McpServer, sync: SyncClient): void;
+
+/**
+ * The jotai pack: a compact current-VALUE reader (the change log is already
+ * covered by get_events sources:['jotai']) plus a setAtom action for writable
+ * atoms.
+ */
+declare function registerJotaiTools(server: McpServer, sync: SyncClient): void;
+
+/**
+ * The redux pack: a compact current-STATE reader (redux is action-based, so the
+ * current state isn't in the action-log snapshot — get_events sources:['redux']
+ * covers the action history) plus a dispatch action, both driving the live
+ * instrumented store.
+ */
+declare function registerReduxTools(server: McpServer, sync: SyncClient): void;
+
+/**
+ * The storage pack: a friendly, compact reader + writer over the app's
+ * storage backends — AsyncStorage, MMKV (all registered instances), and Expo
+ * SecureStore (registered keys). Reuses the storage adapter's async.*, mmkv.*
+ * and secure.* actions; the device already strips Buoy's own devtool keys at
+ * the source, so only real app keys are returned.
+ */
+declare function registerStorageTools(server: McpServer, sync: SyncClient): void;
+
+/**
+ * The routes pack: current route + navigation stack (compact) with an optional
+ * sitemap, plus a navigate action — all reusing the route-events adapter's
+ * existing snapshot and `navigate` action.
+ */
+declare function registerRoutesTools(server: McpServer, sync: SyncClient): void;
+
+/**
+ * The console pack: a compact, token-bounded tail of the app's captured
+ * console.* logs, reusing the console adapter's snapshot (each entry carries a
+ * pre-rendered single-line `message`, so no heavy args cross into context).
+ */
+declare function registerConsoleTools(server: McpServer, sync: SyncClient): void;
+
+/**
+ * The screenshot pack: capture a tight, focused PNG of a single RN component,
+ * reusing the same flow the desktop app's Screenshot tool uses — the device's
+ * highlight-updates `locateComponent` action resolves a testID/name to a live
+ * on-screen rect (scrolling it into view first), and the MCP server itself
+ * captures + crops the iOS Simulator's framebuffer via `xcrun simctl` + `sips`
+ * (no desktop app required, as long as the MCP server runs on the same Mac as
+ * the booted Simulator).
+ */
+declare function registerScreenshotTools(server: McpServer, sync: SyncClient): void;
+
+/**
+ * A one-line update notice if a newer version is published, else null. Safe to
+ * await inline — bounded by the fetch timeout and short-circuited by the cache.
+ */
+declare function getUpdateNotice(now?: number): Promise<string | null>;
+
+declare const VERSION: string;
+/** The published npm package name — used by init + the update check. */
+declare const PACKAGE_NAME = "@buoy-gg/mcp";
+
 interface BuildConfigInput {
     targetRoute: string;
     bounceRoute?: string;