@nudge-ui/mcp 0.2.1 → 0.2.2

package/README.md

@@ -5,33 +5,61 @@
 
 `@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 that discovers live bridges in the current checkout or Git
-worktree.
+small stdio adapter installed independently of any checkout. Each tool call supplies
+the checkout or application being edited.
 
 ## Configure an agent
 
-The Nudge initializer can install the dependency and configure supported agent
-hosts. A manual project-scoped configuration uses this command:
+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
-node ./node_modules/@nudge-ui/mcp/dist/cli.mjs --workspace-root /path/to/project
+npx nudge-ui agent setup --mcp-package /absolute/path/to/nudge-ui-mcp.tgz
 ```
 
-The adapter does not need an origin, port, project ID, or branch. A running
-development integration registers those values in a private per-user runtime
-directory. Restart the agent host after changing its MCP configuration, then
-ask it to **Listen to Nudge**. Agent configuration contains absolute checkout
-and application paths, so rerun agent setup in each clone or Git worktree that
-you intend the agent to edit.
+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.
 
-Run diagnostics without starting MCP stdio framing:
+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
-node ./node_modules/@nudge-ui/mcp/dist/cli.mjs doctor --workspace-root /path/to/project
+npx nudge-ui agent doctor
 ```
 
-The doctor reports live and exact-workspace session counts. It never prints
-control credentials.
+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
 
@@ -65,13 +93,51 @@ 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 all live local sessions through `nudge_list_sessions`, but it
-can listen only to sessions whose canonical workspace and configured
-application path match. An adapter configured at the worktree root can select
-any app in that worktree explicitly. A branch name or shared Git common
-directory never causes fallback to another worktree. When several apps run in
-one workspace, pass the chosen `sessionId` to `nudge_listen`. The adapter keeps
-that app selection across a bridge restart and does not replay old requests.
+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"
+  }
+}
+```
+
+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.
+
+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
@@ -91,8 +157,9 @@ pnpm exec nudge-mcp \
   --workspace-root /path/to/my-app
 ```
 
-This mode remains available for custom integrations during migration. New
-framework integrations should use the project-owned bridge.
+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 calls `nudge_listen`, applies the delivered prompt, reports the
 result through `nudge_report_status`, and listens again. Canvas tools remain

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.js

@@ -310,7 +310,7 @@ export function createLoopbackBridge(options) {
             pageUrl: lastPageUrl,
         }, incomingOrigin);
     };
-    const handlePair = async (request, response) => {
+    const readPairRequest = async (request) => {
         if (!loopbackAddress(request.socket.remoteAddress)) {
             throw new BridgeRequestError(403, "loopback_only", "The browser bridge accepts loopback connections only.");
         }
@@ -332,6 +332,10 @@ export function createLoopbackBridge(options) {
             }
             requestedPageUrl = new URL(body.pageUrl, requestedOrigin).href;
         }
+        return { body, incomingOrigin, requestedPageUrl };
+    };
+    const handlePair = async (request, response) => {
+        const { body, incomingOrigin, requestedPageUrl } = await readPairRequest(request);
         if (sessionToken) {
             if (body.sessionToken !== sessionToken) {
                 throw new BridgeRequestError(409, "already_paired", "A browser is already paired with this project.");
@@ -367,6 +371,15 @@ export function createLoopbackBridge(options) {
         sendJson(response, 200, result, incomingOrigin);
         broadcastStatus();
     };
+    const handleTakeover = async (request, response) => {
+        const { incomingOrigin, requestedPageUrl } = await readPairRequest(request);
+        // Takeover is intentionally separate from normal pairing. The caller has
+        // made an explicit UI choice to revoke the existing browser session.
+        if (sessionToken)
+            disconnectBrowser(sessionToken);
+        const pairing = pairBrowser(options.projectId, incomingOrigin, requestedPageUrl);
+        sendJson(response, 200, pairing, incomingOrigin);
+    };
     const handleEvents = (request, response, url) => {
         parseProjectId(url.searchParams.get("projectId"), options.projectId);
         const incomingOrigin = requireBrowserRequest(request, url);
@@ -661,6 +674,10 @@ export function createLoopbackBridge(options) {
                 await handlePair(request, response);
                 return;
             }
+            if (request.method === "POST" && url.pathname === BRIDGE_ENDPOINTS.takeover) {
+                await handleTakeover(request, response);
+                return;
+            }
             if (request.method === "GET" && url.pathname === BRIDGE_ENDPOINTS.events) {
                 handleEvents(request, response, url);
                 return;

package/dist/cli.d.ts

@@ -3,7 +3,7 @@ export interface CliOptions {
     readonly command: "serve" | "doctor";
     readonly projectId: string;
     readonly origin?: string;
-    readonly workspaceRoot: string;
+    readonly workspaceRoot?: string;
     readonly host: "127.0.0.1" | "::1" | "localhost";
     readonly port: number;
     readonly commandTimeoutMs: number;
@@ -32,6 +32,6 @@ export interface PageLaunchDependencies {
 export declare function openPairedPage(pageUrl: string, dependencies?: PageLaunchDependencies): Promise<boolean>;
 /** Parses only project-scoped, host-neutral CLI options. */
 export declare function parseCliArguments(argv?: readonly string[], environment?: CliEnvironment): CliOptions;
-export declare const CLI_USAGE = "Usage: nudge-mcp [doctor] [options]\n\nStarts a standard MCP stdio adapter. It discovers the bridge owned by the\nrunning project unless --origin selects the legacy coupled mode.\n\nOptions:\n  --project-id <id>             Stable project pairing identity\n  --origin <origin>             Exact app origin required for browser pairing\n  --workspace-root <path>       Project root supplied to the agent\n  --host <loopback>             127.0.0.1, ::1, or localhost\n  --port <port>                 Bridge port; default is deterministic per project, 0 is ephemeral\n  --command-timeout-ms <ms>     Canvas acknowledgement timeout\n  --help                        Show this message\n";
+export declare const CLI_USAGE = "Usage: nudge-mcp [doctor] [options]\n\nStarts a standard MCP stdio adapter. It discovers the bridge owned by the\nrunning project unless --origin selects the legacy coupled mode.\n\nOptions:\n  --project-id <id>             Stable project pairing identity\n  --origin <origin>             Exact app origin required for browser pairing\n  --workspace-root <path>       Optional legacy project restriction; omitted for reusable adapters\n  --host <loopback>             127.0.0.1, ::1, or localhost\n  --port <port>                 Bridge port; default is deterministic per project, 0 is ephemeral\n  --command-timeout-ms <ms>     Canvas acknowledgement timeout\n  --help                        Show this message\n";
 /** Runs the CLI until the stdio MCP connection closes or the process stops. */
 export declare function runCli(argv?: readonly string[], environment?: CliEnvironment): Promise<void>;

package/dist/cli.js

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { spawn } from "node:child_process";
 import { basename, resolve } from "node:path";
 import { defaultBridgePort } from "./internal/agent-protocol.js";
-import { discoverProjectSessions } from "./discovery.js";
+import { diagnoseProjectSessions, discoverProjectSessions } from "./discovery.js";
 import { createAgentCompanion, createDiscoveredAgentAdapter, } from "./server.js";
 const DEFAULT_PORT = 0;
 const DEFAULT_COMMAND_TIMEOUT_MS = 5_000;
@@ -73,7 +73,7 @@ export function parseCliArguments(argv = process.argv.slice(2), environment = pr
     let commandTimeoutMs = environment.NUDGE_UI_COMMAND_TIMEOUT_MS === undefined
         ? DEFAULT_COMMAND_TIMEOUT_MS
         : parseInteger(environment.NUDGE_UI_COMMAND_TIMEOUT_MS, "NUDGE_UI_COMMAND_TIMEOUT_MS", 60_000);
-    let workspaceRoot = root;
+    let workspaceRoot = environment.NUDGE_UI_WORKSPACE_ROOT === undefined ? undefined : root;
     let help = false;
     let explicitPort = environment.NUDGE_UI_BRIDGE_PORT !== undefined;
     for (let index = 0; index < argumentsToParse.length; index += 1) {
@@ -133,7 +133,7 @@ running project unless --origin selects the legacy coupled mode.
 Options:
   --project-id <id>             Stable project pairing identity
   --origin <origin>             Exact app origin required for browser pairing
-  --workspace-root <path>       Project root supplied to the agent
+  --workspace-root <path>       Optional legacy project restriction; omitted for reusable adapters
   --host <loopback>             127.0.0.1, ::1, or localhost
   --port <port>                 Bridge port; default is deterministic per project, 0 is ephemeral
   --command-timeout-ms <ms>     Canvas acknowledgement timeout
@@ -148,13 +148,19 @@ export async function runCli(argv = process.argv.slice(2), environment = process
     }
     if (options.command === "doctor") {
         const sessions = await discoverProjectSessions(options.workspaceRoot);
-        const matches = sessions.filter((session) => session.matchesApplication);
+        const matches = sessions.filter((session) => options.workspaceRoot === undefined || session.matchesApplication);
+        const diagnostics = await diagnoseProjectSessions(options.workspaceRoot);
         process.stdout.write([
-            `[nudge-ui] workspace: ${options.workspaceRoot}`,
+            `[nudge-ui] registry: ${diagnostics.registryRoot}`,
+            `[nudge-ui] workspace: ${diagnostics.workspaceRoot ?? "all projects"}`,
+            `[nudge-ui] application: ${diagnostics.applicationRoot ?? "all applications"}`,
+            `[nudge-ui] descriptors: ${diagnostics.descriptorCount}; invalid: ${diagnostics.invalidCount}; incompatible: ${diagnostics.incompatibleCount}`,
+            `[nudge-ui] matching unreachable descriptors: ${diagnostics.matchingUnreachableCount}`,
+            ...diagnostics.guidance.map((message) => `[nudge-ui] ${message}`),
             `[nudge-ui] live sessions: ${sessions.length}`,
             `[nudge-ui] matching sessions: ${matches.length}`,
             ...(matches.length === 0
-                ? ["[nudge-ui] no matching project bridge is running; start the development server to make Nudge available"]
+                ? ["[nudge-ui] no reachable compatible bridge matches; inspect the diagnostics above or start the development server"]
                 : matches.map((session) => {
                     const state = session.status.connection === "working"
                         ? "working"
@@ -195,8 +201,10 @@ export async function runCli(argv = process.argv.slice(2), environment = process
         }
         return;
     }
+    process.stderr.write("[nudge-ui] --origin uses deprecated coupled mode. Rerun agent setup to use project-owned bridges and avoid port collisions.\n");
     const companion = createAgentCompanion({
         ...options,
+        workspaceRoot: options.workspaceRoot ?? resolve(environment.INIT_CWD ?? process.cwd()),
         onControllerUnavailable: (pageUrl) => openPairedPage(pageUrl).then(() => undefined),
     });
     let stopping = false;