@buoy-gg/mcp 4.0.1

package/dist/index.d.ts

@@ -0,0 +1,379 @@
+import { ToolCapability } from '@buoy-gg/sync-broker';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+interface SyncClientOptions {
+    /** Broker URL to connect to. @default http://localhost:42831 */
+    url?: string;
+    /** Broker port to probe/spawn on. @default 42831 */
+    port?: number;
+    /**
+     * If no broker is already running on the port, spawn one in-process so the
+     * MCP server works standalone (no desktop app needed). @default true
+     */
+    autoSpawnBroker?: boolean;
+    /** Default per-action timeout. @default 15000 */
+    actionTimeoutMs?: number;
+    /** Optional logger — writes to stderr by default (stdout is the MCP channel). */
+    log?: (msg: string) => void;
+}
+/** A device the broker knows about, merged with its advertised tools. */
+interface DeviceInfo {
+    deviceId: string;
+    deviceName: string;
+    platform?: string;
+    isConnected: boolean;
+    /** Whether the connected app reported an active Buoy Pro license. */
+    isPro: boolean;
+    tools: ToolCapability[];
+}
+/** How the client obtained its broker connection. */
+type BrokerMode = "connected" | "spawned";
+/**
+ * A headless "Dashboard" client of the Buoy sync broker — the same role the
+ * desktop app plays, but driven programmatically by the MCP server. Implements
+ * connect-or-spawn: connects to a running broker (e.g. the desktop app) if one
+ * is up, otherwise hosts its own in-process so it works standalone.
+ */
+declare class SyncClient {
+    private socket;
+    private broker;
+    private readonly url;
+    private readonly port;
+    private readonly actionTimeoutMs;
+    private readonly log;
+    /** Latest capabilities announce per deviceId. */
+    private capabilities;
+    /** Latest device list from the broker's `all-devices-update`. */
+    private devices;
+    /** Latest snapshot payload per `${deviceId}::${toolId}`. */
+    private snapshots;
+    /** Tools we've asked the broker to keep streaming, as `${deviceId}::${toolId}`. */
+    private watching;
+    /** In-flight actions awaiting a result, keyed by requestId. */
+    private pendingActions;
+    /** Callbacks waiting for the next snapshot of `${deviceId}::${toolId}`. */
+    private snapshotWaiters;
+    constructor(opts?: SyncClientOptions);
+    private readonly autoSpawn;
+    /** Connect to a running broker, or spawn one in-process, then handshake. */
+    start(): Promise<BrokerMode>;
+    private connectSocket;
+    /** Disconnect and tear down a spawned broker, if any. */
+    stop(): Promise<void>;
+    /** All devices the broker knows about, merged with their advertised tools. */
+    listDevices(): DeviceInfo[];
+    /** Connected devices only. */
+    connectedDevices(): DeviceInfo[];
+    /** Actions advertised for a tool, with the devices offering it. */
+    toolActions(toolId: string): {
+        deviceId: string;
+        deviceName: string;
+        actions: string[];
+    }[];
+    /**
+     * Resolve a concrete target deviceId. If `deviceId` is given it's used as-is.
+     * Otherwise, if exactly one device is connected, that one is chosen; if none
+     * or many, an informative error is thrown (callers can pass "All" explicitly).
+     */
+    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.
+     *
+     * `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.
+     */
+    requireProDevice(deviceId?: string): string;
+    private ensureWatching;
+    /** Stop streaming a tool (releases the device-side backpressure). */
+    unwatch(toolId: string, targetDeviceId: string): void;
+    /** Last snapshot received for a tool/device, if any. */
+    cachedSnapshot(toolId: string, deviceId: string): unknown;
+    /**
+     * Get a tool's current state. Starts watching (so the device begins emitting),
+     * explicitly requests state, and resolves with the next snapshot. Falls back
+     * to the last cached snapshot if the request times out.
+     */
+    getSnapshot(toolId: string, deviceId?: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<{
+        deviceId: string;
+        payload: unknown;
+    }>;
+    private waitForSnapshot;
+    /**
+     * Invoke a remote action on a device and await its result. Pass deviceId to
+     * target one device, or "All" to broadcast (resolves with the first responder).
+     */
+    callAction(toolId: string, action: string, params?: unknown, deviceId?: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<unknown>;
+}
+
+/**
+ * Build the Buoy MCP server and register all tools against a connected
+ * {@link SyncClient}. Tool packs (perf-monitor, etc.) are layered on top of the
+ * generic core here.
+ */
+declare function createMcpServer(sync: SyncClient): McpServer;
+
+/**
+ * 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.
+ */
+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;
+
+/** One row in an automation batch (MCP-friendly input; `id` added internally). */
+interface PerfCaseInput {
+    /** Display name; becomes the saved report's metadata.name. */
+    name: string;
+    /** Query params applied to the route for this case (e.g. { renderer: "v2" }). */
+    params?: Record<string, string>;
+    /** Optional per-case route override; falls back to the batch targetRoute. */
+    route?: string;
+}
+/** Full config sent to the device's `startAutomation` action. */
+interface AutomationConfig {
+    targetRoute: string;
+    bounceRoute: string;
+    perCaseDurationMs: number;
+    settleMs: number;
+    navTimeoutMs: number;
+    cases: {
+        id: string;
+        name: string;
+        params: Record<string, string>;
+        route?: string;
+    }[];
+    reloadBetweenCases?: boolean;
+    reloadStrategy?: "auto" | "dev-settings" | "expo-updates";
+    postReloadSettleMs?: number;
+    runsPerCase?: number;
+    coolDownMs?: number;
+    discardWarmupRuns?: number;
+    shuffleCases?: boolean;
+}
+/** A lightweight saved-recording summary (the device's index entry). */
+interface IndexEntry {
+    id: string;
+    createdAt: number;
+    name: string;
+    route?: string;
+    durationMs?: number;
+    sampleCount?: number;
+    jsFpsAvg?: number;
+    uiFpsAvg?: number;
+    cpuAvg?: number;
+    memMaxMb?: number;
+    jsJankFrames?: number;
+    uiJankFrames?: number;
+    deviceMaxRefreshRate?: number;
+    source?: "manual" | "batch";
+    batchId?: string;
+    batchIndex?: number;
+    batchFailureReason?: string;
+    params?: Record<string, string>;
+    caseId?: string;
+    runIndex?: number;
+    isMedianRun?: boolean;
+}
+/** Per-metric min/max/avg/p95 channel. */
+interface AggregateChannel {
+    min: number;
+    max: number;
+    avg: number;
+    p95: number;
+}
+/** Full report stats (from loadReport) — used by compare_reports. */
+interface BenchmarkReportStats {
+    sampleCount: number;
+    durationMs: number;
+    jsFps: AggregateChannel;
+    uiFps: AggregateChannel;
+    cpuUsage: AggregateChannel;
+    memoryUsage: AggregateChannel;
+    jsJankFrames: number;
+    uiJankFrames: number;
+    deviceMaxRefreshRate: number;
+}
+
+/**
+ * Pure helpers for the perf-monitor pack: build an AutomationConfig from
+ * MCP-friendly input, estimate batch duration, and rank a finished batch's
+ * results into a winner + comparison table. No network/sync — unit-testable.
+ */
+
+interface BuildConfigInput {
+    targetRoute: string;
+    bounceRoute?: string;
+    cases: PerfCaseInput[];
+    runsPerCase?: number;
+    perCaseDurationMs?: number;
+    settleMs?: number;
+    coolDownMs?: number;
+    navTimeoutMs?: number;
+    discardWarmupRuns?: number;
+    shuffleCases?: boolean;
+    reloadBetweenCases?: boolean;
+}
+/** The settings subset a driver inherits from the device's saved config. */
+type BenchmarkSettings = Partial<Pick<AutomationConfig, "perCaseDurationMs" | "settleMs" | "navTimeoutMs" | "runsPerCase" | "coolDownMs" | "discardWarmupRuns" | "shuffleCases" | "reloadBetweenCases">>;
+/**
+ * Build + validate the AutomationConfig the device expects. Throws on bad input.
+ *
+ * `base` is the device's saved benchmark settings — caller args override it,
+ * and it overrides the hardcoded fallback. So a run respects the profile the
+ * user tuned in the app unless the caller explicitly overrides a field.
+ */
+declare function buildAutomationConfig(input: BuildConfigInput, base?: BenchmarkSettings): {
+    config: AutomationConfig;
+    warnings: string[];
+};
+/** Rough wall-clock estimate for a batch, in ms. */
+declare function estimateBatchMs(config: AutomationConfig): number;
+interface RankRow {
+    batchIndex: number;
+    caseName: string;
+    params: Record<string, string>;
+    runs: number;
+    failed: boolean;
+    failureReason?: string;
+    uiFps: number | null;
+    jsFps: number | null;
+    cpu: number | null;
+    memMb: number | null;
+    jsJank: number | null;
+    uiJank: number | null;
+    deviceMaxRefreshRate: number | null;
+    /** Delta vs the baseline (first case) — positive = better/more fps. */
+    deltaUiFps: number | null;
+    deltaJsFps: number | null;
+    /** At-risk axes for this case (e.g. "UI thread drops frames", "CPU near cap"). */
+    flags: string[];
+}
+interface BatchRanking {
+    batchId: string;
+    baselineName: string | null;
+    deviceMaxRefreshRate: number | null;
+    rows: RankRow[];
+    /** The single best case per metric — so no one number masks the others. */
+    leaders: {
+        uiFps?: string;
+        jsFps?: string;
+        lowestCpu?: string;
+        lowestMem?: string;
+        fewestJank?: string;
+    };
+    /** Cases with an at-risk axis (esp. UI thread) — never a silent winner. */
+    flagged: {
+        caseName: string;
+        flags: string[];
+    }[];
+    /** Cases that cap nothing, best-first — the safe candidates to favor. */
+    balanced: string[];
+}
+/**
+ * Rank a finished batch from its index entries. Picks the median run per case,
+ * computes per-metric leaders + at-risk flags, and surfaces the "balanced"
+ * cases (those that cap no axis). Deliberately does NOT crown a single winner:
+ * a cheap run that drops UI frames is worse than a pricier one that holds them,
+ * so the model/user must weigh the trade-offs from the full picture.
+ */
+declare function rankBatchFromIndex(index: IndexEntry[], batchId: string, casesOrder?: {
+    name: string;
+}[], failures?: {
+    index: number;
+    reason: string;
+}[]): BatchRanking;
+/** Render a batch ranking as a trade-off-aware report (no single false winner). */
+declare function formatRankingMarkdown(ranking: BatchRanking): string;
+/** Side-by-side comparison of two full report stats. */
+declare function compareReportStats(a: {
+    name: string;
+    stats: BenchmarkReportStats;
+}, b: {
+    name: string;
+    stats: BenchmarkReportStats;
+}): {
+    a: string;
+    b: string;
+    uiFps: {
+        a: {
+            avg: number;
+            p95: number;
+        };
+        b: {
+            avg: number;
+            p95: number;
+        };
+        deltaAvg: number;
+    };
+    jsFps: {
+        a: {
+            avg: number;
+            p95: number;
+        };
+        b: {
+            avg: number;
+            p95: number;
+        };
+        deltaAvg: number;
+    };
+    cpuUsage: {
+        a: {
+            avg: number;
+            p95: number;
+        };
+        b: {
+            avg: number;
+            p95: number;
+        };
+        deltaAvg: number;
+    };
+    memoryUsage: {
+        a: {
+            avg: number;
+            p95: number;
+        };
+        b: {
+            avg: number;
+            p95: number;
+        };
+        deltaAvg: number;
+    };
+    jsJankFrames: {
+        a: number;
+        b: number;
+        delta: number;
+    };
+    uiJankFrames: {
+        a: number;
+        b: number;
+        delta: number;
+    };
+};
+
+/** Default broker port (shared with the desktop app + sync-broker). */
+declare const BROKER_PORT = 42831;
+/** Default broker URL the MCP server connects to as a "Dashboard" client. */
+declare const BROKER_URL = "http://localhost:42831";
+/** How long to wait for a device's action result before giving up. */
+declare const DEFAULT_ACTION_TIMEOUT_MS = 15000;
+/** How long to wait for a fresh snapshot after requesting tool state. */
+declare const DEFAULT_SNAPSHOT_TIMEOUT_MS = 5000;
+/** The exact handshake name the broker uses to recognize a dashboard client. */
+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 };