@nudge-ui/mcp 0.1.0

package/README.md

@@ -0,0 +1,77 @@
+# `@nudge-ui/mcp`
+
+`@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.
+
+## Install
+
+```sh
+pnpm add -D @nudge-ui/mcp
+```
+
+### Configure automatically
+
+From the application project root, use [`add-mcp`](https://github.com/neon-solutions/add-mcp) to detect supported coding agents and write each host's native configuration format:
+
+```sh
+npx add-mcp \
+  'npx -y @nudge-ui/mcp@latest --project-id my-app --origin http://localhost:5173 --workspace-root .' \
+  --name nudge_ui
+```
+
+The command prompts for detected project agents. Use `-a codex` (or another
+supported agent name) to target one host, or `-y` to skip the prompt and use
+the detected project agents. Keep this project-scoped; do not use `-g` unless
+the configuration intentionally targets one fixed project.
+
+`--origin` must exactly match the development application's browser origin.
+The `--project-id` value must match the ID used by the Nudge host integration.
+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 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
+you need an explicit custom command.
+
+After adding or changing the host configuration, restart or reload the MCP
+server, or start a fresh agent task. Open **Connect MCP** from the inspector's
+prompt menu for setup instructions, connection status, and explicit pairing.
+You can pair a page before the agent starts listening. Ask the agent to call
+`nudge_listen` and keep it active to enable sending. **Copy prompt** remains
+available while the agent is idle; prompts are not queued.
+
+For Codex desktop, confirm that `nudge_ui` appears in the current task after
+the MCP restart. For Codex CLI, `codex mcp list` verifies the project entry.
+Restart a long-running OpenCode service after adding or changing its MCP
+configuration so it refreshes its tool catalog.
+
+## Run manually
+
+```sh
+pnpm exec nudge-mcp \
+  --project-id my-app \
+  --origin http://localhost:5173 \
+  --workspace-root /path/to/my-app
+```
+
+Pass the exact application origin with `--origin` (or
+`NUDGE_UI_ORIGIN`). The bridge rejects browser origins that are not explicitly
+configured; it never trusts the first origin that connects. The bridge chooses
+a deterministic loopback port from the project ID so the inspector can find
+it without a port file. Use `--port 0` for an ephemeral test port.
+
+For integrations that establish the browser origin out of band, trusted host
+code can use the `pairBrowser` API as an explicit manual approval path. An
+unconfigured bridge does not accept HTTP pairing requests.
+
+The agent should call `nudge_listen` immediately, apply the delivered prompt
+through its normal source-editing workflow, call `nudge_report_status`, and
+listen again. Canvas tools are limited to same-origin routes and agent-owned
+groups.

package/dist/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Charles Smart
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/bridge.d.ts

@@ -0,0 +1,79 @@
+import { type Server } from "node:http";
+import type { AgentPromptRequest, AgentRequestOutcome, AgentStatusSnapshot, AgentStatusUpdate, CanvasCommandResult, PairingResponse } from "@nudge-ui/agent-protocol";
+/** A clock port keeps command timeout tests deterministic. */
+export interface BridgeClock {
+    now(): number;
+    setTimeout(callback: () => void, delayMs: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+export interface BrowserBridgeOptions {
+    /** Stable project identity used to scope every browser message. */
+    readonly projectId: string;
+    /** Canonical app origin that browser routes must use. */
+    readonly origin?: string;
+    /** Explicit browser origins accepted by the loopback HTTP server. */
+    readonly allowedOrigins?: readonly string[];
+    readonly host?: "127.0.0.1" | "::1" | "localhost";
+    /** Use port 0 in tests or when several projects run concurrently. */
+    readonly port?: number;
+    readonly commandTimeoutMs?: number;
+    readonly clock?: BridgeClock;
+    /** Test seam; production defaults to cryptographically random tokens. */
+    readonly tokenFactory?: () => string;
+    /** Test seam; production defaults to random UUIDs. */
+    readonly idFactory?: () => string;
+    /**
+     * Best-effort hook used by the CLI to reopen the last paired page when an
+     * agent rearms listening but no browser controller stream is attached.
+     */
+    readonly onControllerUnavailable?: (pageUrl: string) => Promise<void> | void;
+}
+export interface BridgeAddress {
+    readonly host: string;
+    readonly port: number;
+    readonly url: string;
+}
+export type BridgeLifecycle = "created" | "listening" | "closed";
+export interface BrowserBridge {
+    readonly httpServer: Server;
+    readonly projectId: string;
+    readonly origin: string | null;
+    /** The configured origin, or the explicitly approved browser origin. */
+    readonly effectiveOrigin: string | null;
+    readonly lifecycle: BridgeLifecycle;
+    readonly address: BridgeAddress | null;
+    readonly sessionToken: string | null;
+    readonly lastPageUrl: string | null;
+    /** Current companion/browser state, safe to expose to the browser. */
+    getStatus(): AgentStatusSnapshot;
+    start(): Promise<BridgeAddress>;
+    close(): Promise<void>;
+    /** Blocks until a paired browser dispatches a prompt. */
+    waitForPrompt(signal?: AbortSignal): Promise<AgentPromptRequest>;
+    /** Marks the agent-side listener as stopped without ending the project. */
+    cancelListener(reason?: string): void;
+    /** Reports the terminal result for the currently running browser request. */
+    updateRequestStatus(update: AgentStatusUpdate | AgentRequestOutcome): void;
+    /** Sends a Canvas command to the browser and waits for one bounded ack. */
+    dispatchCanvasCommand(command: CanvasCommandInput): Promise<CanvasCommandResult>;
+    /** Returns the currently paired browser token to the host process only. */
+    pairBrowser(projectId: string, requestOrigin: string, pageUrl?: string): PairingResponse;
+    /** 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"> & {
+    readonly commandId?: string;
+} | Omit<import("@nudge-ui/agent-protocol").PresentRoutesCommand, "commandId"> & {
+    readonly commandId?: string;
+} | Omit<import("@nudge-ui/agent-protocol").FocusCanvasGroupCommand, "commandId"> & {
+    readonly commandId?: string;
+} | Omit<import("@nudge-ui/agent-protocol").FitCanvasCommand, "commandId"> & {
+    readonly commandId?: string;
+} | Omit<import("@nudge-ui/agent-protocol").RemoveCanvasGroupCommand, "commandId"> & {
+    readonly commandId?: string;
+};
+/**
+ * Creates the local browser bridge. It binds only to loopback and keeps every
+ * pairing, prompt, command, and acknowledgement in process memory.
+ */
+export declare function createLoopbackBridge(options: BrowserBridgeOptions): BrowserBridge;