@buoy-gg/mcp 4.0.1 → 5.0.0

package/dist/cli.mjs

@@ -1,76 +1,12 @@
 #!/usr/bin/env node
 import {
   SyncClient,
-  createMcpServer
-} from "./chunk-55UIOHVS.mjs";
+  createMcpServer,
+  runInit
+} from "./chunk-SQKZOREF.mjs";
 
 // src/cli.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-
-// src/init.ts
-import fs from "fs";
-import path from "path";
-function runInit(opts = {}) {
-  const cwd = opts.cwd ?? process.cwd();
-  const cliPath = opts.cliPath ?? path.resolve(__dirname, "cli.js");
-  const skillSrcDir = opts.skillSrcDir ?? path.resolve(__dirname, "../skill");
-  const log = opts.log ?? ((m) => process.stdout.write(m + "\n"));
-  const entry = { type: "stdio", command: "node", args: [cliPath] };
-  const done = [];
-  upsertMcpConfig(path.join(cwd, ".mcp.json"), "mcpServers", entry, cwd, done);
-  if (fs.existsSync(path.join(cwd, ".cursor"))) {
-    upsertMcpConfig(path.join(cwd, ".cursor", "mcp.json"), "mcpServers", entry, cwd, done);
-  }
-  if (fs.existsSync(path.join(cwd, ".vscode"))) {
-    upsertMcpConfig(path.join(cwd, ".vscode", "mcp.json"), "servers", entry, cwd, done);
-  }
-  copySkill(skillSrcDir, cwd, done);
-  log("Buoy MCP installed:");
-  for (const line of done) log("  \u2022 " + line);
-  log("");
-  log("Next steps:");
-  log("  1. Restart your editor (or reconnect the MCP server) to load `buoy`.");
-  log("  2. Open your app with Buoy devtools running on a device or simulator.");
-  log('  3. Say "buoy optimize" to start a guided performance pass.');
-}
-function upsertMcpConfig(file, key, entry, cwd, done) {
-  let json = {};
-  if (fs.existsSync(file)) {
-    try {
-      json = JSON.parse(fs.readFileSync(file, "utf8"));
-    } catch {
-      fs.copyFileSync(file, file + ".bak");
-      done.push(`existing ${rel(file, cwd)} was invalid JSON \u2014 backed up to ${rel(file, cwd)}.bak`);
-      json = {};
-    }
-  } else {
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-  }
-  const servers = json[key] && typeof json[key] === "object" ? json[key] : {};
-  const existed = "buoy" in servers;
-  servers.buoy = entry;
-  json[key] = servers;
-  fs.writeFileSync(file, JSON.stringify(json, null, 2) + "\n");
-  done.push(`${existed ? "updated" : "added"} \`buoy\` in ${rel(file, cwd)}`);
-}
-function copySkill(skillSrcDir, cwd, done) {
-  const src = path.join(skillSrcDir, "buoy-optimize", "SKILL.md");
-  if (!fs.existsSync(src)) {
-    done.push("\u26A0 skill source not found \u2014 skipped (skill not installed)");
-    return;
-  }
-  const destDir = path.join(cwd, ".claude", "skills", "buoy-optimize");
-  fs.mkdirSync(destDir, { recursive: true });
-  const dest = path.join(destDir, "SKILL.md");
-  fs.copyFileSync(src, dest);
-  done.push(`installed the buoy-optimize skill \u2192 ${rel(dest, cwd)}`);
-}
-function rel(file, cwd) {
-  const r = path.relative(cwd, file);
-  return r && !r.startsWith("..") ? r : file;
-}
-
-// src/cli.ts
 async function main() {
   const portEnv = process.env.BUOY_BROKER_PORT;
   const sync = new SyncClient({

package/dist/index.d.mts

@@ -120,6 +120,38 @@ declare class SyncClient {
  */
 declare function createMcpServer(sync: SyncClient): McpServer;
 
+/**
+ * `buoy-mcp init` — wire the Buoy MCP server + the buoy-optimize skill into a
+ * project, so a user doesn't have to hand-edit any config.
+ *
+ * - Registers the `buoy` server in the editor MCP config(s): `.mcp.json`
+ *   (Claude Code, always), and `.cursor/mcp.json` / `.vscode/mcp.json` when
+ *   those editor folders already exist.
+ * - Copies the `buoy-optimize` skill into `.claude/skills/`.
+ *
+ * Idempotent + non-destructive: merges into existing configs (never clobbers
+ * other servers), and re-running just refreshes the buoy entry + skill.
+ *
+ * By default the written config launches the server via
+ * `npx -y @buoy-gg/mcp@latest`, so every editor restart re-resolves the newest
+ * published version — users can't get pinned to a stale local copy. (Passing an
+ * explicit `cliPath` writes a `node <path>` entry instead, for local dev/testing
+ * against a working build.)
+ */
+interface InitOptions {
+    /** Project root to install into. @default process.cwd() */
+    cwd?: string;
+    /**
+     * Absolute path to a built cli.js. When set, the config launches that file
+     * via `node` instead of `npx @latest` — for local development only.
+     */
+    cliPath?: string;
+    /** Where the skill source lives. @default resolved from __dirname (../skill). */
+    skillSrcDir?: string;
+    log?: (msg: string) => void;
+}
+declare function runInit(opts?: InitOptions): void;
+
 /**
  * The generic core: tools that work for ANY Buoy tool exposing a sync adapter,
  * with zero tool-specific knowledge. Tool packs add ergonomic wrappers on top.
@@ -133,6 +165,86 @@ declare function registerGenericTools(server: McpServer, sync: SyncClient): void
  */
 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
+ * AsyncStorage. Reuses the storage adapter's existing async.* 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. */
@@ -376,4 +488,4 @@ declare const DASHBOARD_NAME = "Dashboard";
 /** Target token meaning "every connected device". */
 declare const ALL_DEVICES = "All";
 
-export { ALL_DEVICES, BROKER_PORT, BROKER_URL, type BrokerMode, DASHBOARD_NAME, DEFAULT_ACTION_TIMEOUT_MS, DEFAULT_SNAPSHOT_TIMEOUT_MS, type DeviceInfo, SyncClient, type SyncClientOptions, buildAutomationConfig, compareReportStats, createMcpServer, estimateBatchMs, formatRankingMarkdown, rankBatchFromIndex, registerGenericTools, registerPerfMonitorTools };
+export { ALL_DEVICES, BROKER_PORT, BROKER_URL, type BrokerMode, DASHBOARD_NAME, DEFAULT_ACTION_TIMEOUT_MS, DEFAULT_SNAPSHOT_TIMEOUT_MS, type DeviceInfo, type InitOptions, PACKAGE_NAME, SyncClient, type SyncClientOptions, VERSION, buildAutomationConfig, compareReportStats, createMcpServer, estimateBatchMs, formatRankingMarkdown, getUpdateNotice, rankBatchFromIndex, registerConsoleTools, registerEventsTools, registerGenericTools, registerJotaiTools, registerPerfMonitorTools, registerReactQueryTools, registerReduxTools, registerRoutesTools, registerScreenshotTools, registerStorageTools, registerZustandTools, runInit };

package/dist/index.d.ts

@@ -120,6 +120,38 @@ declare class SyncClient {
  */
 declare function createMcpServer(sync: SyncClient): McpServer;
 
+/**
+ * `buoy-mcp init` — wire the Buoy MCP server + the buoy-optimize skill into a
+ * project, so a user doesn't have to hand-edit any config.
+ *
+ * - Registers the `buoy` server in the editor MCP config(s): `.mcp.json`
+ *   (Claude Code, always), and `.cursor/mcp.json` / `.vscode/mcp.json` when
+ *   those editor folders already exist.
+ * - Copies the `buoy-optimize` skill into `.claude/skills/`.
+ *
+ * Idempotent + non-destructive: merges into existing configs (never clobbers
+ * other servers), and re-running just refreshes the buoy entry + skill.
+ *
+ * By default the written config launches the server via
+ * `npx -y @buoy-gg/mcp@latest`, so every editor restart re-resolves the newest
+ * published version — users can't get pinned to a stale local copy. (Passing an
+ * explicit `cliPath` writes a `node <path>` entry instead, for local dev/testing
+ * against a working build.)
+ */
+interface InitOptions {
+    /** Project root to install into. @default process.cwd() */
+    cwd?: string;
+    /**
+     * Absolute path to a built cli.js. When set, the config launches that file
+     * via `node` instead of `npx @latest` — for local development only.
+     */
+    cliPath?: string;
+    /** Where the skill source lives. @default resolved from __dirname (../skill). */
+    skillSrcDir?: string;
+    log?: (msg: string) => void;
+}
+declare function runInit(opts?: InitOptions): void;
+
 /**
  * The generic core: tools that work for ANY Buoy tool exposing a sync adapter,
  * with zero tool-specific knowledge. Tool packs add ergonomic wrappers on top.
@@ -133,6 +165,86 @@ declare function registerGenericTools(server: McpServer, sync: SyncClient): void
  */
 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
+ * AsyncStorage. Reuses the storage adapter's existing async.* 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. */
@@ -376,4 +488,4 @@ declare const DASHBOARD_NAME = "Dashboard";
 /** Target token meaning "every connected device". */
 declare const ALL_DEVICES = "All";
 
-export { ALL_DEVICES, BROKER_PORT, BROKER_URL, type BrokerMode, DASHBOARD_NAME, DEFAULT_ACTION_TIMEOUT_MS, DEFAULT_SNAPSHOT_TIMEOUT_MS, type DeviceInfo, SyncClient, type SyncClientOptions, buildAutomationConfig, compareReportStats, createMcpServer, estimateBatchMs, formatRankingMarkdown, rankBatchFromIndex, registerGenericTools, registerPerfMonitorTools };
+export { ALL_DEVICES, BROKER_PORT, BROKER_URL, type BrokerMode, DASHBOARD_NAME, DEFAULT_ACTION_TIMEOUT_MS, DEFAULT_SNAPSHOT_TIMEOUT_MS, type DeviceInfo, type InitOptions, PACKAGE_NAME, SyncClient, type SyncClientOptions, VERSION, buildAutomationConfig, compareReportStats, createMcpServer, estimateBatchMs, formatRankingMarkdown, getUpdateNotice, rankBatchFromIndex, registerConsoleTools, registerEventsTools, registerGenericTools, registerJotaiTools, registerPerfMonitorTools, registerReactQueryTools, registerReduxTools, registerRoutesTools, registerScreenshotTools, registerStorageTools, registerZustandTools, runInit };