@nudge-ui/mcp 0.2.0 → 0.2.2

package/README.md

@@ -1,62 +1,154 @@
 # `@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.
+> **Early alpha:** This integration can make breaking changes while host
+> support and the setup workflow stabilize.
 
-`@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.
+`@nudge-ui/mcp` connects a local Nudge inspector to an MCP-capable coding
+agent. The development server owns the browser bridge. The agent host starts a
+small stdio adapter installed independently of any checkout. Each tool call supplies
+the checkout or application being edited.
 
-## Install
+## Configure an agent
+
+Run `npx nudge-ui agent setup` from an application, or
+`npm create nudge-ui@latest -- --agent-only`. Setup installs:
+
+- A project-local `@nudge-ui/mcp` dependency for the development server's bridge.
+- A versioned adapter under `~/.nudge-ui/adapters/<initializer-version>/` using npm.
+
+Setup registers the adapter globally with an absolute Node executable and adapter
+entry path. The entry contains no application path, origin, or port. npm must be
+available even when the application uses pnpm, Yarn, or Bun. The adapter version
+comes from the initializer; the bridge version follows the application package.
+
+Before changing agent settings, setup starts a fresh MCP client, completes
+initialization, and checks that the tools support connection-time selection.
+This verifies the executable, not whether an already running agent host has
+reloaded it. Fully quit and restart the host after migration.
+
+When testing a local `@nudge-ui/mcp` tarball, pass the same artifact to setup:
 
 ```sh
-pnpm add -D @nudge-ui/mcp@0.2.0
+npx nudge-ui agent setup --mcp-package /absolute/path/to/nudge-ui-mcp.tgz
 ```
 
-### Configure automatically
+This installs the local build for both the application's project bridge and the
+reusable adapter. Without the override, the adapter is intentionally resolved
+from the published registry and may not contain local changes.
+
+Setup backs up existing `nudge_ui` settings, replaces the global entry, and removes
+the current project's overriding entry. Other agent settings are preserved.
+Run setup once in other projects that still have legacy overrides; setup does
+not scan unrelated repositories. New checkouts need the bridge dependency and
+framework integration, but no project-specific MCP registration.
 
-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:
+To configure a host manually, use the Node executable and managed adapter entry
+printed by setup, with no `--workspace-root` argument. A bare `nudge-mcp` command
+also works if that executable is installed independently and available on the
+host's PATH.
+
+Run diagnostics from an application:
 
 ```sh
-npx add-mcp \
-  'npx -y @nudge-ui/mcp@0.2.0 --project-id my-app --origin http://localhost:5173 --workspace-root .' \
-  --name nudge_ui
+npx nudge-ui agent doctor
 ```
 
-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.
+The doctor distinguishes descriptor, reachable, matching-unreachable, invalid,
+and incompatible-protocol counts. Failed loopback probes do not prove that a
+bridge never registered: a sandbox can block local networking. Retry diagnostics
+outside the command sandbox when appropriate. Credentials are never printed.
+The output includes the resolved registry path and the workspace/application
+scope, even when the registry has no sessions.
+The reusable MCP adapter exposes the same diagnostics through `nudge_diagnose`.
+
+## Project integration
+
+Framework adapters start and stop the project bridge with the development
+server:
 
-`--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.
+```ts
+import { startProjectBridge } from "@nudge-ui/mcp/project";
 
-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.
+const runtime = await startProjectBridge({
+  workspaceRoot: process.cwd(),
+  appRoot: process.cwd(),
+  projectId: "my-app",
+  origin: "http://localhost:5173",
+  allowedOrigins: ["http://127.0.0.1:5173"],
+});
 
-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.
+// Give browser code only these non-secret values.
+console.log(runtime.browser.bridgeUrl, runtime.browser.projectId);
 
-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.
+await runtime.close();
+```
+
+`origin` must be the actual canonical development origin after the framework
+chooses its port. `workspaceRoot` defaults to the Git worktree root when one is
+available and otherwise defaults to `appRoot`. `appRoot` distinguishes several
+applications running from one monorepo.
+
+Each live bridge registers a random session ID, canonical workspace and app
+paths, optional Git common directory and branch metadata, origin, and loopback
+endpoint. The descriptor is mode `0600` inside a mode `0700` registry. It also
+contains a private random credential used only between the bridge and adapter.
+
+The adapter lists live local sessions through `nudge_list_sessions`. Supply
+`workspaceRoot` on every tool call, including status, Canvas, and release. Use
+the absolute checkout root or application directory being edited. The adapter
+does not infer a task's project from its process working directory.
+
+For example, the first discovery call is:
+
+```json
+{
+  "name": "nudge_list_sessions",
+  "arguments": {
+    "workspaceRoot": "/path/to/nudge-examples"
+  }
+}
+```
 
-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.
+Selection is automatic only when the supplied scope contains one live session.
+If several applications match, also supply the chosen `sessionId` and repeat
+both arguments on subsequent calls. A workspace mismatch never falls back to
+the only session elsewhere. Independent selections can run concurrently within
+one MCP connection. Each selection stays bound to its application through
+restarts; old requests are not replayed. An explicit stale session ID requires
+rediscovery before listening again.
 
-## Run manually
+Existing configurations with `--workspace-root` remain restricted to that scope
+until migrated. Branch names and shared Git metadata never authorize selecting
+another checkout.
+
+## OpenCode configuration
+
+The setup integration delegates OpenCode file handling to `add-mcp`. It
+preserves the documented V2 shape, `mcp.servers.<name>`, and also preserves the
+legacy `mcp.<name>` shape when that is what an existing file uses. Setup tests
+both layouts and migrates only the Nudge entry.
+
+OpenCode's CLI does not currently provide a Nudge-specific removal command. To
+remove only Nudge's registration, use `add-mcp` and select the scope explicitly:
+
+```sh
+npx add-mcp remove nudge_ui --global --agent opencode --yes
+npx add-mcp remove nudge_ui --agent opencode --yes
+```
+
+Run the first command for the global registration and the second for a project
+override. These commands leave other MCP servers in place.
+
+One adapter owns a selected project session until it closes. Other adapters
+receive a claimed-session error instead of taking browser work. A heartbeat
+allows the bridge to recover a claim after an adapter process is killed. Call
+`nudge_release` when the user stops listening so another adapter can claim the
+session without restarting the MCP host.
+
+## Legacy coupled mode
+
+Passing `--origin` retains the previous behavior in which the MCP process also
+owns its browser bridge:
 
 ```sh
 pnpm exec nudge-mcp \
@@ -65,17 +157,10 @@ pnpm exec nudge-mcp \
   --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.
+This deprecated mode prints a warning and remains available for custom
+integrations during migration. New framework integrations should use the
+project-owned bridge.
 
-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.
+The agent calls `nudge_listen`, applies the delivered prompt, reports the
+result through `nudge_report_status`, and listens again. Canvas tools remain
+limited to routes from the paired application origin and agent-owned groups.

package/dist/adapterRouting.d.ts

@@ -0,0 +1,16 @@
+import { DiscoveredProjectRouter } from "./discovery.js";
+export interface ProjectTarget {
+    readonly workspaceRoot?: string;
+    readonly sessionId?: string;
+}
+/** Keeps each explicit project selection independent for the lifetime of an MCP connection. */
+export declare class AdapterRouting {
+    readonly registryRoot: string;
+    private closing;
+    private readonly selections;
+    private readonly applications;
+    constructor(registryRoot?: string);
+    target({ workspaceRoot, sessionId }: ProjectTarget): Promise<DiscoveredProjectRouter>;
+    private select;
+    close(): Promise<void>;
+}

package/dist/adapterRouting.js

@@ -0,0 +1,59 @@
+import { realpath } from "node:fs/promises";
+import { isAbsolute } from "node:path";
+import { DiscoveredProjectRouter } from "./discovery.js";
+import { defaultSessionRegistryRoot, resolveWorkspaceRoot } from "./project.js";
+import { readLiveProjectSessions } from "./sessionRegistry.js";
+import { selectProjectSession } from "./sessionSelection.js";
+/** Keeps each explicit project selection independent for the lifetime of an MCP connection. */
+export class AdapterRouting {
+    registryRoot;
+    closing = false;
+    selections = new Map();
+    applications = new Map();
+    constructor(registryRoot = defaultSessionRegistryRoot()) {
+        this.registryRoot = registryRoot;
+    }
+    async target({ workspaceRoot, sessionId }) {
+        if (!workspaceRoot || !isAbsolute(workspaceRoot)) {
+            throw new Error("Supply workspaceRoot as the absolute path of the checkout or application you are editing.");
+        }
+        const applicationRoot = await realpath(workspaceRoot);
+        if (this.closing)
+            throw new Error("The MCP adapter is closing.");
+        const key = JSON.stringify([applicationRoot, sessionId]);
+        let selection = this.selections.get(key);
+        if (!selection) {
+            selection = this.select(applicationRoot, sessionId);
+            this.selections.set(key, selection);
+            void selection.catch(() => {
+                if (this.selections.get(key) === selection)
+                    this.selections.delete(key);
+            });
+        }
+        return await selection;
+    }
+    async select(applicationRoot, sessionId) {
+        const workspaceRoot = await resolveWorkspaceRoot(applicationRoot);
+        const live = await readLiveProjectSessions(this.registryRoot);
+        if (this.closing)
+            throw new Error("The MCP adapter is closing.");
+        const selected = selectProjectSession(live.map(({ descriptor }) => descriptor), {
+            workspaceRoot, applicationRoot, requestedSessionId: sessionId,
+        });
+        const key = selected.sessionId;
+        let router = this.applications.get(key)
+            ?? [...this.applications.values()].find((candidate) => candidate.selectedSessionId === selected.sessionId);
+        if (!router) {
+            router = DiscoveredProjectRouter.forSession(selected, this.registryRoot);
+            this.applications.set(key, router);
+        }
+        return router;
+    }
+    async close() {
+        this.closing = true;
+        await Promise.allSettled(this.selections.values());
+        await Promise.all([...this.applications.values()].map((router) => router.close()));
+        this.selections.clear();
+        this.applications.clear();
+    }
+}

package/dist/bridge.d.ts

@@ -1,5 +1,5 @@
 import { type Server } from "node:http";
-import type { AgentPromptRequest, AgentRequestOutcome, AgentStatusSnapshot, AgentStatusUpdate, CanvasCommandResult, PairingResponse } from "./internal/agent-protocol.js";
+import type { AgentDeliveredPrompt, AgentRequestOutcome, AgentStatusSnapshot, AgentStatusUpdate, CanvasCommandResult, PairingResponse } from "./internal/agent-protocol.js";
 /** A clock port keeps command timeout tests deterministic. */
 export interface BridgeClock {
     now(): number;
@@ -22,6 +22,8 @@ export interface BrowserBridgeOptions {
     readonly tokenFactory?: () => string;
     /** Test seam; production defaults to random UUIDs. */
     readonly idFactory?: () => string;
+    /** Private credential for a separately running MCP adapter. */
+    readonly agentControlToken?: 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.
@@ -49,7 +51,7 @@ export interface BrowserBridge {
     start(): Promise<BridgeAddress>;
     close(): Promise<void>;
     /** Blocks until a paired browser dispatches a prompt. */
-    waitForPrompt(signal?: AbortSignal): Promise<AgentPromptRequest>;
+    waitForPrompt(signal?: AbortSignal): Promise<AgentDeliveredPrompt>;
     /** 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. */