create-nudge-ui 0.2.0 → 0.2.2

package/README.md

@@ -1,7 +1,8 @@
 # `create-nudge-ui`
 
 `create-nudge-ui` detects an application's host framework, installs the
-corresponding Nudge UI adapter, and updates the host configuration.
+corresponding Nudge UI adapter, and updates the host configuration. The guided
+setup can also connect a coding agent to Nudge.
 
 Run the initializer from the application root:
 
@@ -13,6 +14,16 @@ The initializer supports Next.js, Astro, Vite with React, and static HTML. Host
 frameworks take precedence over their underlying tools, so an Astro project
 with React islands receives `nudge-ui/astro`, not `nudge-ui/vite`.
 
+In an interactive terminal, the initializer asks whether to connect a coding
+agent. It detects installed agents, installs the matching `@nudge-ui/mcp`
+version in the project, and installs a versioned reusable adapter under
+`~/.nudge-ui/adapters/`. The adapter is independent of the application and
+does not contain a project path, so different Git worktrees can use the same
+global MCP registration. Existing project-scoped Nudge entries are backed up
+and removed when the host supports that migration.
+
+Fully restart the agent host, then ask it to “listen to Nudge.”
+
 Use an explicit framework when automatic detection is ambiguous:
 
 ```sh
@@ -22,3 +33,35 @@ npm create nudge-ui@latest -- --framework astro
 Use `--dry-run` to print the package installation and configuration change
 without modifying the project. Run `npm create nudge-ui@latest -- --help` for
 the complete command reference.
+
+For scripts, select the MCP behavior explicitly:
+
+```sh
+# Configure detected agents without prompts.
+npm create nudge-ui@latest -- --mcp --yes
+
+# Configure one or more supported add-mcp agent IDs.
+npm create nudge-ui@latest -- --mcp --agent codex --agent cursor --yes
+
+# Skip agent setup.
+npm create nudge-ui@latest -- --no-mcp
+```
+
+Use agent-only mode to add or repair the integration without changing the host
+framework configuration:
+
+```sh
+npm create nudge-ui@latest -- --agent-only --agent codex --yes
+```
+
+For local MCP package testing, pass a tarball with `--mcp-package`. Setup uses
+that artifact for both the project bridge and reusable adapter:
+
+```sh
+npx nudge-ui agent setup --mcp-package /absolute/path/to/nudge-ui-mcp.tgz
+```
+
+Agent configuration is best-effort. If an agent is not supported or its native
+configuration cannot be updated, the initializer prints the complete stdio
+configuration to add to that agent's project settings. Other MCP servers and
+agent settings are preserved on every run.

package/dist/agent-setup.d.ts

@@ -0,0 +1,39 @@
+import { type AgentType, type InstallResult, type McpServerConfig } from "add-mcp";
+import { type InstallCommand } from "./installer.js";
+import type { PackageManager } from "./types.js";
+export declare const nudgeServerName = "nudge_ui";
+export interface AgentSetupPlan {
+    readonly projectRoot: string;
+    readonly packageSpecifier: string;
+    readonly installCommand: InstallCommand;
+    readonly adapterRoot: string;
+    readonly adapterInstallCommand: InstallCommand;
+    readonly serverConfig: McpServerConfig;
+    readonly serverEntry: string;
+}
+export interface AgentInstallOutcome {
+    readonly agent: string;
+    readonly displayName: string;
+    readonly result?: InstallResult;
+    readonly unsupported: boolean;
+    readonly migrationError?: string;
+    readonly backups?: readonly string[];
+}
+/** Plans the project bridge dependency and an independent, versioned adapter installation. */
+export declare function planAgentSetup(projectRoot: string, packageManager: PackageManager, nudgeUiVersion?: string, adapterDirectory?: string, mcpPackageSpecifier?: string): AgentSetupPlan;
+/** Checks that a node_modules based install produced the configured executable. */
+export declare function isAgentServerAvailable(plan: AgentSetupPlan): boolean;
+/** Returns agents that support a reusable stdio MCP configuration. */
+export declare function projectAgentTypes(): AgentType[];
+/** Detects installed or already configured agents. */
+export declare function detectProjectAgentCandidates(projectRoot: string): Promise<AgentType[]>;
+/** Registers the reusable adapter and removes the current project's overriding entry. */
+export declare function configureProjectAgents(plan: AgentSetupPlan, selectedAgents: readonly string[]): Promise<AgentInstallOutcome[]>;
+/** Formats a complete stdio entry for agents that add-mcp cannot configure. */
+export declare function manualAgentConfiguration(plan: AgentSetupPlan): string;
+export declare function projectAgentChoices(detected: readonly AgentType[]): Array<{
+    readonly id: AgentType;
+    readonly label: string;
+    readonly detected: boolean;
+}>;
+export declare function initializerVersion(): string;

package/dist/agent-setup.js

@@ -0,0 +1,124 @@
+import { randomUUID } from "node:crypto";
+import { copyFileSync, existsSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { agents, detectGlobalAgents, detectProjectAgents, getAgentTypes, upsertServer, listInstalledServers, removeServer, } from "add-mcp";
+import { installCommand } from "./installer.js";
+export const nudgeServerName = "nudge_ui";
+/** Plans the project bridge dependency and an independent, versioned adapter installation. */
+export function planAgentSetup(projectRoot, packageManager, nudgeUiVersion, adapterDirectory = join(homedir(), ".nudge-ui", "adapters"), mcpPackageSpecifier) {
+    const canonicalRoot = realpathSync.native(projectRoot);
+    const packageSpecifier = mcpPackageSpecifier ?? `@nudge-ui/mcp@${nudgeUiVersion ?? installedNudgeUiVersion(canonicalRoot) ?? initializerVersion()}`;
+    const adapterPackageSpecifier = mcpPackageSpecifier ?? `@nudge-ui/mcp@${initializerVersion()}`;
+    const adapterRoot = join(adapterDirectory, initializerVersion());
+    const serverEntry = join(adapterRoot, "node_modules", "@nudge-ui", "mcp", "dist", "cli.mjs");
+    const serverConfig = { command: process.execPath, args: [serverEntry] };
+    return {
+        projectRoot: canonicalRoot,
+        packageSpecifier,
+        installCommand: installCommand(packageManager, packageSpecifier),
+        serverConfig,
+        adapterRoot,
+        adapterInstallCommand: {
+            executable: "npm",
+            args: ["install", "--prefix", adapterRoot, "--no-save", "--package-lock=false", adapterPackageSpecifier],
+        },
+        serverEntry,
+    };
+}
+/** Checks that a node_modules based install produced the configured executable. */
+export function isAgentServerAvailable(plan) {
+    return existsSync(plan.serverEntry);
+}
+/** Returns agents that support a reusable stdio MCP configuration. */
+export function projectAgentTypes() {
+    return getAgentTypes().filter((agent) => agents[agent].supportedTransports.includes("stdio"));
+}
+/** Detects installed or already configured agents. */
+export async function detectProjectAgentCandidates(projectRoot) {
+    const supported = new Set(projectAgentTypes());
+    const detected = [
+        ...detectProjectAgents(projectRoot),
+        ...await detectGlobalAgents(),
+    ].filter((agent) => supported.has(agent));
+    return [...new Set(detected)];
+}
+/** Registers the reusable adapter and removes the current project's overriding entry. */
+export async function configureProjectAgents(plan, selectedAgents) {
+    const supported = new Set(projectAgentTypes());
+    const outcomes = [];
+    for (const agent of new Set(selectedAgents)) {
+        if (!supported.has(agent)) {
+            outcomes.push({ agent, displayName: agent, unsupported: true });
+            continue;
+        }
+        const agentType = agent;
+        const global = await listInstalledServers({ agents: [agentType], global: true, cwd: plan.projectRoot });
+        const local = agents[agentType].localConfigPath
+            ? await listInstalledServers({ agents: [agentType], global: false, cwd: plan.projectRoot })
+            : [];
+        const configurations = [...global, ...local];
+        const invalid = configurations.find((configuration) => configuration.error);
+        if (invalid) {
+            outcomes.push({ agent, displayName: agents[agentType].displayName, unsupported: false,
+                result: { success: false, path: invalid.configPath, error: invalid.error } });
+            continue;
+        }
+        const backups = [];
+        for (const configuration of configurations) {
+            if (!configuration.servers.some((server) => server.serverName === nudgeServerName))
+                continue;
+            const backup = `${configuration.configPath}.nudge-backup-${randomUUID()}`;
+            copyFileSync(configuration.configPath, backup);
+            backups.push(backup);
+        }
+        const result = upsertServer(agentType, nudgeServerName, plan.serverConfig, { local: false, cwd: plan.projectRoot });
+        const removal = result.success && agents[agentType].localConfigPath
+            ? removeServer(agentType, nudgeServerName, { local: true, cwd: plan.projectRoot })
+            : undefined;
+        outcomes.push({
+            agent, displayName: agents[agentType].displayName, result, unsupported: false, backups,
+            ...(removal && !removal.success ? { migrationError: removal.error ?? "Could not remove the project override." } : {}),
+        });
+    }
+    return outcomes;
+}
+/** Formats a complete stdio entry for agents that add-mcp cannot configure. */
+export function manualAgentConfiguration(plan) {
+    return JSON.stringify({
+        mcpServers: {
+            [nudgeServerName]: plan.serverConfig,
+        },
+    }, null, 2);
+}
+export function projectAgentChoices(detected) {
+    const detectedSet = new Set(detected);
+    return projectAgentTypes()
+        .sort((left, right) => {
+        const detectionOrder = Number(detectedSet.has(right)) - Number(detectedSet.has(left));
+        return detectionOrder || agents[left].displayName.localeCompare(agents[right].displayName);
+    })
+        .map((id) => ({ id, label: agents[id].displayName, detected: detectedSet.has(id) }));
+}
+export function initializerVersion() {
+    const packageJsonUrl = new URL("../package.json", import.meta.url);
+    const value = JSON.parse(readFileSync(packageJsonUrl, "utf8"));
+    if (!isPackageMetadata(value))
+        throw new TypeError("create-nudge-ui package metadata has no version.");
+    return value.version;
+}
+function installedNudgeUiVersion(projectRoot) {
+    const manifestPath = join(projectRoot, "node_modules", "nudge-ui", "package.json");
+    try {
+        const value = JSON.parse(readFileSync(manifestPath, "utf8"));
+        return isPackageMetadata(value) ? value.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isPackageMetadata(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    return typeof value.version === "string";
+}

package/dist/agent-verification.d.ts

@@ -0,0 +1,3 @@
+import type { McpServerConfig } from "add-mcp";
+/** Verifies the configured executable, initialization, and tools without claiming a project. */
+export declare function verifyAgentServer(config: McpServerConfig): Promise<void>;

package/dist/agent-verification.js

@@ -0,0 +1,21 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+/** Verifies the configured executable, initialization, and tools without claiming a project. */
+export async function verifyAgentServer(config) {
+    if (!config.command)
+        throw new Error("The MCP adapter has no executable.");
+    const client = new Client({ name: "nudge-setup", version: "1.0.0" });
+    const transport = new StdioClientTransport({ command: config.command, args: config.args, stderr: "inherit" });
+    try {
+        await client.connect(transport, { timeout: 15_000 });
+        const { tools } = await client.listTools({}, { timeout: 15_000 });
+        const listen = tools.find((tool) => tool.name === "nudge_listen");
+        if (!listen?.inputSchema.required?.includes("workspaceRoot") || !tools.some((tool) => tool.name === "nudge_list_sessions")) {
+            throw new Error("The installed adapter does not support connection-time project selection. Upgrade @nudge-ui/mcp.");
+        }
+    }
+    finally {
+        await transport.close();
+        await client.close();
+    }
+}

package/dist/arguments.d.ts

@@ -2,9 +2,14 @@ import { type Framework, type PackageManager } from "./types.js";
 export interface CliOptions {
     readonly framework?: Framework;
     readonly packageManager?: PackageManager;
+    readonly agentOnly: boolean;
+    readonly agents: readonly string[];
+    readonly mcpPackageSpecifier?: string;
+    readonly mcp?: boolean;
+    readonly yes: boolean;
     readonly dryRun: boolean;
     readonly help: boolean;
 }
 /** Parses the initializer command line. */
 export declare function parseArguments(args: readonly string[]): CliOptions;
-export declare const helpText = "Set up Nudge UI in the current project.\n\nUsage: npm create nudge-ui@latest -- [options]\n\nOptions:\n  --framework <nextjs|astro|vite-react|standalone>\n  --package-manager <pnpm|npm|yarn|bun>\n  --dry-run\n  -h, --help";
+export declare const helpText = "Set up Nudge UI in the current project.\n\nUsage: npm create nudge-ui@latest -- [options]\n\nOptions:\n  --framework <nextjs|astro|vite-react|standalone>\n  --package-manager <pnpm|npm|yarn|bun>\n  --mcp                         Configure the reusable Nudge MCP adapter\n  --no-mcp                      Skip coding-agent setup\n  --agent <id>                  Configure a supported agent (repeatable)\n  --mcp-package <path|package> Use this MCP package for the project and adapter\n  --agent-only                  Install or repair only the agent integration\n  -y, --yes                     Accept defaults without prompting\n  --dry-run\n  -h, --help";

package/dist/arguments.js

@@ -3,14 +3,40 @@ import { frameworks, packageManagers } from "./types.js";
 export function parseArguments(args) {
     let framework;
     let packageManager;
+    let agentOnly = false;
+    const agents = [];
+    let mcpPackageSpecifier;
+    let mcp;
+    let yes = false;
     let dryRun = false;
     let help = false;
     for (let index = 0; index < args.length; index += 1) {
         const argument = args[index];
         if (argument === "--")
             continue;
+        if (index === 0 && argument === "agent" && args[index + 1] === "setup") {
+            agentOnly = true;
+            index += 1;
+            continue;
+        }
         if (argument === "--dry-run")
             dryRun = true;
+        else if (argument === "--yes" || argument === "-y")
+            yes = true;
+        else if (argument === "--agent-only")
+            agentOnly = true;
+        else if (argument === "--mcp")
+            mcp = setMcpPreference(mcp, true);
+        else if (argument === "--no-mcp")
+            mcp = setMcpPreference(mcp, false);
+        else if (argument === "--agent")
+            agents.push(requiredValue(args, ++index, argument));
+        else if (argument.startsWith("--agent="))
+            agents.push(requiredValue([argument.slice("--agent=".length)], 0, "--agent"));
+        else if (argument === "--mcp-package")
+            mcpPackageSpecifier = requiredValue(args, ++index, argument);
+        else if (argument.startsWith("--mcp-package="))
+            mcpPackageSpecifier = requiredValue([argument.slice("--mcp-package=".length)], 0, "--mcp-package");
         else if (argument === "--help" || argument === "-h")
             help = true;
         else if (argument === "--framework")
@@ -26,7 +52,16 @@ export function parseArguments(args) {
         else
             throw new Error(`Unknown option: ${argument}`);
     }
-    return { framework, packageManager, dryRun, help };
+    if (agents.length > 0 && mcp === false)
+        throw new Error("--agent cannot be combined with --no-mcp.");
+    if (agentOnly && mcp === false)
+        throw new Error("--agent-only cannot be combined with --no-mcp.");
+    return { framework, packageManager, agentOnly, agents, mcpPackageSpecifier, mcp, yes, dryRun, help };
+}
+function setMcpPreference(current, next) {
+    if (current !== undefined && current !== next)
+        throw new Error("--mcp and --no-mcp cannot be combined.");
+    return next;
 }
 function requiredValue(args, index, option) {
     const value = args[index];
@@ -41,6 +76,12 @@ Usage: npm create nudge-ui@latest -- [options]
 Options:
   --framework <nextjs|astro|vite-react|standalone>
   --package-manager <pnpm|npm|yarn|bun>
+  --mcp                         Configure the reusable Nudge MCP adapter
+  --no-mcp                      Skip coding-agent setup
+  --agent <id>                  Configure a supported agent (repeatable)
+  --mcp-package <path|package> Use this MCP package for the project and adapter
+  --agent-only                  Install or repair only the agent integration
+  -y, --yes                     Accept defaults without prompting
   --dry-run
   -h, --help`;
 function parseFramework(value) {

package/dist/cli.d.ts

@@ -1,2 +1,14 @@
+import { type PackageManager } from "./types.js";
+export interface RunAgentSetupOptions {
+    readonly agents?: readonly string[];
+    /** Optional package specifier or tarball used for both bridge and adapter testing. */
+    readonly mcpPackageSpecifier?: string;
+    readonly dryRun?: boolean;
+    readonly nudgeUiVersion?: string;
+    readonly packageManager?: PackageManager;
+    readonly yes?: boolean;
+}
 /** Runs the Nudge UI project initializer. */
 export declare function runCli(args?: string[], projectRoot?: string): Promise<void>;
+/** Installs and configures the reusable MCP adapter and project bridge dependency. Safe to rerun for repairs. */
+export declare function runAgentSetup(projectRoot?: string, options?: RunAgentSetupOptions): Promise<void>;

package/dist/cli.js

@@ -1,12 +1,14 @@
-import { rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { verifyAgentServer } from "./agent-verification.js";
 import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
 import { basename, relative } from "node:path";
+import { configureProjectAgents, detectProjectAgentCandidates, initializerVersion, isAgentServerAvailable, manualAgentConfiguration, planAgentSetup, projectAgentChoices, } from "./agent-setup.js";
 import { parseArguments, helpText } from "./arguments.js";
 import { planConfiguration } from "./configuration.js";
 import { detectFrameworks, detectPackageManager, detectStaticRoot, frameworkDisplayName, readProjectManifest, } from "./detection.js";
 import { formatCommand, installCommand, installPackage } from "./installer.js";
-import { frameworks } from "./types.js";
+import { frameworks, } from "./types.js";
 /** Runs the Nudge UI project initializer. */
 export async function runCli(args = process.argv.slice(2), projectRoot = process.cwd()) {
     const options = parseArguments(args);
@@ -15,12 +17,22 @@ export async function runCli(args = process.argv.slice(2), projectRoot = process
         return;
     }
     const manifest = readProjectManifest(projectRoot);
+    const packageManager = options.packageManager ?? detectPackageManager(projectRoot, manifest);
+    if (options.agentOnly) {
+        await runAgentSetup(projectRoot, {
+            agents: options.agents,
+            mcpPackageSpecifier: options.mcpPackageSpecifier,
+            dryRun: options.dryRun,
+            packageManager,
+            yes: options.yes,
+        });
+        return;
+    }
     const detected = detectFrameworks(projectRoot, manifest);
     const framework = options.framework ?? await selectFramework(detected);
-    const packageManager = options.packageManager ?? detectPackageManager(projectRoot, manifest);
     // One package serves every host; the framework only decides which
     // subpath the generated configuration imports.
-    const command = installCommand(packageManager, "nudge-ui");
+    const command = installCommand(packageManager, `nudge-ui@${initializerVersion()}`);
     const change = planConfiguration(projectRoot, framework);
     const staticRoot = framework === "standalone" ? detectStaticRoot(projectRoot) : undefined;
     const serveDirectory = staticRoot ? relative(projectRoot, staticRoot) || "." : ".";
@@ -31,6 +43,16 @@ export async function runCli(args = process.argv.slice(2), projectRoot = process
             stdout.write(`Would ${change.created ? "create" : "update"}: ${change.path}\n`);
         if (framework === "standalone")
             stdout.write(`After installation, run: nudge-ui serve ${serveDirectory}\n`);
+        if (await shouldConfigureAgent(options.mcp, options.agents.length > 0, options.yes)) {
+            await runAgentSetup(projectRoot, {
+                agents: options.agents,
+                mcpPackageSpecifier: options.mcpPackageSpecifier,
+                dryRun: true,
+                nudgeUiVersion: initializerVersion(),
+                packageManager,
+                yes: options.yes,
+            });
+        }
         return;
     }
     if (change) {
@@ -51,6 +73,157 @@ export async function runCli(args = process.argv.slice(2), projectRoot = process
         stdout.write(`Run \`nudge-ui serve ${serveDirectory}\` to start the instrumented development server.\n`);
     }
     stdout.write(`Nudge UI is configured for ${frameworkDisplayName(framework)}.\n`);
+    if (await shouldConfigureAgent(options.mcp, options.agents.length > 0, options.yes)) {
+        await runAgentSetup(projectRoot, {
+            agents: options.agents,
+            mcpPackageSpecifier: options.mcpPackageSpecifier,
+            nudgeUiVersion: initializerVersion(),
+            packageManager,
+            yes: options.yes,
+        });
+    }
+}
+/** Installs and configures the reusable MCP adapter and project bridge dependency. Safe to rerun for repairs. */
+export async function runAgentSetup(projectRoot = process.cwd(), options = {}) {
+    const manifest = readProjectManifest(projectRoot);
+    const packageManager = options.packageManager ?? detectPackageManager(projectRoot, manifest);
+    const plan = planAgentSetup(projectRoot, packageManager, options.nudgeUiVersion, undefined, options.mcpPackageSpecifier);
+    const detected = await detectProjectAgentCandidates(plan.projectRoot);
+    const selected = options.agents && options.agents.length > 0
+        ? options.agents
+        : options.yes || !stdin.isTTY || !stdout.isTTY
+            ? detected
+            : await selectAgents(detected);
+    if (options.dryRun) {
+        stdout.write(`Would run: ${formatCommand(plan.installCommand)}\n`);
+        stdout.write(`Would run: ${formatCommand(plan.adapterInstallCommand)}\n`);
+        if (selected.length > 0) {
+            stdout.write(`Would configure global MCP and migrate this project override for: ${selected.join(", ")}\n`);
+        }
+        else {
+            stdout.write("No coding agent was detected. Use --agent <id> or add the configuration below manually.\n");
+            writeManualInstructions(plan);
+        }
+        return;
+    }
+    installPackage(plan.installCommand, plan.projectRoot);
+    try {
+        mkdirSync(plan.adapterRoot, { recursive: true });
+        installPackage(plan.adapterInstallCommand, plan.adapterRoot);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        stdout.write(`Could not install the reusable MCP adapter: ${message}\n`);
+        stdout.write(`Retry with: ${formatCommand(plan.adapterInstallCommand)}\n`);
+        stdout.write("The coding-agent configuration was not changed. After the adapter install succeeds, rerun with --agent-only.\n");
+        return;
+    }
+    if (!isAgentServerAvailable(plan)) {
+        stdout.write(`Installed ${plan.packageSpecifier}, but its reusable MCP executable was not found at ${plan.serverEntry}.\n`);
+        stdout.write(`Retry with: ${formatCommand(plan.adapterInstallCommand)}\n`);
+        stdout.write("The coding-agent configuration was not changed. Check the package-manager install output, then rerun with --agent-only.\n");
+        return;
+    }
+    try {
+        await verifyAgentServer(plan.serverConfig);
+        stdout.write("Verified MCP initialization and tool discovery with a fresh client.\n");
+    }
+    catch (error) {
+        stdout.write(`MCP verification failed: ${error instanceof Error ? error.message : String(error)}\n`);
+        stdout.write(`Retry with: ${formatCommand(plan.adapterInstallCommand)}\n`);
+        stdout.write("The coding-agent configuration was not changed. After repairing the adapter install, rerun with --agent-only.\n");
+        return;
+    }
+    if (selected.length === 0) {
+        stdout.write(`Installed ${plan.packageSpecifier}, but no coding agent was detected.\n`);
+        writeManualInstructions(plan);
+        return;
+    }
+    let outcomes;
+    try {
+        outcomes = await configureProjectAgents(plan, selected);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        stdout.write(`Could not update the coding-agent configuration: ${message}\n`);
+        writeManualInstructions(plan);
+        return;
+    }
+    let configured = 0;
+    for (const outcome of outcomes) {
+        if (outcome.unsupported) {
+            stdout.write(`${outcome.displayName} is not supported for automatic global setup.\n`);
+            continue;
+        }
+        for (const backup of outcome.backups ?? [])
+            stdout.write(`Saved previous MCP configuration: ${backup}\n`);
+        if (outcome.migrationError) {
+            stdout.write(`Global adapter configured, but project override migration failed: ${outcome.migrationError}\n`);
+            continue;
+        }
+        if (outcome.result?.success) {
+            configured += 1;
+            stdout.write(`Configured ${outcome.displayName}: ${outcome.result.path}\n`);
+            continue;
+        }
+        stdout.write(`Could not configure ${outcome.displayName}: ${outcome.result?.error ?? "unknown error"}\n`);
+    }
+    if (configured !== outcomes.length)
+        writeManualInstructions(plan);
+    if (configured > 0) {
+        stdout.write("Adapter configuration is ready. Fully restart the agent host to load it, then ask it to listen to Nudge in the current workspace. Existing overrides in other projects require one setup rerun there.\n");
+    }
+}
+async function shouldConfigureAgent(preference, hasExplicitAgents, yes) {
+    if (preference !== undefined)
+        return preference;
+    if (hasExplicitAgents || yes)
+        return true;
+    if (!stdin.isTTY || !stdout.isTTY)
+        return false;
+    return promptYesNo("Connect a coding agent?", true);
+}
+async function promptYesNo(message, defaultValue) {
+    const reader = createInterface({ input: stdin, output: stdout });
+    try {
+        const answer = (await reader.question(`${message} ${defaultValue ? "[Y/n]" : "[y/N]"} `)).trim().toLowerCase();
+        if (!answer)
+            return defaultValue;
+        return answer === "y" || answer === "yes";
+    }
+    finally {
+        reader.close();
+    }
+}
+async function selectAgents(detected) {
+    const choices = projectAgentChoices(detected);
+    stdout.write("Select coding agents (comma-separated):\n");
+    choices.forEach((choice, index) => {
+        stdout.write(`  ${index + 1}. ${choice.label}${choice.detected ? " (detected)" : ""}\n`);
+    });
+    const defaults = choices
+        .map((choice, index) => choice.detected ? String(index + 1) : undefined)
+        .filter((value) => value !== undefined)
+        .join(",");
+    const reader = createInterface({ input: stdin, output: stdout });
+    try {
+        while (true) {
+            const suffix = defaults ? ` [${defaults}]` : "";
+            const answer = (await reader.question(`Agents${suffix}: `)).trim() || defaults;
+            const indexes = answer.split(",").map((value) => Number(value.trim()) - 1);
+            if (indexes.length > 0 && indexes.every((index) => choices[index])) {
+                return [...new Set(indexes.map((index) => choices[index].id))];
+            }
+            stdout.write(`Enter one or more numbers from 1 to ${choices.length}.\n`);
+        }
+    }
+    finally {
+        reader.close();
+    }
+}
+function writeManualInstructions(plan) {
+    stdout.write("Add this global stdio server to your agent's MCP settings:\n");
+    stdout.write(`${manualAgentConfiguration(plan)}\n`);
 }
 async function selectFramework(detected) {
     if (detected.length === 1)

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export { parseArguments, helpText, type CliOptions } from "./arguments.js";
+export { configureProjectAgents, detectProjectAgentCandidates, initializerVersion, isAgentServerAvailable, manualAgentConfiguration, planAgentSetup, projectAgentChoices, projectAgentTypes, type AgentInstallOutcome, type AgentSetupPlan, } from "./agent-setup.js";
+export { runAgentSetup, type RunAgentSetupOptions } from "./cli.js";
 export { configureSource, planConfiguration } from "./configuration.js";
 export { detectFrameworks, detectPackageManager, detectStaticRoot, frameworkDisplayName, readProjectManifest, } from "./detection.js";
 export { formatCommand, installCommand, type InstallCommand } from "./installer.js";

package/dist/index.js

@@ -1,4 +1,6 @@
 export { parseArguments, helpText } from "./arguments.js";
+export { configureProjectAgents, detectProjectAgentCandidates, initializerVersion, isAgentServerAvailable, manualAgentConfiguration, planAgentSetup, projectAgentChoices, projectAgentTypes, } from "./agent-setup.js";
+export { runAgentSetup } from "./cli.js";
 export { configureSource, planConfiguration } from "./configuration.js";
 export { detectFrameworks, detectPackageManager, detectStaticRoot, frameworkDisplayName, readProjectManifest, } from "./detection.js";
 export { formatCommand, installCommand } from "./installer.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-nudge-ui",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Framework-detecting installer for Nudge UI.",
   "license": "MIT",
   "repository": {
@@ -29,7 +29,9 @@
     "create-nudge-ui": "./dist/entry.js"
   },
   "dependencies": {
-    "typescript": "^5.9.3"
+    "add-mcp": "^2.4.0",
+    "typescript": "^5.9.3",
+    "@modelcontextprotocol/sdk": "^1.30.0"
   },
   "devDependencies": {
     "vitest": "^2.1.9"