@nudge-ui/mcp 0.1.2 → 0.2.0

package/README.md

@@ -1,5 +1,9 @@
 # `@nudge-ui/mcp`
 
+> **Early alpha:** This integration is still under heavy testing. Expect
+> breaking changes, incomplete host compatibility, and other rough edges. Do
+> not rely on it for production workflows yet.
+
 `@nudge-ui/mcp` connects a local Nudge UI inspector to an MCP-capable coding
 agent. It combines a standard MCP stdio server with a project-scoped loopback
 browser bridge. The browser does not speak MCP directly.
@@ -7,7 +11,7 @@ browser bridge. The browser does not speak MCP directly.
 ## Install
 
 ```sh
-pnpm add -D @nudge-ui/mcp
+pnpm add -D @nudge-ui/mcp@0.2.0
 ```
 
 ### Configure automatically
@@ -16,7 +20,7 @@ From the application project root, use [`add-mcp`](https://github.com/neon-solut
 
 ```sh
 npx add-mcp \
-  'npx -y @nudge-ui/mcp@latest --project-id my-app --origin http://localhost:5173 --workspace-root .' \
+  'npx -y @nudge-ui/mcp@0.2.0 --project-id my-app --origin http://localhost:5173 --workspace-root .' \
   --name nudge_ui
 ```
 
@@ -31,10 +35,10 @@ For standard Vite and Astro projects, `my-app` normally matches the project
 directory name. Next.js and standalone HTML projects use host-specific IDs, so
 retain the explicit ID from their integration configuration.
 
-The generated command uses the published `@nudge-ui/mcp` package through
-`npx`. Pin the package version instead of `@latest` when reproducible tool
-versions are required. After configuration, restart or reload the agent host
-so it refreshes its MCP tool catalog.
+The generated command pins the published `@nudge-ui/mcp@0.2.0` package through
+`npx` for reproducible tool versions. Update the version deliberately when
+upgrading the MCP integration. After configuration, restart or reload the
+agent host so it refreshes its MCP tool catalog.
 
 The package has no install-time project mutation. The manual configuration
 below remains useful when an agent host is not supported by `add-mcp` or when

package/dist/bridge.d.ts

@@ -1,5 +1,5 @@
 import { type Server } from "node:http";
-import type { AgentPromptRequest, AgentRequestOutcome, AgentStatusSnapshot, AgentStatusUpdate, CanvasCommandResult, PairingResponse } from "@nudge-ui/agent-protocol";
+import type { AgentPromptRequest, AgentRequestOutcome, AgentStatusSnapshot, AgentStatusUpdate, CanvasCommandResult, PairingResponse } from "./internal/agent-protocol.js";
 /** A clock port keeps command timeout tests deterministic. */
 export interface BridgeClock {
     now(): number;
@@ -61,15 +61,15 @@ export interface BrowserBridge {
     /** Revokes a browser pairing; no data is written to disk. */
     disconnectBrowser(token: string): void;
 }
-export type CanvasCommandInput = Omit<import("@nudge-ui/agent-protocol").ReadCanvasStateCommand, "commandId"> & {
+export type CanvasCommandInput = Omit<import("./internal/agent-protocol.js").ReadCanvasStateCommand, "commandId"> & {
     readonly commandId?: string;
-} | Omit<import("@nudge-ui/agent-protocol").PresentRoutesCommand, "commandId"> & {
+} | Omit<import("./internal/agent-protocol.js").PresentRoutesCommand, "commandId"> & {
     readonly commandId?: string;
-} | Omit<import("@nudge-ui/agent-protocol").FocusCanvasGroupCommand, "commandId"> & {
+} | Omit<import("./internal/agent-protocol.js").FocusCanvasGroupCommand, "commandId"> & {
     readonly commandId?: string;
-} | Omit<import("@nudge-ui/agent-protocol").FitCanvasCommand, "commandId"> & {
+} | Omit<import("./internal/agent-protocol.js").FitCanvasCommand, "commandId"> & {
     readonly commandId?: string;
-} | Omit<import("@nudge-ui/agent-protocol").RemoveCanvasGroupCommand, "commandId"> & {
+} | Omit<import("./internal/agent-protocol.js").RemoveCanvasGroupCommand, "commandId"> & {
     readonly commandId?: string;
 };
 /**

package/dist/bridge.js

@@ -1,6 +1,6 @@
 import { createServer, } from "node:http";
 import { randomBytes, randomUUID } from "node:crypto";
-import { AGENT_PROTOCOL_LIMITS, AGENT_PROTOCOL_VERSION, canonicalOrigin, isAgentStatusUpdate, isAllowedOrigin, isCanvasCommand, isCanvasGroup, isCanvasState, isSameOriginRoute, validateRoutes, } from "@nudge-ui/agent-protocol";
+import { AGENT_PROTOCOL_LIMITS, AGENT_PROTOCOL_VERSION, canonicalOrigin, isAgentStatusUpdate, isAllowedOrigin, isCanvasCommand, isCanvasGroup, isCanvasState, isSameOriginRoute, validateRoutes, } from "./internal/agent-protocol.js";
 import { BRIDGE_ENDPOINTS } from "./protocol.js";
 const LOOPBACK_HOSTS = new Set(["127.0.0.1", "::1", "localhost"]);
 const MAX_BODY_BYTES = 256 * 1024;

package/dist/cli.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { spawn } from "node:child_process";
 import { basename, resolve } from "node:path";
-import { defaultBridgePort } from "@nudge-ui/agent-protocol";
+import { defaultBridgePort } from "./internal/agent-protocol.js";
 import { createAgentCompanion } from "./server.js";
 const DEFAULT_PORT = 0;
 const DEFAULT_COMMAND_TIMEOUT_MS = 5_000;
@@ -62,6 +62,7 @@ export function parseCliArguments(argv = process.argv.slice(2), environment = pr
     const root = resolve(environment.NUDGE_UI_WORKSPACE_ROOT ?? environment.INIT_CWD ?? process.cwd());
     let projectId = environment.NUDGE_UI_PROJECT_ID ?? projectIdFor(root);
     let origin = environment.NUDGE_UI_ORIGIN;
+    // SAFETY: NUDGE_UI_BRIDGE_HOST is trusted operator config for a loopback-bound dev bridge; CliOptions["host"] is its declared address union.
     let host = (environment.NUDGE_UI_BRIDGE_HOST ?? "127.0.0.1");
     let port = environment.NUDGE_UI_BRIDGE_PORT === undefined
         ? DEFAULT_PORT

package/dist/cli.mjs

@@ -21578,6 +21578,9 @@ var StdioServerTransport = class {
   }
 };
 
+// src/server.ts
+import { createRequire } from "node:module";
+
 // src/bridge.ts
 import {
   createServer
@@ -22285,7 +22288,14 @@ function createLoopbackBridge(options) {
 
 // src/server.ts
 var MCP_SERVER_NAME = "nudge-ui";
-var MCP_SERVER_VERSION = "0.1.2";
+var MCP_SERVER_VERSION = readPackageVersion();
+function readPackageVersion() {
+  const metadata = createRequire(import.meta.url)("../package.json");
+  if (typeof metadata !== "object" || metadata === null || !("version" in metadata) || typeof metadata.version !== "string") {
+    throw new TypeError("@nudge-ui/mcp package metadata has no version.");
+  }
+  return metadata.version;
+}
 var MCP_SERVER_INSTRUCTIONS = [
   "Nudge UI is a local browser companion for one project workspace.",
   "Browser pairing requires the app origin to be configured explicitly with --origin or NUDGE_UI_ORIGIN; an unconfigured bridge accepts no HTTP pairing.",

package/dist/internal/agent-protocol.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Public, host-neutral contracts shared by the Nudge browser inspector and
+ * its local MCP companion.
+ *
+ * This module deliberately has no Node, browser, MCP SDK, or framework
+ * imports. Hosts can use the same validation and message shapes without
+ * pulling the companion into a browser bundle.
+ */
+export declare const AGENT_PROTOCOL_VERSION: 1;
+export declare const AGENT_PROTOCOL_LIMITS: {
+    readonly projectId: 256;
+    readonly workspaceRoot: 4096;
+    readonly origin: 2048;
+    readonly sessionToken: 256;
+    readonly requestId: 256;
+    readonly commandId: 256;
+    readonly prompt: 32000;
+    readonly groupId: 256;
+    readonly label: 160;
+    readonly routeUrl: 2048;
+    readonly routeTitle: 512;
+    readonly routeCount: 64;
+    readonly canvasCardCount: 128;
+};
+/**
+ * Returns the default project-specific loopback port used by the CLI.
+ *
+ * The value is deterministic so a browser can probe the companion without a
+ * port file, while the range stays high enough to avoid common dev servers.
+ * Callers may still override it with an explicit port when a collision occurs.
+ */
+export declare function defaultBridgePort(projectId: string): number;
+export type AgentProtocolVersion = typeof AGENT_PROTOCOL_VERSION;
+/** A project identity is the pairing boundary for one companion process. */
+export interface AgentProjectIdentity {
+    readonly projectId: string;
+    /** Omitted when a trusted host establishes the browser origin out of band. */
+    readonly origin?: string;
+    readonly workspaceRoot?: string;
+}
+/** A same-origin route that an agent asks the browser to add to Canvas. */
+export interface AgentRoute {
+    readonly url: string;
+    readonly title?: string;
+    /** A short user-facing name. When absent, the browser derives one. */
+    readonly label?: string;
+}
+/** The owner marker lets the browser remove only groups created by the agent. */
+export type CanvasGroupOwner = "agent" | "user";
+/** A browser-reported comparison group. */
+export interface CanvasGroup {
+    readonly id: string;
+    readonly label: string;
+    readonly owner: CanvasGroupOwner;
+    readonly routes: readonly AgentRoute[];
+}
+/** A compact, serialisable Canvas snapshot returned by the browser. */
+export interface CanvasState {
+    readonly mode: "inspect" | "canvas";
+    readonly groups: readonly CanvasGroup[];
+    readonly focusedGroupId?: string | null;
+    readonly focusedRouteUrl?: string | null;
+}
+export declare const CANVAS_COMMAND_TYPES: readonly ["read-state", "present-routes", "focus-group", "fit-all", "remove-group"];
+export type CanvasCommandType = (typeof CANVAS_COMMAND_TYPES)[number];
+export interface ReadCanvasStateCommand {
+    readonly type: "read-state";
+    readonly commandId: string;
+}
+export interface PresentRoutesCommand {
+    readonly type: "present-routes";
+    readonly commandId: string;
+    readonly groupId: string;
+    readonly label: string;
+    readonly routes: readonly AgentRoute[];
+}
+export interface FocusCanvasGroupCommand {
+    readonly type: "focus-group";
+    readonly commandId: string;
+    readonly groupId: string;
+}
+export interface FitCanvasCommand {
+    readonly type: "fit-all";
+    readonly commandId: string;
+}
+export interface RemoveCanvasGroupCommand {
+    readonly type: "remove-group";
+    readonly commandId: string;
+    readonly groupId: string;
+}
+/** Commands sent from the companion to the paired browser over SSE. */
+export type CanvasCommand = ReadCanvasStateCommand | PresentRoutesCommand | FocusCanvasGroupCommand | FitCanvasCommand | RemoveCanvasGroupCommand;
+export interface CanvasCommandError {
+    readonly code: string;
+    readonly message: string;
+}
+export interface CanvasCommandResult {
+    readonly commandId: string;
+    readonly ok: boolean;
+    readonly state?: CanvasState;
+    readonly group?: CanvasGroup;
+    readonly error?: CanvasCommandError;
+}
+/** A prompt is immutable after it is accepted by the browser bridge. */
+export interface AgentPromptRequest {
+    readonly requestId: string;
+    readonly projectId: string;
+    readonly prompt: string;
+    /** The browser's canonical change revision captured at dispatch time. */
+    readonly changeRevision?: number;
+}
+export type AgentRequestStatus = "working" | "completed" | "failed" | "interrupted";
+export interface AgentRequestOutcome {
+    readonly requestId: string;
+    readonly status: AgentRequestStatus;
+    readonly summary?: string;
+    readonly error?: string;
+}
+export type AgentConnectionState = "offline" | "listening" | "paired" | "working";
+export interface AgentStatusSnapshot {
+    readonly protocolVersion: AgentProtocolVersion;
+    readonly projectId: string;
+    readonly connection: AgentConnectionState;
+    readonly listenerActive: boolean;
+    readonly paired: boolean;
+    /** The last paired page, retained only for this process lifetime. */
+    readonly pageUrl?: string | null;
+    readonly request: (AgentPromptRequest & {
+        readonly status: AgentRequestStatus;
+        readonly summary?: string;
+        readonly error?: string;
+    }) | null;
+}
+export type BridgeEventType = "status" | "canvas-command" | "connected" | "disconnected";
+export interface BridgeStatusEvent {
+    readonly type: "status";
+    readonly status: AgentStatusSnapshot;
+}
+export interface BridgeConnectedEvent {
+    readonly type: "connected";
+    readonly status: AgentStatusSnapshot;
+}
+export interface BridgeDisconnectedEvent {
+    readonly type: "disconnected";
+    readonly reason?: string;
+}
+export interface BridgeCanvasCommandEvent {
+    readonly type: "canvas-command";
+    readonly command: CanvasCommand;
+}
+/** Payload delivered to a browser SSE connection. */
+export type BridgeEvent = BridgeStatusEvent | BridgeConnectedEvent | BridgeDisconnectedEvent | BridgeCanvasCommandEvent;
+export interface BridgeEnvelope {
+    readonly protocolVersion: AgentProtocolVersion;
+    readonly projectId: string;
+    readonly sessionToken: string;
+    readonly event: BridgeEvent;
+}
+export interface CanvasCommandAcknowledgement {
+    readonly commandId: string;
+    readonly ok: boolean;
+    readonly state?: CanvasState;
+    readonly group?: CanvasGroup;
+    readonly error?: CanvasCommandError;
+}
+export interface PairingRequest {
+    readonly projectId: string;
+    readonly origin: string;
+    /** The active page is retained only while this process is alive. */
+    readonly pageUrl?: string;
+}
+export interface PairingResponse {
+    readonly protocolVersion: AgentProtocolVersion;
+    readonly projectId: string;
+    readonly origin: string;
+    readonly sessionToken: string;
+    readonly pageUrl?: string;
+    readonly status: AgentStatusSnapshot;
+}
+export interface PromptDispatchRequest {
+    readonly projectId: string;
+    readonly sessionToken: string;
+    readonly prompt: string;
+    readonly changeRevision?: number;
+}
+export interface PromptDispatchResponse {
+    readonly request: AgentPromptRequest;
+    readonly status: AgentRequestStatus;
+}
+export interface StatusEventRequest {
+    readonly projectId: string;
+    readonly sessionToken: string;
+}
+export interface AgentStatusUpdate {
+    readonly requestId: string;
+    readonly status: AgentRequestStatus;
+    readonly summary?: string;
+    readonly error?: string;
+}
+export interface ProtocolErrorShape {
+    readonly code: string;
+    readonly message: string;
+}
+/**
+ * Returns a canonical origin or null. Credentials, paths, and fragments are
+ * rejected so the browser cannot broaden the pairing boundary accidentally.
+ */
+export declare function canonicalOrigin(value: unknown): string | null;
+/** Returns true only for exact, canonical HTTP(S) origins. */
+export declare function isCanonicalOrigin(value: unknown): value is string;
+/**
+ * Checks an origin against an explicit allow-list. An empty allow-list does
+ * not mean wildcard access; callers must choose an origin before pairing.
+ */
+export declare function isAllowedOrigin(value: unknown, allowedOrigins: readonly string[]): value is string;
+/**
+ * Validates an agent route and ensures it belongs to the paired origin.
+ * Fragments are retained because they are useful initial Canvas locations.
+ */
+export declare function isSameOriginRoute(value: unknown, origin: string): value is AgentRoute;
+/** Validates and normalises route values for a presentation command. */
+export declare function validateRoutes(value: unknown, origin: string): AgentRoute[];
+/** Validates the fields shared by every companion message. */
+export declare function isProtocolVersion(value: unknown): value is AgentProtocolVersion;
+export declare function isProjectIdentity(value: unknown): value is AgentProjectIdentity;
+export declare function isAgentPromptRequest(value: unknown): value is AgentPromptRequest;
+export declare function isAgentStatusUpdate(value: unknown): value is AgentStatusUpdate;
+export declare function isCanvasState(value: unknown): value is CanvasState;
+export declare function isCanvasGroup(value: unknown): value is CanvasGroup;
+export declare function isCanvasCommand(value: unknown): value is CanvasCommand;
+/** Creates a stable protocol error shape without exposing thrown values. */
+export declare function protocolError(code: string, message: string): ProtocolErrorShape;

package/dist/internal/agent-protocol.js

@@ -0,0 +1,237 @@
+/**
+ * Public, host-neutral contracts shared by the Nudge browser inspector and
+ * its local MCP companion.
+ *
+ * This module deliberately has no Node, browser, MCP SDK, or framework
+ * imports. Hosts can use the same validation and message shapes without
+ * pulling the companion into a browser bundle.
+ */
+export const AGENT_PROTOCOL_VERSION = 1;
+export const AGENT_PROTOCOL_LIMITS = {
+    projectId: 256,
+    workspaceRoot: 4096,
+    origin: 2048,
+    sessionToken: 256,
+    requestId: 256,
+    commandId: 256,
+    prompt: 32_000,
+    groupId: 256,
+    label: 160,
+    routeUrl: 2048,
+    routeTitle: 512,
+    routeCount: 64,
+    canvasCardCount: 128,
+};
+/**
+ * Returns the default project-specific loopback port used by the CLI.
+ *
+ * The value is deterministic so a browser can probe the companion without a
+ * port file, while the range stays high enough to avoid common dev servers.
+ * Callers may still override it with an explicit port when a collision occurs.
+ */
+export function defaultBridgePort(projectId) {
+    if (!nonEmptyString(projectId, AGENT_PROTOCOL_LIMITS.projectId)) {
+        throw new TypeError("projectId must be a bounded non-empty string");
+    }
+    let hash = 2_166_136_261;
+    for (let index = 0; index < projectId.length; index += 1) {
+        hash ^= projectId.charCodeAt(index);
+        hash = Math.imul(hash, 16_777_619);
+    }
+    return 30_000 + ((hash >>> 0) % 20_000);
+}
+export const CANVAS_COMMAND_TYPES = [
+    "read-state",
+    "present-routes",
+    "focus-group",
+    "fit-all",
+    "remove-group",
+];
+const ORIGIN_PROTOCOLS = new Set(["http:", "https:"]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasOnlyKeys(value, keys) {
+    const allowed = new Set(keys);
+    return Object.keys(value).every((key) => allowed.has(key));
+}
+function nonEmptyString(value, maximum) {
+    return typeof value === "string" && value.length > 0 && value.length <= maximum;
+}
+function optionalString(value, maximum) {
+    return value === undefined || (typeof value === "string" && value.length <= maximum);
+}
+function optionalRevision(value) {
+    return value === undefined || (typeof value === "number" && Number.isSafeInteger(value) && value >= 0);
+}
+/**
+ * Returns a canonical origin or null. Credentials, paths, and fragments are
+ * rejected so the browser cannot broaden the pairing boundary accidentally.
+ */
+export function canonicalOrigin(value) {
+    if (!nonEmptyString(value, AGENT_PROTOCOL_LIMITS.origin))
+        return null;
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        return null;
+    }
+    if (!ORIGIN_PROTOCOLS.has(parsed.protocol) || parsed.username || parsed.password)
+        return null;
+    if (parsed.pathname !== "/" || parsed.search || parsed.hash)
+        return null;
+    return parsed.origin;
+}
+/** Returns true only for exact, canonical HTTP(S) origins. */
+export function isCanonicalOrigin(value) {
+    return canonicalOrigin(value) === value;
+}
+/**
+ * Checks an origin against an explicit allow-list. An empty allow-list does
+ * not mean wildcard access; callers must choose an origin before pairing.
+ */
+export function isAllowedOrigin(value, allowedOrigins) {
+    const origin = canonicalOrigin(value);
+    if (!origin || allowedOrigins.length === 0)
+        return false;
+    return allowedOrigins.some((candidate) => canonicalOrigin(candidate) === origin);
+}
+/**
+ * Validates an agent route and ensures it belongs to the paired origin.
+ * Fragments are retained because they are useful initial Canvas locations.
+ */
+export function isSameOriginRoute(value, origin) {
+    if (!isRecord(value) || !hasOnlyKeys(value, ["url", "title", "label"]))
+        return false;
+    if (!nonEmptyString(value.url, AGENT_PROTOCOL_LIMITS.routeUrl))
+        return false;
+    if (!optionalString(value.title, AGENT_PROTOCOL_LIMITS.routeTitle))
+        return false;
+    if (!optionalString(value.label, AGENT_PROTOCOL_LIMITS.label))
+        return false;
+    const expectedOrigin = canonicalOrigin(origin);
+    if (!expectedOrigin)
+        return false;
+    let route;
+    try {
+        route = new URL(value.url, expectedOrigin);
+    }
+    catch {
+        return false;
+    }
+    if (route.origin !== expectedOrigin || !ORIGIN_PROTOCOLS.has(route.protocol))
+        return false;
+    return true;
+}
+/** Validates and normalises route values for a presentation command. */
+export function validateRoutes(value, origin) {
+    if (!Array.isArray(value) || value.length === 0 || value.length > AGENT_PROTOCOL_LIMITS.routeCount) {
+        throw new TypeError(`routes must contain between 1 and ${AGENT_PROTOCOL_LIMITS.routeCount} items`);
+    }
+    const expectedOrigin = canonicalOrigin(origin);
+    if (!expectedOrigin)
+        throw new TypeError("origin must be a canonical HTTP(S) origin");
+    return value.map((route, index) => {
+        if (!isSameOriginRoute(route, expectedOrigin)) {
+            throw new TypeError(`routes[${index}] must be a same-origin route`);
+        }
+        const input = route;
+        const parsed = new URL(input.url, expectedOrigin);
+        return {
+            url: parsed.href,
+            ...(input.title === undefined ? {} : { title: input.title }),
+            ...(input.label === undefined ? {} : { label: input.label }),
+        };
+    });
+}
+/** Validates the fields shared by every companion message. */
+export function isProtocolVersion(value) {
+    return value === AGENT_PROTOCOL_VERSION;
+}
+export function isProjectIdentity(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, ["projectId", "origin", "workspaceRoot"]))
+        return false;
+    return nonEmptyString(value.projectId, AGENT_PROTOCOL_LIMITS.projectId)
+        && (value.origin === undefined || isCanonicalOrigin(value.origin))
+        && optionalString(value.workspaceRoot, AGENT_PROTOCOL_LIMITS.workspaceRoot);
+}
+export function isAgentPromptRequest(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, ["requestId", "projectId", "prompt", "changeRevision"]))
+        return false;
+    return nonEmptyString(value.requestId, AGENT_PROTOCOL_LIMITS.requestId)
+        && nonEmptyString(value.projectId, AGENT_PROTOCOL_LIMITS.projectId)
+        && nonEmptyString(value.prompt, AGENT_PROTOCOL_LIMITS.prompt)
+        && optionalRevision(value.changeRevision);
+}
+export function isAgentStatusUpdate(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, ["requestId", "status", "summary", "error"]))
+        return false;
+    return nonEmptyString(value.requestId, AGENT_PROTOCOL_LIMITS.requestId)
+        && (value.status === "working" || value.status === "completed"
+            || value.status === "failed" || value.status === "interrupted")
+        && optionalString(value.summary, AGENT_PROTOCOL_LIMITS.prompt)
+        && optionalString(value.error, AGENT_PROTOCOL_LIMITS.prompt);
+}
+export function isCanvasState(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, ["mode", "groups", "focusedGroupId", "focusedRouteUrl"]))
+        return false;
+    if (value.mode !== "inspect" && value.mode !== "canvas")
+        return false;
+    if (!Array.isArray(value.groups) || value.groups.length > AGENT_PROTOCOL_LIMITS.canvasCardCount)
+        return false;
+    if (!(value.focusedGroupId === undefined || value.focusedGroupId === null
+        || nonEmptyString(value.focusedGroupId, AGENT_PROTOCOL_LIMITS.groupId)))
+        return false;
+    if (!(value.focusedRouteUrl === undefined || value.focusedRouteUrl === null
+        || nonEmptyString(value.focusedRouteUrl, AGENT_PROTOCOL_LIMITS.routeUrl)))
+        return false;
+    return value.groups.every(isCanvasGroup);
+}
+export function isCanvasGroup(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, ["id", "label", "owner", "routes"]))
+        return false;
+    return nonEmptyString(value.id, AGENT_PROTOCOL_LIMITS.groupId)
+        && nonEmptyString(value.label, AGENT_PROTOCOL_LIMITS.label)
+        && (value.owner === "agent" || value.owner === "user")
+        && Array.isArray(value.routes)
+        && value.routes.length <= AGENT_PROTOCOL_LIMITS.routeCount
+        && value.routes.every((route) => isRecord(route)
+            && nonEmptyString(route.url, AGENT_PROTOCOL_LIMITS.routeUrl)
+            && optionalString(route.title, AGENT_PROTOCOL_LIMITS.routeTitle)
+            && optionalString(route.label, AGENT_PROTOCOL_LIMITS.label));
+}
+export function isCanvasCommand(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, ["type", "commandId", "groupId", "label", "routes"]))
+        return false;
+    if (!nonEmptyString(value.commandId, AGENT_PROTOCOL_LIMITS.commandId))
+        return false;
+    switch (value.type) {
+        case "read-state":
+        case "fit-all":
+            return true;
+        case "focus-group":
+        case "remove-group":
+            return nonEmptyString(value.groupId, AGENT_PROTOCOL_LIMITS.groupId);
+        case "present-routes":
+            return nonEmptyString(value.groupId, AGENT_PROTOCOL_LIMITS.groupId)
+                && nonEmptyString(value.label, AGENT_PROTOCOL_LIMITS.label)
+                && Array.isArray(value.routes)
+                && value.routes.length > 0
+                && value.routes.length <= AGENT_PROTOCOL_LIMITS.routeCount
+                && value.routes.every((route) => isRecord(route)
+                    && nonEmptyString(route.url, AGENT_PROTOCOL_LIMITS.routeUrl)
+                    && optionalString(route.title, AGENT_PROTOCOL_LIMITS.routeTitle)
+                    && optionalString(route.label, AGENT_PROTOCOL_LIMITS.label));
+        default:
+            return false;
+    }
+}
+/** Creates a stable protocol error shape without exposing thrown values. */
+export function protocolError(code, message) {
+    if (!nonEmptyString(code, 128) || !nonEmptyString(message, AGENT_PROTOCOL_LIMITS.prompt)) {
+        throw new TypeError("Protocol errors require bounded code and message strings");
+    }
+    return { code, message };
+}

package/dist/protocol.d.ts

@@ -1,12 +1,12 @@
 /**
  * Companion-facing aliases and transport envelopes.
  *
- * The domain contracts live in `@nudge-ui/agent-protocol`; this module keeps
- * transport names discoverable for Node consumers while preserving a single
- * protocol vocabulary for browser and agent adapters.
+ * The domain contracts live in the private shared protocol module. This public
+ * subpath keeps transport names discoverable for Node consumers while
+ * preserving one protocol vocabulary for browser and agent adapters.
  */
-export { AGENT_PROTOCOL_LIMITS, AGENT_PROTOCOL_VERSION, CANVAS_COMMAND_TYPES, canonicalOrigin, defaultBridgePort, isAgentPromptRequest, isAgentStatusUpdate, isAllowedOrigin, isCanvasCommand, isCanvasGroup, isCanvasState, isCanonicalOrigin, isProjectIdentity, isSameOriginRoute, protocolError, validateRoutes, } from "@nudge-ui/agent-protocol";
-export type { AgentConnectionState, AgentProjectIdentity, AgentPromptRequest, AgentRequestOutcome, AgentRequestStatus, AgentRoute, AgentStatusSnapshot, AgentStatusUpdate, BridgeCanvasCommandEvent, BridgeConnectedEvent, BridgeDisconnectedEvent, BridgeEnvelope, BridgeEvent, BridgeEventType, BridgeStatusEvent, CanvasCommand, CanvasCommandAcknowledgement, CanvasCommandError, CanvasCommandResult, CanvasGroup, CanvasGroupOwner, CanvasState, FitCanvasCommand, FocusCanvasGroupCommand, PairingRequest, PairingResponse, PresentRoutesCommand, PromptDispatchRequest, PromptDispatchResponse, ReadCanvasStateCommand, RemoveCanvasGroupCommand, StatusEventRequest, } from "@nudge-ui/agent-protocol";
+export { AGENT_PROTOCOL_LIMITS, AGENT_PROTOCOL_VERSION, CANVAS_COMMAND_TYPES, canonicalOrigin, defaultBridgePort, isAgentPromptRequest, isAgentStatusUpdate, isAllowedOrigin, isCanvasCommand, isCanvasGroup, isCanvasState, isCanonicalOrigin, isProjectIdentity, isSameOriginRoute, protocolError, validateRoutes, } from "./internal/agent-protocol.js";
+export type { AgentConnectionState, AgentProjectIdentity, AgentPromptRequest, AgentRequestOutcome, AgentRequestStatus, AgentRoute, AgentStatusSnapshot, AgentStatusUpdate, BridgeCanvasCommandEvent, BridgeConnectedEvent, BridgeDisconnectedEvent, BridgeEnvelope, BridgeEvent, BridgeEventType, BridgeStatusEvent, CanvasCommand, CanvasCommandAcknowledgement, CanvasCommandError, CanvasCommandResult, CanvasGroup, CanvasGroupOwner, CanvasState, FitCanvasCommand, FocusCanvasGroupCommand, PairingRequest, PairingResponse, PresentRoutesCommand, PromptDispatchRequest, PromptDispatchResponse, ReadCanvasStateCommand, RemoveCanvasGroupCommand, StatusEventRequest, } from "./internal/agent-protocol.js";
 /** Stable endpoint names used by the loopback browser bridge. */
 export declare const BRIDGE_ENDPOINTS: {
     readonly health: "/health";

package/dist/protocol.js

@@ -1,11 +1,11 @@
 /**
  * Companion-facing aliases and transport envelopes.
  *
- * The domain contracts live in `@nudge-ui/agent-protocol`; this module keeps
- * transport names discoverable for Node consumers while preserving a single
- * protocol vocabulary for browser and agent adapters.
+ * The domain contracts live in the private shared protocol module. This public
+ * subpath keeps transport names discoverable for Node consumers while
+ * preserving one protocol vocabulary for browser and agent adapters.
  */
-export { AGENT_PROTOCOL_LIMITS, AGENT_PROTOCOL_VERSION, CANVAS_COMMAND_TYPES, canonicalOrigin, defaultBridgePort, isAgentPromptRequest, isAgentStatusUpdate, isAllowedOrigin, isCanvasCommand, isCanvasGroup, isCanvasState, isCanonicalOrigin, isProjectIdentity, isSameOriginRoute, protocolError, validateRoutes, } from "@nudge-ui/agent-protocol";
+export { AGENT_PROTOCOL_LIMITS, AGENT_PROTOCOL_VERSION, CANVAS_COMMAND_TYPES, canonicalOrigin, defaultBridgePort, isAgentPromptRequest, isAgentStatusUpdate, isAllowedOrigin, isCanvasCommand, isCanvasGroup, isCanvasState, isCanonicalOrigin, isProjectIdentity, isSameOriginRoute, protocolError, validateRoutes, } from "./internal/agent-protocol.js";
 /** Stable endpoint names used by the loopback browser bridge. */
 export const BRIDGE_ENDPOINTS = {
     health: "/health",

package/dist/server.d.ts

@@ -1,9 +1,9 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
-import type { AgentProjectIdentity } from "@nudge-ui/agent-protocol";
+import type { AgentProjectIdentity } from "./internal/agent-protocol.js";
 import { type BrowserBridge, type BrowserBridgeOptions, type BridgeAddress } from "./bridge.js";
 export declare const MCP_SERVER_NAME = "nudge-ui";
-export declare const MCP_SERVER_VERSION = "0.1.2";
+export declare const MCP_SERVER_VERSION: string;
 /** Instructions are sent through MCP initialization for every host. */
 export declare const MCP_SERVER_INSTRUCTIONS: string;
 export interface AgentCompanionOptions extends BrowserBridgeOptions {

package/dist/server.js

@@ -1,10 +1,21 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createRequire } from "node:module";
 import { z } from "zod";
-import { validateRoutes } from "@nudge-ui/agent-protocol";
+import { validateRoutes } from "./internal/agent-protocol.js";
 import { createLoopbackBridge, } from "./bridge.js";
 export const MCP_SERVER_NAME = "nudge-ui";
-export const MCP_SERVER_VERSION = "0.1.2";
+export const MCP_SERVER_VERSION = readPackageVersion();
+function readPackageVersion() {
+    const metadata = createRequire(import.meta.url)("../package.json");
+    if (typeof metadata !== "object"
+        || metadata === null
+        || !("version" in metadata)
+        || typeof metadata.version !== "string") {
+        throw new TypeError("@nudge-ui/mcp package metadata has no version.");
+    }
+    return metadata.version;
+}
 /** Instructions are sent through MCP initialization for every host. */
 export const MCP_SERVER_INSTRUCTIONS = [
     "Nudge UI is a local browser companion for one project workspace.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nudge-ui/mcp",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Optional local MCP companion for pairing Nudge UI with coding agents.",
   "license": "MIT",
   "repository": {
@@ -46,14 +46,14 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "zod": "^3.25.76",
-    "@nudge-ui/agent-protocol": "0.1.2"
+    "zod": "^3.25.76"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",
     "esbuild": "^0.21.5",
     "typescript": "^5.9.3",
-    "vitest": "^2.1.9"
+    "vitest": "^2.1.9",
+    "@nudge-ui/agent-protocol": "0.2.0"
   },
   "engines": {
     "node": ">=20"
@@ -62,7 +62,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "node ../../scripts/build-package.mjs && node scripts/build.mjs",
+    "build": "node ../../scripts/build-package.mjs && node ../../scripts/vendor-agent-protocol.mjs && node scripts/build.mjs",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test:unit": "vitest run",
     "test:unit:watch": "vitest"