@paradigma-inc/flywheel 0.1.1 → 0.1.5

package/README.md

@@ -1,12 +1,6 @@
 # flywheel setup CLI
 
-This package provides a Context7-style setup workflow for Flywheel MCP.
-
-Design intentionally mirrors Context7's setup implementation patterns from:
-
-- `packages/cli/src/commands/setup.ts`
-- `packages/cli/src/setup/agents.ts`
-- `packages/cli/src/setup/mcp-writer.ts`
+This package provides setup and uninstall workflows for Flywheel MCP.
 
 ## Usage
 
@@ -15,21 +9,15 @@ npx @paradigma-inc/flywheel setup
 npx @paradigma-inc/flywheel uninstall
 ```
 
-## Production vs staging
-
-- `npx @paradigma-inc/flywheel setup` defaults to production
-  (`https://flywheel.paradigma.inc`).
-- To target staging explicitly, pass a staging base URL:
+`--base-url` must be the public Flywheel origin, not a backend URL or an `/api`
+path. Example:
 
 ```bash
-npx @paradigma-inc/flywheel setup --base-url https://flywheel-staging.paradigma.inc
+npx @paradigma-inc/flywheel@staging setup \
+  --name flywheel-staging \
+  --base-url https://flywheel-staging.paradigma.inc
 ```
 
-- Staging remains protected by the existing staging password gate in the WebUI.
-  The browser auth step must pass that gate before key creation can complete.
-- Setup writes one Flywheel server entry per host+scope. If a host is already
-  configured, setup leaves that entry in place (Context7-style).
-
 ## Commands
 
 - `setup`: interview + browser auth bridge + idempotent host config writes.
@@ -37,16 +25,15 @@ npx @paradigma-inc/flywheel setup --base-url https://flywheel-staging.paradigma.
 - Add `--yes` to skip interactive prompts in the Flywheel wizard.
 - `npx --yes` only auto-confirms `npx`; it does not imply `flywheel --yes`.
 
-## Release channels
-
-- Public production installs use npm (`latest`):
-
-```bash
-npx @paradigma-inc/flywheel setup
-```
-
 ## Supported hosts
 
 - Codex (`~/.codex/config.toml` or `.codex/config.toml`)
 - Claude Code (`~/.claude.json` or `.mcp.json`)
 - OpenCode (`~/.config/opencode/opencode.json` or `opencode.json`)
+- Cursor (`~/.cursor/mcp.json` or `.cursor/mcp.json`)
+- Hermes Agent (`~/.hermes/config.yaml` or `.hermes/config.yaml`)
+- OpenClaw (`~/.openclaw/openclaw.json` or `.openclaw/openclaw.json`)
+- Pi (pi-mono) (`~/.pi/agent/settings.json` or `.pi/settings.json`)
+
+Pi (pi-mono) support writes `mcp.servers` into Pi settings. It requires an
+MCP-capable Pi extension/package to consume those entries.

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "@paradigma-inc/flywheel",
-  "version": "0.1.1",
-  "description": "One-command setup for Flywheel MCP on Codex, Claude Code, and OpenCode",
+  "version": "0.1.5",
+  "description": "One-command setup for Flywheel MCP hosts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/paradigma-inc/paradigma",
+    "directory": "project/flywheel-setup"
+  },
   "type": "module",
   "files": [
     "bin/",
@@ -17,6 +22,7 @@
   "dependencies": {
     "@inquirer/prompts": "^8.2.0",
     "commander": "^14.0.1",
+    "js-yaml": "^4.1.0",
     "ora": "^9.0.0",
     "picocolors": "^1.1.1"
   },

package/src/agents.mjs

@@ -3,11 +3,23 @@ import os from "node:os";
 import path from "node:path";
 
 export const SERVER_NAME = "flywheel";
-export const ALL_HOST_NAMES = ["claude", "opencode", "codex"];
+export const ALL_HOST_NAMES = [
+  "claude",
+  "opencode",
+  "codex",
+  "cursor",
+  "pi-mono",
+  "hermes-agent",
+  "openclaw",
+];
 export const SETUP_HOST_NAMES = {
   claude: "Claude Code",
   opencode: "OpenCode",
   codex: "Codex",
+  cursor: "Cursor",
+  "pi-mono": "Pi (pi-mono)",
+  "hermes-agent": "Hermes Agent",
+  openclaw: "OpenClaw",
 };
 
 const HOME = os.homedir();
@@ -42,10 +54,17 @@ const hosts = {
     displayName: "OpenCode",
     mcp: {
       configType: "json",
-      projectPaths: ["opencode.json", ".opencode.json"],
+      projectPaths: [
+        "opencode.json",
+        "opencode.jsonc",
+        ".opencode.json",
+        ".opencode.jsonc",
+      ],
       globalPaths: [
         path.join(HOME, ".config", "opencode", "opencode.json"),
+        path.join(HOME, ".config", "opencode", "opencode.jsonc"),
         path.join(HOME, ".config", "opencode", ".opencode.json"),
+        path.join(HOME, ".config", "opencode", ".opencode.jsonc"),
       ],
       configKey: "mcp",
       buildEntry: ({ serverUrl, apiKey }) => ({
@@ -58,7 +77,12 @@ const hosts = {
       }),
     },
     detect: {
-      projectPaths: ["opencode.json", ".opencode.json"],
+      projectPaths: [
+        "opencode.json",
+        "opencode.jsonc",
+        ".opencode.json",
+        ".opencode.jsonc",
+      ],
       globalPaths: [path.join(HOME, ".config", "opencode")],
     },
   },
@@ -83,6 +107,89 @@ const hosts = {
       globalPaths: [path.join(HOME, ".codex")],
     },
   },
+  cursor: {
+    name: "cursor",
+    displayName: "Cursor",
+    mcp: {
+      configType: "json",
+      projectPaths: [path.join(".cursor", "mcp.json")],
+      globalPaths: [path.join(HOME, ".cursor", "mcp.json")],
+      configKey: "mcpServers",
+      buildEntry: ({ serverUrl, apiKey }) => ({
+        url: serverUrl,
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+        },
+      }),
+    },
+    detect: {
+      projectPaths: [".cursor", path.join(".cursor", "mcp.json")],
+      globalPaths: [path.join(HOME, ".cursor")],
+    },
+  },
+  "pi-mono": {
+    name: "pi-mono",
+    displayName: "Pi (pi-mono)",
+    mcp: {
+      configType: "json",
+      projectPaths: [path.join(".pi", "settings.json")],
+      globalPaths: [path.join(HOME, ".pi", "agent", "settings.json")],
+      configKey: ["mcp", "servers"],
+      buildEntry: ({ serverUrl, apiKey }) => ({
+        url: serverUrl,
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+        },
+      }),
+    },
+    detect: {
+      projectPaths: [".pi", path.join(".pi", "settings.json")],
+      globalPaths: [path.join(HOME, ".pi"), path.join(HOME, ".pi", "agent")],
+    },
+  },
+  "hermes-agent": {
+    name: "hermes-agent",
+    displayName: "Hermes Agent",
+    mcp: {
+      configType: "yaml",
+      projectPaths: [path.join(".hermes", "config.yaml")],
+      globalPaths: [path.join(HOME, ".hermes", "config.yaml")],
+      configKey: "mcp_servers",
+      buildEntry: ({ serverUrl, apiKey }) => ({
+        url: serverUrl,
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+        },
+      }),
+    },
+    detect: {
+      projectPaths: [".hermes", path.join(".hermes", "config.yaml")],
+      globalPaths: [path.join(HOME, ".hermes"), path.join(HOME, ".hermes", "config.yaml")],
+    },
+  },
+  openclaw: {
+    name: "openclaw",
+    displayName: "OpenClaw",
+    mcp: {
+      configType: "json",
+      projectPaths: [path.join(".openclaw", "openclaw.json")],
+      globalPaths: [path.join(HOME, ".openclaw", "openclaw.json")],
+      configKey: ["mcp", "servers"],
+      buildEntry: ({ serverUrl, apiKey }) => ({
+        url: serverUrl,
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+        },
+      }),
+    },
+    detect: {
+      projectPaths: [".openclaw", path.join(".openclaw", "openclaw.json")],
+      globalPaths: [
+        path.join(HOME, ".openclaw"),
+        path.join(HOME, ".openclaw", "openclaw.json"),
+      ],
+    },
+  },
 };
 
 export function getHost(name) {

package/src/cli.mjs

@@ -18,10 +18,12 @@ import {
   mergeServerEntry,
   readJsonConfig,
   readTomlServerExists,
+  readYamlConfig,
   removeCodexTomlServer,
   removeJsonServerEntry,
   resolveMcpPath,
   writeJsonConfig,
+  writeYamlConfig,
 } from "./mcp-writer.mjs";
 import { acquireApiKeyViaBrowserBridge } from "./setup-auth.mjs";
 
@@ -44,9 +46,29 @@ const CHECKBOX_THEME = {
 };
 
 function normalizeBaseUrl(value) {
-  return String(value || "")
-    .trim()
-    .replace(/\/$/, "");
+  const normalized = String(value || "").trim();
+  let parsedUrl;
+  try {
+    parsedUrl = new URL(normalized);
+  } catch {
+    throw new Error("Base URL must be a valid absolute URL.");
+  }
+
+  if (parsedUrl.pathname !== "/" || parsedUrl.search || parsedUrl.hash) {
+    throw new Error(
+      "Base URL must be a public Flywheel origin without a path, query, or hash.",
+    );
+  }
+
+  return parsedUrl.origin;
+}
+
+function normalizeServerName(value) {
+  const normalized = String(value || "").trim();
+  if (!normalized) {
+    throw new Error("Server name cannot be empty.");
+  }
+  return normalized;
 }
 
 function selectedHostsFromOptions(options) {
@@ -54,6 +76,10 @@ function selectedHostsFromOptions(options) {
   if (options.claude) hosts.push("claude");
   if (options.opencode) hosts.push("opencode");
   if (options.codex) hosts.push("codex");
+  if (options.cursor) hosts.push("cursor");
+  if (options.piMono) hosts.push("pi-mono");
+  if (options.hermesAgent) hosts.push("hermes-agent");
+  if (options.openclaw) hosts.push("openclaw");
   return hosts;
 }
 
@@ -74,26 +100,49 @@ function mcpCandidatesForScope(host, scope) {
   );
 }
 
-async function isAlreadyConfigured(hostName, scope) {
+function readConfigSection(config, configKey) {
+  const pathParts = Array.isArray(configKey) ? configKey : [configKey];
+  let current = config && typeof config === "object" ? config : {};
+  for (const part of pathParts) {
+    if (
+      !current ||
+      typeof current !== "object" ||
+      Array.isArray(current) ||
+      !(part in current)
+    ) {
+      return {};
+    }
+    const next = current[part];
+    if (!next || typeof next !== "object" || Array.isArray(next)) {
+      return {};
+    }
+    current = next;
+  }
+  return current;
+}
+
+async function isAlreadyConfigured(hostName, scope, serverName) {
   const host = getHost(hostName);
   const mcpPath = await resolveMcpPath(mcpCandidatesForScope(host, scope));
   if (host.mcp.configType === "toml") {
-    return readTomlServerExists(mcpPath, SERVER_NAME);
+    return readTomlServerExists(mcpPath, serverName);
   }
-  const existing = await readJsonConfig(mcpPath);
-  const section =
-    existing && typeof existing[host.mcp.configKey] === "object"
-      ? existing[host.mcp.configKey]
-      : {};
-  return SERVER_NAME in section;
+  const existing =
+    host.mcp.configType === "yaml"
+      ? await readYamlConfig(mcpPath)
+      : await readJsonConfig(mcpPath);
+  const section = readConfigSection(existing, host.mcp.configKey);
+  return serverName in section;
 }
 
-async function promptHosts(scope, detected) {
+async function promptHosts(scope, detected, serverName) {
   const choices = await Promise.all(
     ALL_HOST_NAMES.map(async (hostName) => {
-      const configured = await isAlreadyConfigured(hostName, scope).catch(
-        () => false,
-      );
+      const configured = await isAlreadyConfigured(
+        hostName,
+        scope,
+        serverName,
+      ).catch(() => false);
       return {
         name: SETUP_HOST_NAMES[hostName],
         value: hostName,
@@ -122,7 +171,7 @@ async function promptHosts(scope, detected) {
   }
 }
 
-async function resolveHosts(options, scope) {
+async function resolveHosts(options, scope, serverName) {
   const explicit = selectedHostsFromOptions(options);
   if (explicit.length > 0) return explicit;
 
@@ -130,7 +179,7 @@ async function resolveHosts(options, scope) {
   if (detected.length > 0 && options.yes) return detected;
 
   log.blank();
-  const selected = await promptHosts(scope, detected);
+  const selected = await promptHosts(scope, detected, serverName);
   if (!selected) {
     log.warn("Setup cancelled");
     return [];
@@ -156,14 +205,14 @@ async function resolveApiKey(options, baseUrl) {
   }
 }
 
-async function setupHost(hostName, scope, serverUrl, apiKey) {
+async function setupHost(hostName, scope, serverUrl, apiKey, serverName) {
   const host = getHost(hostName);
   const mcpPath = await resolveMcpPath(mcpCandidatesForScope(host, scope));
 
   if (host.mcp.configType === "toml") {
     const { alreadyExists } = await appendTomlServer(
       mcpPath,
-      SERVER_NAME,
+      serverName,
       host.mcp.buildEntry({ serverUrl, apiKey }),
     );
     return {
@@ -173,15 +222,22 @@ async function setupHost(hostName, scope, serverUrl, apiKey) {
     };
   }
 
-  const existing = await readJsonConfig(mcpPath);
+  const existing =
+    host.mcp.configType === "yaml"
+      ? await readYamlConfig(mcpPath)
+      : await readJsonConfig(mcpPath);
   const { config, alreadyExists } = mergeServerEntry(
     existing,
     host.mcp.configKey,
-    SERVER_NAME,
+    serverName,
     host.mcp.buildEntry({ serverUrl, apiKey }),
   );
   if (config !== existing) {
-    await writeJsonConfig(mcpPath, config);
+    if (host.mcp.configType === "yaml") {
+      await writeYamlConfig(mcpPath, config);
+    } else {
+      await writeJsonConfig(mcpPath, config);
+    }
   }
   return {
     host: host.displayName,
@@ -211,7 +267,8 @@ async function runSetupCommand(options) {
   const scope = options.project ? "project" : "global";
   const baseUrl = normalizeBaseUrl(options.baseUrl || DEFAULT_BASE_URL);
   const serverUrl = `${baseUrl}/mcp-server`;
-  const hosts = await resolveHosts(options, scope);
+  const serverName = normalizeServerName(options.name || SERVER_NAME);
+  const hosts = await resolveHosts(options, scope, serverName);
   if (hosts.length === 0) return;
 
   const apiKey = await resolveApiKey(options, baseUrl);
@@ -225,7 +282,9 @@ async function runSetupCommand(options) {
   for (const hostName of hosts) {
     spinner.text = `Setting up ${getHost(hostName).displayName}...`;
     // eslint-disable-next-line no-await-in-loop
-    results.push(await setupHost(hostName, scope, serverUrl, apiKey));
+    results.push(
+      await setupHost(hostName, scope, serverUrl, apiKey, serverName),
+    );
   }
   spinner.succeed("Setup complete");
   printSetupResults(results, scope, serverUrl);
@@ -249,13 +308,15 @@ function scopesFromUninstallScope(scope) {
   return scope === "all" ? ["global", "project"] : [scope];
 }
 
-async function isConfiguredForUninstallScope(hostName, scope) {
+async function isConfiguredForUninstallScope(hostName, scope, serverName) {
   const scopes = scopesFromUninstallScope(scope);
   for (const singleScope of scopes) {
     // eslint-disable-next-line no-await-in-loop
-    const configured = await isAlreadyConfigured(hostName, singleScope).catch(
-      () => false,
-    );
+    const configured = await isAlreadyConfigured(
+      hostName,
+      singleScope,
+      serverName,
+    ).catch(() => false);
     if (configured) return true;
   }
   return false;
@@ -278,10 +339,14 @@ async function promptUninstallScope(defaultScope) {
   }
 }
 
-async function promptUninstallHosts(scope) {
+async function promptUninstallHosts(scope, serverName) {
   const choices = await Promise.all(
     ALL_HOST_NAMES.map(async (hostName) => {
-      const configured = await isConfiguredForUninstallScope(hostName, scope);
+      const configured = await isConfiguredForUninstallScope(
+        hostName,
+        scope,
+        serverName,
+      );
       return {
         name: SETUP_HOST_NAMES[hostName],
         value: hostName,
@@ -310,7 +375,7 @@ async function promptUninstallHosts(scope) {
   }
 }
 
-async function resolveUninstallTargets(options) {
+async function resolveUninstallTargets(options, serverName) {
   const explicitHostsFromFlags = selectedHostsFromOptions(options);
   const explicitHostsFromList =
     explicitHostsFromFlags.length === 0 ? parseHostsList(options.hosts) : [];
@@ -339,7 +404,7 @@ async function resolveUninstallTargets(options) {
     }
 
     if (!hasExplicitHosts) {
-      const selectedHosts = await promptUninstallHosts(scope);
+      const selectedHosts = await promptUninstallHosts(scope, serverName);
       if (!selectedHosts) {
         log.warn("Uninstall cancelled");
         return null;
@@ -351,14 +416,14 @@ async function resolveUninstallTargets(options) {
   return { scope, hosts };
 }
 
-async function removeHostConfig(hostName, scope) {
+async function removeHostConfig(hostName, scope, serverName) {
   const host = getHost(hostName);
   const filePath = await resolveMcpPath(mcpCandidatesForScope(host, scope));
 
   if (host.mcp.configType === "toml") {
     const result = await removeCodexTomlServer({
       filePath,
-      serverName: SERVER_NAME,
+      serverName,
     });
     return {
       host: host.displayName,
@@ -368,14 +433,21 @@ async function removeHostConfig(hostName, scope) {
     };
   }
 
-  const current = await readJsonConfig(filePath);
+  const current =
+    host.mcp.configType === "yaml"
+      ? await readYamlConfig(filePath)
+      : await readJsonConfig(filePath);
   const next = removeJsonServerEntry({
     config: current,
     configKey: host.mcp.configKey,
-    serverName: SERVER_NAME,
+    serverName,
   });
   if (next.changed) {
-    await writeJsonConfig(filePath, next.config);
+    if (host.mcp.configType === "yaml") {
+      await writeYamlConfig(filePath, next.config);
+    } else {
+      await writeJsonConfig(filePath, next.config);
+    }
   }
   return {
     host: host.displayName,
@@ -386,7 +458,8 @@ async function removeHostConfig(hostName, scope) {
 }
 
 async function runUninstallCommand(options) {
-  const resolved = await resolveUninstallTargets(options);
+  const serverName = normalizeServerName(options.name || SERVER_NAME);
+  const resolved = await resolveUninstallTargets(options, serverName);
   if (!resolved) return;
   const { scope, hosts } = resolved;
   const scopes = scopesFromUninstallScope(scope);
@@ -397,7 +470,7 @@ async function runUninstallCommand(options) {
     for (const host of hosts) {
       spinner.text = `Removing from ${getHost(host).displayName} (${singleScope})...`;
       // eslint-disable-next-line no-await-in-loop
-      results.push(await removeHostConfig(host, singleScope));
+      results.push(await removeHostConfig(host, singleScope, serverName));
     }
   }
   spinner.succeed("Uninstall complete");
@@ -425,8 +498,10 @@ function buildProgram() {
 Examples:
   ${pc.green("npx @paradigma-inc/flywheel setup")}
   ${pc.green("npx @paradigma-inc/flywheel setup --codex --project")}
-  ${pc.green("npx @paradigma-inc/flywheel setup --yes --codex --claude")}
-  ${pc.green("npx @paradigma-inc/flywheel uninstall --scope all --hosts codex,claude,opencode")}
+  ${pc.green("npx @paradigma-inc/flywheel setup --yes --codex --claude --cursor")}
+  ${pc.green(
+    "npx @paradigma-inc/flywheel uninstall --scope all --hosts codex,claude,opencode,cursor,pi-mono,hermes-agent,openclaw",
+  )}
 `,
     );
 
@@ -436,6 +511,10 @@ Examples:
     .option("--claude", "Set up for Claude Code")
     .option("--opencode", "Set up for OpenCode")
     .option("--codex", "Set up for Codex")
+    .option("--cursor", "Set up for Cursor")
+    .option("--pi-mono", "Set up for Pi (pi-mono)")
+    .option("--hermes-agent", "Set up for Hermes Agent")
+    .option("--openclaw", "Set up for OpenClaw")
     .option(
       "-p, --project",
       "Configure for current project instead of globally",
@@ -444,8 +523,9 @@ Examples:
     .option("--api-key <key>", "Use API key authentication")
     .option(
       "--base-url <url>",
-      `Flywheel base URL (default: ${DEFAULT_BASE_URL})`,
+      `Public Flywheel origin used for setup and MCP config (default: ${DEFAULT_BASE_URL})`,
     )
+    .option("--name <name>", `MCP server name (default: ${SERVER_NAME})`)
     .action(async (options) => {
       await runSetupCommand(options);
     });
@@ -456,8 +536,19 @@ Examples:
     .option("--claude", "Uninstall for Claude Code")
     .option("--opencode", "Uninstall for OpenCode")
     .option("--codex", "Uninstall for Codex")
-    .option("--hosts <list>", "Comma-separated: codex,claude,opencode")
+    .option("--cursor", "Uninstall for Cursor")
+    .option("--pi-mono", "Uninstall for Pi (pi-mono)")
+    .option("--hermes-agent", "Uninstall for Hermes Agent")
+    .option("--openclaw", "Uninstall for OpenClaw")
+    .option(
+      "--hosts <list>",
+      "Comma-separated: codex,claude,opencode,cursor,pi-mono,hermes-agent,openclaw",
+    )
     .option("--scope <scope>", "all | global | project")
+    .option(
+      "--name <name>",
+      `MCP server name to remove (default: ${SERVER_NAME})`,
+    )
     .option("-y, --yes", "Skip uninstall selection prompts")
     .action(async (options) => {
       await runUninstallCommand(options);

package/src/mcp-writer.mjs

@@ -1,5 +1,6 @@
 import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { load as loadYaml, dump as dumpYaml } from "js-yaml";
 
 function stripJsonComments(text) {
   let result = "";
@@ -52,6 +53,35 @@ export async function writeJsonConfig(filePath, config) {
   });
 }
 
+export async function readYamlConfig(filePath) {
+  let raw;
+  try {
+    raw = await readFile(filePath, "utf8");
+  } catch {
+    return {};
+  }
+  const trimmed = raw.trim();
+  if (!trimmed) return {};
+
+  try {
+    const parsed = loadYaml(trimmed);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+    return {};
+  } catch {
+    return {};
+  }
+}
+
+export async function writeYamlConfig(filePath, config) {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, dumpYaml(config, { noRefs: true }), {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+}
+
 export async function resolveMcpPath(candidates) {
   for (const candidate of candidates) {
     try {
@@ -65,37 +95,72 @@ export async function resolveMcpPath(candidates) {
   return candidates[0];
 }
 
-export function mergeServerEntry(existing, configKey, serverName, entry) {
-  const section =
-    existing &&
-    typeof existing[configKey] === "object" &&
-    existing[configKey] !== null
-      ? existing[configKey]
+function keyPath(configKey) {
+  return Array.isArray(configKey) ? configKey : [configKey];
+}
+
+function readConfigSection(config, configKey) {
+  const pathParts = keyPath(configKey);
+  let current = config && typeof config === "object" ? config : {};
+  for (const part of pathParts) {
+    if (
+      !current ||
+      typeof current !== "object" ||
+      Array.isArray(current) ||
+      !(part in current)
+    ) {
+      return {};
+    }
+    const next = current[part];
+    if (!next || typeof next !== "object" || Array.isArray(next)) {
+      return {};
+    }
+    current = next;
+  }
+  return current;
+}
+
+function writeConfigSection(config, configKey, section) {
+  const pathParts = keyPath(configKey);
+  if (pathParts.length === 0) return config || {};
+
+  const root =
+    config && typeof config === "object" && !Array.isArray(config)
+      ? { ...config }
       : {};
+  let cursor = root;
+
+  for (let index = 0; index < pathParts.length - 1; index += 1) {
+    const part = pathParts[index];
+    const existing = cursor[part];
+    cursor[part] =
+      existing && typeof existing === "object" && !Array.isArray(existing)
+        ? { ...existing }
+        : {};
+    cursor = cursor[part];
+  }
+  cursor[pathParts[pathParts.length - 1]] = section;
+  return root;
+}
+
+export function mergeServerEntry(existing, configKey, serverName, entry) {
+  const section = readConfigSection(existing, configKey);
 
   if (serverName in section) {
     return { config: existing, alreadyExists: true };
   }
 
   return {
-    config: {
-      ...(existing || {}),
-      [configKey]: {
-        ...section,
-        [serverName]: entry,
-      },
-    },
+    config: writeConfigSection(existing, configKey, {
+      ...section,
+      [serverName]: entry,
+    }),
     alreadyExists: false,
   };
 }
 
 export function removeJsonServerEntry({ config, configKey, serverName }) {
-  const section =
-    config &&
-    typeof config[configKey] === "object" &&
-    config[configKey] !== null
-      ? { ...config[configKey] }
-      : {};
+  const section = { ...readConfigSection(config, configKey) };
 
   if (!(serverName in section)) {
     return { config: config || {}, changed: false };
@@ -103,10 +168,7 @@ export function removeJsonServerEntry({ config, configKey, serverName }) {
 
   delete section[serverName];
   return {
-    config: {
-      ...(config || {}),
-      [configKey]: section,
-    },
+    config: writeConfigSection(config, configKey, section),
     changed: true,
   };
 }

package/src/setup-auth.mjs

@@ -32,6 +32,62 @@ function renderCallbackPage({ ok, message }) {
 </html>`;
 }
 
+async function redeemSetupExchangeToken({
+  baseUrl,
+  exchangeToken,
+  state,
+  redirectUri,
+}) {
+  const redeemUrl = new URL(
+    "/api/auth/mcp-api-keys/setup-exchange/redeem",
+    baseUrl,
+  );
+  const response = await fetch(redeemUrl, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      "Idempotency-Key": `setup-redeem:${state}`,
+    },
+    body: JSON.stringify({
+      exchange_token: exchangeToken,
+      state,
+      redirect_uri: redirectUri,
+    }),
+  });
+  let payload = {};
+  try {
+    payload = await response.json();
+  } catch {
+    payload = {};
+  }
+  if (!response.ok) {
+    const detail = resolveRedeemErrorMessage(payload);
+    throw new Error(detail);
+  }
+  const key = (payload?.key || "").trim();
+  if (!key) {
+    throw new Error("Setup exchange response missing API key.");
+  }
+  return { apiKey: key };
+}
+
+function resolveRedeemErrorMessage(payload) {
+  if (!payload || typeof payload !== "object") {
+    return "Setup exchange redemption failed.";
+  }
+  const detail = payload.detail;
+  if (typeof detail === "string" && detail.trim()) {
+    return detail.trim();
+  }
+  if (detail && typeof detail === "object") {
+    const message = detail.message;
+    if (typeof message === "string" && message.trim()) {
+      return message.trim();
+    }
+  }
+  return "Setup exchange redemption failed.";
+}
+
 export async function acquireApiKeyViaBrowserBridge({
   baseUrl,
   keyName,
@@ -44,6 +100,7 @@ export async function acquireApiKeyViaBrowserBridge({
     let settled = false;
     let timeout = null;
     let server = null;
+    let callbackUrl = "";
 
     const cleanup = () => {
       if (timeout) {
@@ -72,7 +129,7 @@ export async function acquireApiKeyViaBrowserBridge({
       resolve(result);
     };
 
-    server = http.createServer((req, res) => {
+    server = http.createServer(async (req, res) => {
       const reqUrl = new URL(req.url || "/", "http://127.0.0.1");
       if (reqUrl.pathname !== "/callback") {
         res.writeHead(404, { "Content-Type": "text/plain" });
@@ -81,7 +138,9 @@ export async function acquireApiKeyViaBrowserBridge({
       }
 
       const callbackState = (reqUrl.searchParams.get("state") || "").trim();
-      const key = (reqUrl.searchParams.get("key") || "").trim();
+      const exchangeToken = (
+        reqUrl.searchParams.get("exchange_token") || ""
+      ).trim();
       const error = (reqUrl.searchParams.get("error") || "").trim();
 
       if (callbackState !== state) {
@@ -103,15 +162,32 @@ export async function acquireApiKeyViaBrowserBridge({
         return;
       }
 
-      if (!key) {
+      if (!exchangeToken) {
         res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
         res.end(
           renderCallbackPage({
             ok: false,
-            message: "No API key was returned.",
+            message: "No setup exchange token was returned.",
           }),
         );
-        fail(new Error("Setup callback missing API key."));
+        fail(new Error("Setup callback missing exchange token."));
+        return;
+      }
+
+      let redeemed;
+      try {
+        redeemed = await redeemSetupExchangeToken({
+          baseUrl,
+          exchangeToken,
+          state,
+          redirectUri: callbackUrl,
+        });
+      } catch (err) {
+        const message =
+          err instanceof Error ? err.message : "Failed to redeem setup exchange.";
+        res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(renderCallbackPage({ ok: false, message }));
+        fail(new Error(message));
         return;
       }
 
@@ -122,7 +198,7 @@ export async function acquireApiKeyViaBrowserBridge({
           message: "Flywheel MCP was authorized successfully.",
         }),
       );
-      succeed({ apiKey: key });
+      succeed({ apiKey: redeemed.apiKey });
     });
 
     server.once("error", (error) => {
@@ -136,7 +212,7 @@ export async function acquireApiKeyViaBrowserBridge({
         return;
       }
 
-      const callbackUrl = `http://127.0.0.1:${address.port}/callback`;
+      callbackUrl = `http://127.0.0.1:${address.port}/callback`;
       const setupUrl = new URL("/auth/mcp/setup", baseUrl);
       setupUrl.searchParams.set("state", state);
       setupUrl.searchParams.set("redirect_uri", callbackUrl);