@paradigma-inc/flywheel 0.1.0

package/README.md

@@ -0,0 +1,58 @@
+# 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`
+
+## Usage
+
+```bash
+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:
+
+```bash
+npx @paradigma-inc/flywheel setup --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. Re-running setup for a
+  different base URL in the same host+scope updates that same entry.
+
+## Commands
+
+- `setup`: interview + browser auth bridge + idempotent host config writes.
+- `uninstall`: remove Flywheel MCP entries from selected host configs.
+
+## Release channels
+
+- Public production installs use npm (`latest`):
+
+```bash
+npx @paradigma-inc/flywheel setup
+```
+
+- Internal staging builds are published to GitHub Packages (`staging` tag) and
+  require npm auth for `npm.pkg.github.com`.
+- Example internal install:
+
+```bash
+npx --registry=https://npm.pkg.github.com @paradigma-inc/flywheel@staging 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`)

package/bin/flywheel.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import { runCli } from "../src/cli.mjs";
+
+runCli(process.argv).catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`flywheel: ${message}`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@paradigma-inc/flywheel",
+  "version": "0.1.0",
+  "description": "One-command setup for Flywheel MCP on Codex, Claude Code, and OpenCode",
+  "type": "module",
+  "bin": {
+    "flywheel": "bin/flywheel.js"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "UNLICENSED"
+}

package/src/agents.mjs

@@ -0,0 +1,97 @@
+import os from "node:os";
+import path from "node:path";
+
+export const SERVER_NAME = "flywheel";
+export const HOSTS = ["codex", "claude", "opencode"];
+
+export const HOST_LABELS = {
+  codex: "Codex",
+  claude: "Claude Code",
+  opencode: "OpenCode",
+};
+
+const HOME = os.homedir();
+
+/**
+ * Patterns mirrored from Context7's `setup/agents.ts`.
+ */
+export const AGENT_CONFIG = {
+  codex: {
+    configType: "toml",
+    projectPath: path.join(".codex", "config.toml"),
+    globalPath: path.join(HOME, ".codex", "config.toml"),
+    buildEntry: ({ serverUrl, apiKey }) => ({
+      type: "http",
+      url: serverUrl,
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+      },
+    }),
+  },
+  claude: {
+    configType: "json",
+    projectPath: ".mcp.json",
+    globalPath: path.join(HOME, ".claude.json"),
+    configKey: "mcpServers",
+    buildEntry: ({ serverUrl, apiKey }) => ({
+      type: "http",
+      url: serverUrl,
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+      },
+    }),
+  },
+  opencode: {
+    configType: "json",
+    projectPath: "opencode.json",
+    globalPath: path.join(HOME, ".config", "opencode", "opencode.json"),
+    configKey: "mcp",
+    buildEntry: ({ serverUrl, apiKey }) => ({
+      type: "remote",
+      url: serverUrl,
+      enabled: true,
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+      },
+    }),
+  },
+};
+
+export function normalizeScope(scope) {
+  if (scope === "global" || scope === "project") return scope;
+  return "global";
+}
+
+export function resolveHostConfigPath(host, scope) {
+  const hostConfig = AGENT_CONFIG[host];
+  if (!hostConfig) {
+    throw new Error(`Unsupported host: ${host}`);
+  }
+  if (scope === "project") {
+    return path.join(process.cwd(), hostConfig.projectPath);
+  }
+  return hostConfig.globalPath;
+}
+
+export function normalizeHosts(rawHosts) {
+  if (!Array.isArray(rawHosts) || rawHosts.length === 0) {
+    return [...HOSTS];
+  }
+  const normalized = [];
+  for (const host of rawHosts) {
+    const candidate = String(host || "").trim().toLowerCase();
+    if (!candidate) continue;
+    if (!HOSTS.includes(candidate)) {
+      throw new Error(
+        `Unsupported host '${candidate}'. Supported: ${HOSTS.join(", ")}`,
+      );
+    }
+    if (!normalized.includes(candidate)) {
+      normalized.push(candidate);
+    }
+  }
+  if (normalized.length === 0) {
+    return [...HOSTS];
+  }
+  return normalized;
+}

package/src/cli.mjs

@@ -0,0 +1,422 @@
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline/promises";
+
+import {
+  AGENT_CONFIG,
+  HOST_LABELS,
+  HOSTS,
+  SERVER_NAME,
+  normalizeHosts,
+  normalizeScope,
+  resolveHostConfigPath,
+} from "./agents.mjs";
+import {
+  readJsonConfig,
+  removeCodexTomlServer,
+  removeJsonServerEntry,
+  upsertCodexTomlServer,
+  upsertJsonServerEntry,
+  writeJsonConfig,
+} from "./mcp-writer.mjs";
+import { acquireApiKeyViaBrowserBridge } from "./setup-auth.mjs";
+
+// This setup flow intentionally follows Context7's structure:
+// - packages/cli/src/commands/setup.ts
+// - packages/cli/src/setup/agents.ts
+// - packages/cli/src/setup/mcp-writer.ts
+const DEFAULT_BASE_URL =
+  process.env.FLYWHEEL_PUBLIC_BASE_URL || "https://flywheel.paradigma.inc";
+const DEFAULT_SCOPE = "global";
+const SHARED_KEY_PATH = path.join(
+  os.homedir(),
+  ".config",
+  "flywheel",
+  "mcp-api-key",
+);
+
+function printHelp() {
+  console.log(`flywheel
+
+Commands:
+  setup       Configure Flywheel MCP for codex/claude/opencode
+  uninstall   Remove Flywheel MCP entries from host configs
+
+Options:
+  --hosts <list>       Comma-separated: codex,claude,opencode
+  --scope <scope>      global | project | all (uninstall only)
+  --base-url <url>     Flywheel base URL (default: ${DEFAULT_BASE_URL})
+  --server-url <url>   MCP server URL (default: <base-url>/mcp-server)
+  --api-key <key>      Use API key directly (skip browser auth)
+  --name <name>        API key name to create during browser setup
+  --yes                Non-interactive defaults
+  --delete-key         Uninstall: also remove ~/.config/flywheel/mcp-api-key
+  -h, --help           Show this help
+`);
+}
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const command = args[0];
+  const options = {
+    hosts: null,
+    scope: null,
+    baseUrl: null,
+    serverUrl: null,
+    apiKey: null,
+    name: null,
+    yes: false,
+    deleteKey: false,
+    help: false,
+  };
+
+  for (let i = 1; i < args.length; i += 1) {
+    const arg = args[i];
+    const next = args[i + 1];
+    switch (arg) {
+      case "--hosts":
+        options.hosts = next || "";
+        i += 1;
+        break;
+      case "--scope":
+        options.scope = next || "";
+        i += 1;
+        break;
+      case "--base-url":
+        options.baseUrl = next || "";
+        i += 1;
+        break;
+      case "--server-url":
+        options.serverUrl = next || "";
+        i += 1;
+        break;
+      case "--api-key":
+        options.apiKey = next || "";
+        i += 1;
+        break;
+      case "--name":
+        options.name = next || "";
+        i += 1;
+        break;
+      case "--yes":
+      case "-y":
+        options.yes = true;
+        break;
+      case "--delete-key":
+        options.deleteKey = true;
+        break;
+      case "--help":
+      case "-h":
+        options.help = true;
+        break;
+      default:
+        throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+
+  return { command, options };
+}
+
+function parseHostsValue(value) {
+  if (!value) return [...HOSTS];
+  const pieces = String(value)
+    .split(",")
+    .map((v) => v.trim())
+    .filter(Boolean);
+  return normalizeHosts(pieces);
+}
+
+async function promptLine(rl, message, defaultValue = "") {
+  const suffix = defaultValue ? ` (${defaultValue})` : "";
+  const answer = await rl.question(`${message}${suffix}: `);
+  const trimmed = answer.trim();
+  return trimmed || defaultValue;
+}
+
+async function resolveSetupInputs(options) {
+  let scope = normalizeScope(options.scope || DEFAULT_SCOPE);
+  let hosts = parseHostsValue(options.hosts);
+  let baseUrl = (options.baseUrl || DEFAULT_BASE_URL).trim().replace(/\/$/, "");
+
+  if (!options.yes) {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    try {
+      const promptedScope = await promptLine(
+        rl,
+        "Scope [global/project]",
+        scope,
+      );
+      scope = normalizeScope(promptedScope);
+
+      const promptedHosts = await promptLine(
+        rl,
+        "Hosts (comma-separated codex,claude,opencode)",
+        hosts.join(","),
+      );
+      hosts = parseHostsValue(promptedHosts);
+
+      baseUrl = (await promptLine(rl, "Flywheel base URL", baseUrl)).replace(
+        /\/$/,
+        "",
+      );
+    } finally {
+      rl.close();
+    }
+  }
+
+  const serverUrl = (options.serverUrl || `${baseUrl}/mcp-server`)
+    .trim()
+    .replace(/\/$/, "");
+
+  return {
+    scope,
+    hosts,
+    baseUrl,
+    serverUrl,
+  };
+}
+
+async function resolveUninstallInputs(options) {
+  let scope = (options.scope || "all").trim().toLowerCase();
+  if (!["all", "global", "project"].includes(scope)) {
+    scope = "all";
+  }
+  let hosts = parseHostsValue(options.hosts);
+
+  if (!options.yes) {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    try {
+      const promptedScope = await promptLine(
+        rl,
+        "Scope [all/global/project]",
+        scope,
+      );
+      scope = ["all", "global", "project"].includes(promptedScope)
+        ? promptedScope
+        : "all";
+      const promptedHosts = await promptLine(
+        rl,
+        "Hosts (comma-separated codex,claude,opencode)",
+        hosts.join(","),
+      );
+      hosts = parseHostsValue(promptedHosts);
+    } finally {
+      rl.close();
+    }
+  }
+
+  return { scope, hosts };
+}
+
+async function writeSharedApiKey(apiKey) {
+  await mkdir(path.dirname(SHARED_KEY_PATH), { recursive: true });
+  await writeFile(SHARED_KEY_PATH, `${apiKey.trim()}\n`, {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+}
+
+async function configureHost({ host, scope, serverUrl, apiKey }) {
+  const config = AGENT_CONFIG[host];
+  const filePath = resolveHostConfigPath(host, scope);
+  const entry = config.buildEntry({ serverUrl, apiKey });
+
+  if (config.configType === "toml") {
+    const result = await upsertCodexTomlServer({
+      filePath,
+      serverName: SERVER_NAME,
+      entry,
+    });
+    return {
+      host,
+      filePath,
+      status: result.changed
+        ? result.hadExisting
+          ? "updated"
+          : "installed"
+        : "already configured",
+    };
+  }
+
+  const current = await readJsonConfig(filePath);
+  const next = upsertJsonServerEntry({
+    config: current,
+    configKey: config.configKey,
+    serverName: SERVER_NAME,
+    entry,
+  });
+  if (next.changed) {
+    await writeJsonConfig(filePath, next.config);
+  }
+  return {
+    host,
+    filePath,
+    status: next.changed
+      ? next.hadExisting
+        ? "updated"
+        : "installed"
+      : "already configured",
+  };
+}
+
+async function removeHostConfig({ host, scope }) {
+  const config = AGENT_CONFIG[host];
+  const filePath = resolveHostConfigPath(host, scope);
+
+  if (config.configType === "toml") {
+    const result = await removeCodexTomlServer({
+      filePath,
+      serverName: SERVER_NAME,
+    });
+    return {
+      host,
+      scope,
+      filePath,
+      status: result.changed ? "removed" : "not present",
+    };
+  }
+
+  const current = await readJsonConfig(filePath);
+  const next = removeJsonServerEntry({
+    config: current,
+    configKey: config.configKey,
+    serverName: SERVER_NAME,
+  });
+  if (next.changed) {
+    await writeJsonConfig(filePath, next.config);
+  }
+  return {
+    host,
+    scope,
+    filePath,
+    status: next.changed ? "removed" : "not present",
+  };
+}
+
+function printSetupSummary({ scope, serverUrl, results }) {
+  console.log("\nFlywheel MCP setup complete\n");
+  console.log(`Scope: ${scope}`);
+  console.log(`Server URL: ${serverUrl}`);
+  for (const result of results) {
+    console.log(
+      `- ${HOST_LABELS[result.host]}: ${result.status}\n  ${result.filePath}`,
+    );
+  }
+  console.log(`\nStored API key: ${SHARED_KEY_PATH}`);
+}
+
+function printUninstallSummary(results, deletedKey) {
+  console.log("\nFlywheel MCP uninstall complete\n");
+  for (const result of results) {
+    console.log(
+      `- ${HOST_LABELS[result.host]} (${result.scope}): ${result.status}\n  ${result.filePath}`,
+    );
+  }
+  if (deletedKey) {
+    console.log(`\nDeleted shared API key: ${SHARED_KEY_PATH}`);
+  }
+}
+
+async function runSetup(options) {
+  const inputs = await resolveSetupInputs(options);
+  const keyName =
+    (options.name || `flywheel-setup-${cryptoRandomHex(3)}`).trim() ||
+    `flywheel-setup-${cryptoRandomHex(3)}`;
+
+  const apiKey =
+    (options.apiKey && options.apiKey.trim()) ||
+    (
+      await acquireApiKeyViaBrowserBridge({
+        baseUrl: inputs.baseUrl,
+        keyName,
+      })
+    ).apiKey;
+
+  if (!apiKey || !apiKey.trim()) {
+    throw new Error("No API key available for setup.");
+  }
+
+  await writeSharedApiKey(apiKey);
+
+  const results = [];
+  for (const host of inputs.hosts) {
+    results.push(
+      await configureHost({
+        host,
+        scope: inputs.scope,
+        serverUrl: inputs.serverUrl,
+        apiKey,
+      }),
+    );
+  }
+
+  printSetupSummary({
+    scope: inputs.scope,
+    serverUrl: inputs.serverUrl,
+    results,
+  });
+}
+
+async function runUninstall(options) {
+  const inputs = await resolveUninstallInputs(options);
+  const scopes =
+    inputs.scope === "all" ? ["global", "project"] : [inputs.scope];
+
+  const results = [];
+  for (const scope of scopes) {
+    for (const host of inputs.hosts) {
+      results.push(await removeHostConfig({ host, scope }));
+    }
+  }
+
+  let deletedKey = false;
+  if (options.deleteKey) {
+    try {
+      await rm(SHARED_KEY_PATH, { force: true });
+      deletedKey = true;
+    } catch {
+      deletedKey = false;
+    }
+  }
+
+  printUninstallSummary(results, deletedKey);
+}
+
+function cryptoRandomHex(bytes) {
+  return randomBytes(bytes).toString("hex");
+}
+
+export async function runCli(argv = process.argv) {
+  const { command, options } = parseArgs(argv);
+
+  if (
+    !command ||
+    options.help ||
+    command === "help" ||
+    command === "--help" ||
+    command === "-h"
+  ) {
+    printHelp();
+    return;
+  }
+
+  if (command === "setup") {
+    await runSetup(options);
+    return;
+  }
+
+  if (command === "uninstall") {
+    await runUninstall(options);
+    return;
+  }
+
+  throw new Error(`Unknown command '${command}'. Use --help for usage.`);
+}

package/src/mcp-writer.mjs

@@ -0,0 +1,199 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+function stripJsonComments(text) {
+  let result = "";
+  let i = 0;
+  while (i < text.length) {
+    if (text[i] === '"') {
+      const start = i++;
+      while (i < text.length && text[i] !== '"') {
+        if (text[i] === "\\") i++;
+        i++;
+      }
+      result += text.slice(start, ++i);
+    } else if (text[i] === "/" && text[i + 1] === "/") {
+      i += 2;
+      while (i < text.length && text[i] !== "\n") i++;
+    } else if (text[i] === "/" && text[i + 1] === "*") {
+      i += 2;
+      while (i < text.length && !(text[i] === "*" && text[i + 1] === "/")) i++;
+      i += 2;
+    } else {
+      result += text[i++];
+    }
+  }
+  return result;
+}
+
+export async function readJsonConfig(filePath) {
+  try {
+    const raw = (await readFile(filePath, "utf8")).trim();
+    if (!raw) return {};
+    return JSON.parse(stripJsonComments(raw));
+  } catch {
+    return {};
+  }
+}
+
+export async function writeJsonConfig(filePath, config) {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, `${JSON.stringify(config, null, 2)}\n`, {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+}
+
+function stableJson(value) {
+  return JSON.stringify(value, Object.keys(value || {}).sort());
+}
+
+export function upsertJsonServerEntry({ config, configKey, serverName, entry }) {
+  const section =
+    config && typeof config[configKey] === "object" && config[configKey] !== null
+      ? { ...config[configKey] }
+      : {};
+  const previous = section[serverName] ?? null;
+  section[serverName] = entry;
+  const nextConfig = {
+    ...(config || {}),
+    [configKey]: section,
+  };
+
+  const changed = stableJson(previous) !== stableJson(entry);
+  return {
+    config: nextConfig,
+    changed,
+    hadExisting: previous !== null,
+  };
+}
+
+export function removeJsonServerEntry({ config, configKey, serverName }) {
+  const section =
+    config && typeof config[configKey] === "object" && config[configKey] !== null
+      ? { ...config[configKey] }
+      : {};
+  if (!(serverName in section)) {
+    return {
+      config: config || {},
+      changed: false,
+    };
+  }
+  delete section[serverName];
+  const nextConfig = {
+    ...(config || {}),
+    [configKey]: section,
+  };
+  return {
+    config: nextConfig,
+    changed: true,
+  };
+}
+
+function normalizeLineEndings(text) {
+  return text.replace(/\r\n/g, "\n");
+}
+
+export function buildCodexTomlServerBlock({ serverName, entry }) {
+  const lines = [`[mcp_servers.${serverName}]`];
+  lines.push(`type = ${JSON.stringify(entry.type)}`);
+  lines.push(`url = ${JSON.stringify(entry.url)}`);
+
+  const headers = entry.headers && typeof entry.headers === "object" ? entry.headers : {};
+  const headerEntries = Object.entries(headers);
+  if (headerEntries.length > 0) {
+    lines.push("");
+    lines.push(`[mcp_servers.${serverName}.http_headers]`);
+    for (const [key, value] of headerEntries) {
+      lines.push(`${key} = ${JSON.stringify(String(value))}`);
+    }
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+function stripCodexTomlServerBlock({ tomlText, serverName }) {
+  const normalized = normalizeLineEndings(tomlText || "");
+  const lines = normalized.split("\n");
+  const output = [];
+
+  let skipping = false;
+  let removed = false;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    const sectionMatch = trimmed.match(/^\[(.+)\]$/);
+
+    if (sectionMatch) {
+      const sectionName = sectionMatch[1];
+      const isTargetSection =
+        sectionName === `mcp_servers.${serverName}` ||
+        sectionName.startsWith(`mcp_servers.${serverName}.`);
+      if (isTargetSection) {
+        skipping = true;
+        removed = true;
+        continue;
+      }
+      if (skipping) {
+        skipping = false;
+      }
+    }
+
+    if (!skipping) {
+      output.push(line);
+    }
+  }
+
+  let stripped = output.join("\n");
+  stripped = stripped.replace(/\n{3,}/g, "\n\n").trimEnd();
+  if (stripped.length > 0) {
+    stripped += "\n";
+  }
+  return { stripped, removed };
+}
+
+export async function upsertCodexTomlServer({ filePath, serverName, entry }) {
+  let existing = "";
+  try {
+    existing = await readFile(filePath, "utf8");
+  } catch {
+    existing = "";
+  }
+
+  const { stripped, removed } = stripCodexTomlServerBlock({
+    tomlText: existing,
+    serverName,
+  });
+  const block = buildCodexTomlServerBlock({ serverName, entry });
+  const separator = stripped.length > 0 ? "\n" : "";
+  const next = `${stripped}${separator}${block}`;
+
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, next, { encoding: "utf8", mode: 0o600 });
+
+  return {
+    changed: normalizeLineEndings(existing) !== normalizeLineEndings(next),
+    hadExisting: removed,
+  };
+}
+
+export async function removeCodexTomlServer({ filePath, serverName }) {
+  let existing = "";
+  try {
+    existing = await readFile(filePath, "utf8");
+  } catch {
+    return { changed: false };
+  }
+
+  const { stripped, removed } = stripCodexTomlServerBlock({
+    tomlText: existing,
+    serverName,
+  });
+  if (!removed) {
+    return { changed: false };
+  }
+
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, stripped, { encoding: "utf8", mode: 0o600 });
+  return { changed: true };
+}

package/src/setup-auth.mjs

@@ -0,0 +1,157 @@
+import crypto from "node:crypto";
+import http from "node:http";
+import { spawn } from "node:child_process";
+
+const DEFAULT_AUTH_TIMEOUT_MS = 5 * 60 * 1000;
+
+function openUrlInBrowser(url) {
+  const platform = process.platform;
+  if (platform === "darwin") {
+    return spawn("open", [url], { stdio: "ignore", detached: true });
+  }
+  if (platform === "win32") {
+    return spawn("cmd", ["/c", "start", "", url], {
+      stdio: "ignore",
+      detached: true,
+    });
+  }
+  return spawn("xdg-open", [url], { stdio: "ignore", detached: true });
+}
+
+function renderCallbackPage({ ok, message }) {
+  const title = ok ? "Flywheel Setup Complete" : "Flywheel Setup Failed";
+  const color = ok ? "#16a34a" : "#dc2626";
+  return `<!doctype html>
+<html>
+  <head><meta charset=\"utf-8\"><title>${title}</title></head>
+  <body style=\"font-family: system-ui; margin: 0; padding: 40px; background: #fafafa; color: #111;\">
+    <h1 style=\"margin-top: 0; color: ${color};\">${title}</h1>
+    <p>${message}</p>
+    <p>You can close this window and return to the terminal.</p>
+  </body>
+</html>`;
+}
+
+export async function acquireApiKeyViaBrowserBridge({
+  baseUrl,
+  keyName,
+  timeoutMs = DEFAULT_AUTH_TIMEOUT_MS,
+}) {
+  const state = crypto.randomUUID();
+
+  return await new Promise((resolve, reject) => {
+    let settled = false;
+    let timeout = null;
+    let server = null;
+
+    const cleanup = () => {
+      if (timeout) {
+        clearTimeout(timeout);
+        timeout = null;
+      }
+      if (server) {
+        server.close();
+        server = null;
+      }
+    };
+
+    const fail = (error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(error);
+    };
+
+    const succeed = (result) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve(result);
+    };
+
+    server = http.createServer((req, res) => {
+      const reqUrl = new URL(req.url || "/", "http://127.0.0.1");
+      if (reqUrl.pathname !== "/callback") {
+        res.writeHead(404, { "Content-Type": "text/plain" });
+        res.end("Not Found");
+        return;
+      }
+
+      const callbackState = (reqUrl.searchParams.get("state") || "").trim();
+      const key = (reqUrl.searchParams.get("key") || "").trim();
+      const error = (reqUrl.searchParams.get("error") || "").trim();
+
+      if (callbackState !== state) {
+        res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(
+          renderCallbackPage({
+            ok: false,
+            message: "State mismatch. Please retry setup.",
+          }),
+        );
+        fail(new Error("Setup callback state mismatch."));
+        return;
+      }
+
+      if (error) {
+        res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(renderCallbackPage({ ok: false, message: error }));
+        fail(new Error(error));
+        return;
+      }
+
+      if (!key) {
+        res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(
+          renderCallbackPage({
+            ok: false,
+            message: "No API key was returned.",
+          }),
+        );
+        fail(new Error("Setup callback missing API key."));
+        return;
+      }
+
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+      res.end(
+        renderCallbackPage({
+          ok: true,
+          message: "Flywheel MCP was authorized successfully.",
+        }),
+      );
+      succeed({ apiKey: key });
+    });
+
+    server.once("error", (error) => {
+      fail(error);
+    });
+
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (!address || typeof address === "string") {
+        fail(new Error("Failed to allocate local callback port."));
+        return;
+      }
+
+      const 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);
+      setupUrl.searchParams.set("name", keyName);
+
+      console.log("Opening browser for Flywheel login and key creation...");
+      console.log(`If it does not open, use this URL:\n${setupUrl.toString()}\n`);
+
+      try {
+        const child = openUrlInBrowser(setupUrl.toString());
+        child.unref();
+      } catch {
+        // User can still open URL manually.
+      }
+    });
+
+    timeout = setTimeout(() => {
+      fail(new Error("Timed out waiting for browser authorization."));
+    }, timeoutMs);
+  });
+}

package/tests/mcp-writer.test.mjs

@@ -0,0 +1,117 @@
+import { mkdtemp, readFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  removeCodexTomlServer,
+  removeJsonServerEntry,
+  upsertCodexTomlServer,
+  upsertJsonServerEntry,
+  writeJsonConfig,
+  readJsonConfig,
+} from "../src/mcp-writer.mjs";
+
+test("upsertJsonServerEntry installs and removes server entries", async () => {
+  const initial = {
+    mcpServers: {
+      other: {
+        url: "http://localhost/other",
+      },
+    },
+  };
+
+  const inserted = upsertJsonServerEntry({
+    config: initial,
+    configKey: "mcpServers",
+    serverName: "flywheel",
+    entry: {
+      type: "http",
+      url: "https://flywheel.paradigma.inc/mcp-server",
+    },
+  });
+
+  assert.equal(inserted.changed, true);
+  assert.equal(inserted.hadExisting, false);
+  assert.equal(inserted.config.mcpServers.flywheel.type, "http");
+
+  const removed = removeJsonServerEntry({
+    config: inserted.config,
+    configKey: "mcpServers",
+    serverName: "flywheel",
+  });
+  assert.equal(removed.changed, true);
+  assert.equal("flywheel" in removed.config.mcpServers, false);
+  assert.equal("other" in removed.config.mcpServers, true);
+});
+
+test("codex toml writer replaces flywheel block idempotently", async () => {
+  const tempDir = await mkdtemp(path.join(os.tmpdir(), "flywheel-mcp-writer-"));
+  const filePath = path.join(tempDir, "config.toml");
+
+  const first = await upsertCodexTomlServer({
+    filePath,
+    serverName: "flywheel",
+    entry: {
+      type: "http",
+      url: "https://flywheel.paradigma.inc/mcp-server",
+      headers: {
+        Authorization: "Bearer one",
+      },
+    },
+  });
+  assert.equal(first.changed, true);
+
+  const second = await upsertCodexTomlServer({
+    filePath,
+    serverName: "flywheel",
+    entry: {
+      type: "http",
+      url: "https://flywheel.paradigma.inc/mcp-server",
+      headers: {
+        Authorization: "Bearer two",
+      },
+    },
+  });
+  assert.equal(second.changed, true);
+  assert.equal(second.hadExisting, true);
+
+  const text = await readFile(filePath, "utf8");
+  assert.equal(
+    text.includes("Authorization = \"Bearer two\""),
+    true,
+    "updated token should be present",
+  );
+  assert.equal(
+    text.includes("Authorization = \"Bearer one\""),
+    false,
+    "old token should not survive repeated setup",
+  );
+
+  const removed = await removeCodexTomlServer({
+    filePath,
+    serverName: "flywheel",
+  });
+  assert.equal(removed.changed, true);
+  const afterRemove = await readFile(filePath, "utf8");
+  assert.equal(afterRemove.includes("[mcp_servers.flywheel]"), false);
+});
+
+test("readJsonConfig/writeJsonConfig round-trip", async () => {
+  const tempDir = await mkdtemp(path.join(os.tmpdir(), "flywheel-mcp-json-"));
+  const filePath = path.join(tempDir, "mcp.json");
+
+  const config = {
+    mcpServers: {
+      flywheel: {
+        type: "http",
+        url: "https://flywheel.paradigma.inc/mcp-server",
+      },
+    },
+  };
+
+  await writeJsonConfig(filePath, config);
+  const loaded = await readJsonConfig(filePath);
+  assert.deepEqual(loaded, config);
+});