@peppermint-mcp/wizard 0.1.0

package/README.md

@@ -0,0 +1,81 @@
+# @peppermint/mcp-wizard
+
+One-command installer for [Peppermint](https://peppermint.com) MCP across AI coding hosts.
+
+```bash
+npx @peppermint/mcp-wizard
+```
+
+Detects your installed AI tools, authenticates with Peppermint, and writes the correct MCP config for each host. No manual JSON editing.
+
+## Supported Hosts
+
+| Host | Install method | Auth handled by |
+|---|---|---|
+| Claude Code | `claude mcp add` (CLI) | Claude Code (built-in MCP OAuth) |
+| Claude Desktop | Config file + `mcp-remote` shim | Wizard (browser OAuth → API key) |
+| Cursor | Config file (native HTTP) | Wizard (browser OAuth → API key) |
+| Codex CLI | `codex mcp add` (CLI) | Codex (built-in MCP OAuth) |
+
+## Usage
+
+### Install Peppermint MCP
+
+```bash
+npx @peppermint/mcp-wizard
+```
+
+The wizard will:
+1. Detect which AI hosts are installed on your machine
+2. Let you choose which ones to configure
+3. Open your browser to sign in (only for hosts that need it)
+4. Write the MCP config for each selected host
+5. Verify the installation
+
+### Other commands
+
+```bash
+# List detected hosts and their status
+npx @peppermint/mcp-wizard list
+
+# Health check on existing installation
+npx @peppermint/mcp-wizard doctor
+
+# Remove Peppermint from selected hosts
+npx @peppermint/mcp-wizard remove
+```
+
+### Flags
+
+| Flag | Description |
+|---|---|
+| `--server <url>` | MCP server URL (default: `https://api.peppermint.com/mcp/`) |
+| `--dry-run` | Print what would change without writing anything |
+| `--no-verify` | Skip post-install health check |
+
+### Using staging
+
+```bash
+npx @peppermint/mcp-wizard --server https://dev-api.peppermint.com/mcp/
+```
+
+## How it works
+
+**CLI hosts (Claude Code, Codex):** The wizard runs the host's built-in `mcp add` command. Auth is handled by the host itself through the MCP protocol's browser OAuth flow — no token management needed.
+
+**File-based hosts (Claude Desktop, Cursor):** The wizard performs a localhost OAuth flow:
+1. Opens your browser to Peppermint's sign-in page
+2. Catches the auth callback on a temporary localhost server
+3. Creates a long-lived API key (`pep_...`) that doesn't expire
+4. Writes the API key into the host's config JSON
+
+Credentials are stored in `~/.config/peppermint/credentials.json`. On subsequent runs, the wizard reuses the existing API key without re-authenticating.
+
+## Development
+
+```bash
+npm install
+npm run build     # Build with tsup
+npm run dev       # Watch mode
+npm test          # Run tests
+```

package/dist/cli.js

@@ -0,0 +1,893 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command } from "commander";
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+
+// src/detection/claude-code.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+var exec = promisify(execFile);
+async function detectClaudeCode() {
+  const warnings = [];
+  let version;
+  try {
+    const { stdout } = await exec("claude", ["--version"], { timeout: 5e3 });
+    version = stdout.trim().split("\n")[0];
+  } catch {
+    return null;
+  }
+  let alreadyInstalled = false;
+  try {
+    const { stdout } = await exec("claude", ["mcp", "list"], {
+      timeout: 1e4
+    });
+    alreadyInstalled = stdout.includes("peppermint-memory") || stdout.includes("peppermint");
+  } catch {
+    warnings.push("Could not check existing MCP config");
+  }
+  return {
+    id: "claude-code",
+    name: "Claude Code",
+    version,
+    installMethod: "cli",
+    alreadyInstalled,
+    needsRestart: false,
+    warnings
+  };
+}
+
+// src/detection/claude-desktop.ts
+import { existsSync, readFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import * as jsonc from "jsonc-parser";
+function getConfigPath() {
+  return join(
+    homedir(),
+    "Library",
+    "Application Support",
+    "Claude",
+    "claude_desktop_config.json"
+  );
+}
+function getConfigDir() {
+  return join(homedir(), "Library", "Application Support", "Claude");
+}
+async function detectClaudeDesktop() {
+  const configDir = getConfigDir();
+  const configPath = getConfigPath();
+  const appExists = existsSync("/Applications/Claude.app");
+  const configDirExists = existsSync(configDir);
+  if (!appExists && !configDirExists) {
+    return null;
+  }
+  const warnings = [];
+  let alreadyInstalled = false;
+  if (existsSync(configPath)) {
+    try {
+      const content = readFileSync(configPath, "utf-8");
+      const parsed = jsonc.parse(content);
+      alreadyInstalled = !!parsed?.mcpServers?.peppermint;
+    } catch {
+      warnings.push("Config file exists but could not be parsed");
+    }
+  }
+  return {
+    id: "claude-desktop",
+    name: "Claude Desktop",
+    installMethod: "file-stdio-shim",
+    configPath,
+    alreadyInstalled,
+    needsRestart: true,
+    warnings
+  };
+}
+
+// src/detection/cursor.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { homedir as homedir2 } from "os";
+import { join as join2 } from "path";
+import * as jsonc2 from "jsonc-parser";
+function getConfigPath2() {
+  return join2(homedir2(), ".cursor", "mcp.json");
+}
+async function detectCursor() {
+  const configPath = getConfigPath2();
+  const appExists = existsSync2("/Applications/Cursor.app");
+  const configExists = existsSync2(configPath);
+  if (!appExists && !configExists) {
+    return null;
+  }
+  const warnings = [];
+  let alreadyInstalled = false;
+  if (configExists) {
+    try {
+      const content = readFileSync2(configPath, "utf-8");
+      const parsed = jsonc2.parse(content);
+      alreadyInstalled = !!parsed?.mcpServers?.peppermint;
+    } catch {
+      warnings.push("Config file exists but could not be parsed");
+    }
+  }
+  return {
+    id: "cursor",
+    name: "Cursor",
+    installMethod: "file-native-http",
+    configPath,
+    alreadyInstalled,
+    needsRestart: true,
+    warnings
+  };
+}
+
+// src/detection/codex.ts
+import { execFile as execFile2 } from "child_process";
+import { promisify as promisify2 } from "util";
+var exec2 = promisify2(execFile2);
+async function detectCodex() {
+  let version;
+  try {
+    const { stdout } = await exec2("codex", ["--version"], { timeout: 5e3 });
+    version = stdout.trim().split("\n")[0];
+  } catch {
+    return null;
+  }
+  return {
+    id: "codex",
+    name: "Codex CLI",
+    version,
+    installMethod: "cli",
+    alreadyInstalled: false,
+    needsRestart: false,
+    warnings: []
+  };
+}
+
+// src/detection/index.ts
+async function detectHosts() {
+  const results = await Promise.allSettled([
+    detectClaudeCode(),
+    detectClaudeDesktop(),
+    detectCursor(),
+    detectCodex()
+  ]);
+  return results.filter(
+    (r) => r.status === "fulfilled" && r.value !== null
+  ).map((r) => r.value);
+}
+
+// src/auth/token-store.ts
+import { existsSync as existsSync3, mkdirSync, readFileSync as readFileSync3, writeFileSync } from "fs";
+import { homedir as homedir3 } from "os";
+import { dirname, join as join3 } from "path";
+function getCredentialsPath() {
+  return join3(homedir3(), ".config", "peppermint", "credentials.json");
+}
+function loadCredentials(server) {
+  const path = getCredentialsPath();
+  if (!existsSync3(path)) return null;
+  try {
+    const content = readFileSync3(path, "utf-8");
+    const creds = JSON.parse(content);
+    if (creds.server !== server) return null;
+    if (!creds.api_key || !creds.api_key.startsWith("pep_")) return null;
+    return creds;
+  } catch {
+    return null;
+  }
+}
+function saveCredentials(creds) {
+  const path = getCredentialsPath();
+  const dir = dirname(path);
+  if (!existsSync3(dir)) {
+    mkdirSync(dir, { recursive: true, mode: 448 });
+  }
+  writeFileSync(path, JSON.stringify(creds, null, 2), {
+    encoding: "utf-8",
+    mode: 384
+  });
+}
+
+// src/auth/localhost-oauth.ts
+import { createServer } from "http";
+import { randomBytes, createHash } from "crypto";
+import { URL, URLSearchParams } from "url";
+import open from "open";
+var AUTH_TIMEOUT_MS = 5 * 60 * 1e3;
+function generatePKCE() {
+  const verifier = randomBytes(32).toString("base64url");
+  const challenge = createHash("sha256").update(verifier).digest("base64url");
+  return { verifier, challenge };
+}
+async function registerClient(serverBase2, redirectUri) {
+  const res = await fetch(`${serverBase2}/oauth/register`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      client_name: "Peppermint MCP Wizard",
+      redirect_uris: [redirectUri],
+      grant_types: ["authorization_code"],
+      response_types: ["code"],
+      token_endpoint_auth_method: "none"
+    })
+  });
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(`Client registration failed (${res.status}): ${body}`);
+  }
+  const data = await res.json();
+  return data.client_id;
+}
+async function exchangeCodeForTokens(serverBase2, code, redirectUri, clientId, codeVerifier) {
+  const body = new URLSearchParams({
+    grant_type: "authorization_code",
+    code,
+    redirect_uri: redirectUri,
+    client_id: clientId,
+    code_verifier: codeVerifier
+  });
+  const res = await fetch(`${serverBase2}/oauth/token`, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: body.toString()
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Token exchange failed (${res.status}): ${text}`);
+  }
+  return res.json();
+}
+async function createApiKey(serverBase2, accessToken) {
+  const res = await fetch(`${serverBase2}/auth/api-keys`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${accessToken}`
+    },
+    body: JSON.stringify({
+      name: "mcp-wizard",
+      scopes: ["read:own", "write:own", "read:team"]
+    })
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`API key creation failed (${res.status}): ${text}`);
+  }
+  return res.json();
+}
+function waitForCallback(port, expectedState) {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      server.close();
+      reject(new Error("Authentication timed out (5 minutes). Please try again."));
+    }, AUTH_TIMEOUT_MS);
+    const server = createServer((req, res) => {
+      const url = new URL(req.url, `http://127.0.0.1:${port}`);
+      if (url.pathname !== "/callback") {
+        res.writeHead(404);
+        res.end("Not found");
+        return;
+      }
+      const error = url.searchParams.get("error");
+      if (error) {
+        res.writeHead(200, { "Content-Type": "text/html" });
+        res.end("<html><body><h2>Authorization denied.</h2><p>You can close this tab.</p></body></html>");
+        clearTimeout(timeout);
+        server.close();
+        reject(new Error(`Authorization denied: ${error}`));
+        return;
+      }
+      const code = url.searchParams.get("code");
+      const state = url.searchParams.get("state");
+      if (!code) {
+        res.writeHead(400);
+        res.end("Missing authorization code");
+        return;
+      }
+      if (state !== expectedState) {
+        res.writeHead(400);
+        res.end("State mismatch");
+        clearTimeout(timeout);
+        server.close();
+        reject(new Error("OAuth state mismatch \u2014 possible CSRF"));
+        return;
+      }
+      res.writeHead(200, { "Content-Type": "text/html" });
+      res.end(
+        "<html><body><h2>Authenticated!</h2><p>You can close this tab and return to the terminal.</p></body></html>"
+      );
+      clearTimeout(timeout);
+      server.close();
+      resolve({ code });
+    });
+    server.listen(port, "127.0.0.1");
+  });
+}
+async function authenticateWithBrowser(serverBase2) {
+  const tempServer = createServer();
+  await new Promise((resolve) => {
+    tempServer.listen(0, "127.0.0.1", () => resolve());
+  });
+  const port = tempServer.address().port;
+  tempServer.close();
+  const redirectUri = `http://127.0.0.1:${port}/callback`;
+  const clientId = await registerClient(serverBase2, redirectUri);
+  const { verifier, challenge } = generatePKCE();
+  const state = randomBytes(16).toString("hex");
+  const callbackPromise = waitForCallback(port, state);
+  const params = new URLSearchParams({
+    client_id: clientId,
+    redirect_uri: redirectUri,
+    response_type: "code",
+    code_challenge: challenge,
+    code_challenge_method: "S256",
+    state
+  });
+  const authorizeUrl = `${serverBase2}/oauth/authorize?${params}`;
+  await open(authorizeUrl);
+  const { code } = await callbackPromise;
+  const tokens = await exchangeCodeForTokens(
+    serverBase2,
+    code,
+    redirectUri,
+    clientId,
+    verifier
+  );
+  const apiKeyResult = await createApiKey(serverBase2, tokens.access_token);
+  const creds = {
+    api_key: apiKeyResult.key,
+    email: tokens.email,
+    server: serverBase2,
+    client_id: clientId,
+    created_at: Date.now()
+  };
+  saveCredentials(creds);
+  return creds;
+}
+
+// src/hosts/claude-code.ts
+import { execFile as execFile3 } from "child_process";
+import { promisify as promisify3 } from "util";
+var exec3 = promisify3(execFile3);
+async function installClaudeCode(serverUrl, dryRun) {
+  const args = [
+    "mcp",
+    "add",
+    "--scope",
+    "user",
+    "--transport",
+    "http",
+    "peppermint-memory",
+    serverUrl
+  ];
+  if (dryRun) {
+    return {
+      success: true,
+      message: `Would run: claude ${args.join(" ")}`,
+      needsRestart: false
+    };
+  }
+  try {
+    await exec3("claude", args, { timeout: 15e3 });
+    return {
+      success: true,
+      message: "Added peppermint-memory via claude mcp add",
+      needsRestart: false
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "claude mcp add failed";
+    return { success: false, message, needsRestart: false };
+  }
+}
+async function removeClaudeCode(dryRun) {
+  const args = ["mcp", "remove", "--scope", "user", "peppermint-memory"];
+  if (dryRun) {
+    return {
+      success: true,
+      message: `Would run: claude ${args.join(" ")}`,
+      needsRestart: false
+    };
+  }
+  try {
+    await exec3("claude", args, { timeout: 15e3 });
+    return {
+      success: true,
+      message: "Removed peppermint-memory via claude mcp remove",
+      needsRestart: false
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "claude mcp remove failed";
+    return { success: false, message, needsRestart: false };
+  }
+}
+
+// src/hosts/claude-desktop.ts
+import { homedir as homedir4 } from "os";
+import { join as join4 } from "path";
+
+// src/hosts/json-config.ts
+import {
+  copyFileSync,
+  existsSync as existsSync4,
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync4,
+  renameSync,
+  writeFileSync as writeFileSync2
+} from "fs";
+import { dirname as dirname2 } from "path";
+import * as jsonc3 from "jsonc-parser";
+function writeServerToConfig(options) {
+  const { filePath, serverProperty, serverName, serverConfig, dryRun } = options;
+  const dir = dirname2(filePath);
+  if (!existsSync4(dir)) {
+    if (dryRun) {
+      return `Would create directory: ${dir}
+Would create: ${filePath}`;
+    }
+    mkdirSync2(dir, { recursive: true });
+  }
+  let content = "";
+  if (existsSync4(filePath)) {
+    content = readFileSync4(filePath, "utf-8");
+  }
+  const edits = jsonc3.modify(content, [serverProperty, serverName], serverConfig, {
+    formattingOptions: { tabSize: 2, insertSpaces: true }
+  });
+  const updated = jsonc3.applyEdits(content, edits);
+  const errors = [];
+  jsonc3.parse(updated, errors);
+  if (errors.length > 0) {
+    throw new Error(
+      `Config merge produced invalid JSON: ${errors.map((e) => jsonc3.printParseErrorCode(e.error)).join(", ")}`
+    );
+  }
+  if (dryRun) {
+    return `Would write to ${filePath}:
+${updated}`;
+  }
+  if (existsSync4(filePath)) {
+    const backupPath = `${filePath}.bak.${Date.now()}`;
+    copyFileSync(filePath, backupPath);
+  }
+  const tmpPath = `${filePath}.tmp`;
+  writeFileSync2(tmpPath, updated, "utf-8");
+  renameSync(tmpPath, filePath);
+  return filePath;
+}
+function removeServerFromConfig(filePath, serverProperty, serverName, dryRun) {
+  if (!existsSync4(filePath)) {
+    return false;
+  }
+  const content = readFileSync4(filePath, "utf-8");
+  const edits = jsonc3.modify(content, [serverProperty, serverName], void 0, {
+    formattingOptions: { tabSize: 2, insertSpaces: true }
+  });
+  if (edits.length === 0) {
+    return false;
+  }
+  const updated = jsonc3.applyEdits(content, edits);
+  if (dryRun) {
+    return true;
+  }
+  const backupPath = `${filePath}.bak.${Date.now()}`;
+  copyFileSync(filePath, backupPath);
+  const tmpPath = `${filePath}.tmp`;
+  writeFileSync2(tmpPath, updated, "utf-8");
+  renameSync(tmpPath, filePath);
+  return true;
+}
+
+// src/hosts/claude-desktop.ts
+function getConfigPath3() {
+  return join4(
+    homedir4(),
+    "Library",
+    "Application Support",
+    "Claude",
+    "claude_desktop_config.json"
+  );
+}
+async function installClaudeDesktop(serverUrl, apiKey, dryRun) {
+  const configPath = getConfigPath3();
+  const serverConfig = {
+    command: "npx",
+    args: [
+      "-y",
+      "mcp-remote@latest",
+      serverUrl,
+      "--header",
+      "Authorization:${PEPPERMINT_AUTH_HEADER}"
+    ],
+    env: {
+      PEPPERMINT_AUTH_HEADER: `Bearer ${apiKey}`
+    }
+  };
+  try {
+    const result = writeServerToConfig({
+      filePath: configPath,
+      serverProperty: "mcpServers",
+      serverName: "peppermint",
+      serverConfig,
+      dryRun
+    });
+    return {
+      success: true,
+      message: dryRun ? result : `Wrote config to ${configPath}`,
+      needsRestart: true
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "Config write failed";
+    return { success: false, message, needsRestart: false };
+  }
+}
+async function removeClaudeDesktop(dryRun) {
+  const configPath = getConfigPath3();
+  const removed = removeServerFromConfig(
+    configPath,
+    "mcpServers",
+    "peppermint",
+    dryRun
+  );
+  return {
+    success: true,
+    message: removed ? "Removed peppermint from Claude Desktop config" : "peppermint not found in Claude Desktop config",
+    needsRestart: true
+  };
+}
+
+// src/hosts/cursor.ts
+import { homedir as homedir5 } from "os";
+import { join as join5 } from "path";
+function getConfigPath4() {
+  return join5(homedir5(), ".cursor", "mcp.json");
+}
+async function installCursor(serverUrl, apiKey, dryRun) {
+  const configPath = getConfigPath4();
+  const serverConfig = {
+    url: serverUrl,
+    headers: {
+      Authorization: `Bearer ${apiKey}`
+    }
+  };
+  try {
+    const result = writeServerToConfig({
+      filePath: configPath,
+      serverProperty: "mcpServers",
+      serverName: "peppermint",
+      serverConfig,
+      dryRun
+    });
+    return {
+      success: true,
+      message: dryRun ? result : `Wrote config to ${configPath}`,
+      needsRestart: true
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "Config write failed";
+    return { success: false, message, needsRestart: false };
+  }
+}
+async function removeCursor(dryRun) {
+  const configPath = getConfigPath4();
+  const removed = removeServerFromConfig(
+    configPath,
+    "mcpServers",
+    "peppermint",
+    dryRun
+  );
+  return {
+    success: true,
+    message: removed ? "Removed peppermint from Cursor config" : "peppermint not found in Cursor config",
+    needsRestart: true
+  };
+}
+
+// src/hosts/codex.ts
+import { execFile as execFile4 } from "child_process";
+import { promisify as promisify4 } from "util";
+var exec4 = promisify4(execFile4);
+async function installCodex(serverUrl, dryRun) {
+  const addArgs = ["mcp", "add", "peppermint-memory", "--url", serverUrl];
+  if (dryRun) {
+    return {
+      success: true,
+      message: `Would run: codex ${addArgs.join(" ")}`,
+      needsRestart: false
+    };
+  }
+  try {
+    await exec4("codex", addArgs, { timeout: 15e3 });
+    return {
+      success: true,
+      message: "Added peppermint-memory via codex mcp add",
+      needsRestart: false
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "codex mcp add failed";
+    return { success: false, message, needsRestart: false };
+  }
+}
+async function removeCodex(dryRun) {
+  const args = ["mcp", "remove", "peppermint-memory"];
+  if (dryRun) {
+    return {
+      success: true,
+      message: `Would run: codex ${args.join(" ")}`,
+      needsRestart: false
+    };
+  }
+  try {
+    await exec4("codex", args, { timeout: 15e3 });
+    return {
+      success: true,
+      message: "Removed peppermint-memory via codex mcp remove",
+      needsRestart: false
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "codex mcp remove failed";
+    return { success: false, message, needsRestart: false };
+  }
+}
+
+// src/verify/server.ts
+async function checkServerReachable(serverUrl) {
+  const start = Date.now();
+  try {
+    const res = await fetch(serverUrl, {
+      method: "POST",
+      signal: AbortSignal.timeout(5e3),
+      headers: { "Content-Type": "application/json" },
+      body: "{}"
+    });
+    return { reachable: true, latencyMs: Date.now() - start };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "Server unreachable";
+    return { reachable: false, error: message };
+  }
+}
+
+// src/verify/host.ts
+import { existsSync as existsSync5, readFileSync as readFileSync5 } from "fs";
+import * as jsonc4 from "jsonc-parser";
+function checkHostConfig(hostId, configPath) {
+  if (!configPath) {
+    return {
+      hostId,
+      status: "pass",
+      message: "Installed via CLI"
+    };
+  }
+  if (!existsSync5(configPath)) {
+    return {
+      hostId,
+      status: "fail",
+      message: `Config file not found: ${configPath}`
+    };
+  }
+  try {
+    const content = readFileSync5(configPath, "utf-8");
+    const parsed = jsonc4.parse(content);
+    const hasPeppermint = !!parsed?.mcpServers?.peppermint;
+    if (!hasPeppermint) {
+      return {
+        hostId,
+        status: "fail",
+        message: "peppermint entry not found in config"
+      };
+    }
+    return {
+      hostId,
+      status: "warn",
+      message: "Config written; restart required to verify"
+    };
+  } catch {
+    return {
+      hostId,
+      status: "fail",
+      message: `Config file could not be parsed: ${configPath}`
+    };
+  }
+}
+
+// src/cli.ts
+var DEFAULT_SERVER = "https://api.peppermint.com/mcp/";
+function serverBase(serverUrl) {
+  return serverUrl.replace(/\/mcp\/?$/, "");
+}
+function needsAuth(hosts) {
+  return hosts.some(
+    (h) => h.installMethod === "file-native-http" || h.installMethod === "file-stdio-shim"
+  );
+}
+async function installHost(host, serverUrl, apiKey, dryRun) {
+  switch (host.id) {
+    case "claude-code":
+      return installClaudeCode(serverUrl, dryRun);
+    case "claude-desktop":
+      if (!apiKey) throw new Error("API key required for Claude Desktop");
+      return installClaudeDesktop(serverUrl, apiKey, dryRun);
+    case "cursor":
+      if (!apiKey) throw new Error("API key required for Cursor");
+      return installCursor(serverUrl, apiKey, dryRun);
+    case "codex":
+      return installCodex(serverUrl, dryRun);
+  }
+}
+async function removeHost(host, dryRun) {
+  switch (host.id) {
+    case "claude-code":
+      return removeClaudeCode(dryRun);
+    case "claude-desktop":
+      return removeClaudeDesktop(dryRun);
+    case "cursor":
+      return removeCursor(dryRun);
+    case "codex":
+      return removeCodex(dryRun);
+  }
+}
+async function addCommand(options) {
+  p.intro(pc.green("\u{1F33F} Peppermint MCP Wizard"));
+  const s = p.spinner();
+  s.start("Detecting AI hosts...");
+  const hosts = await detectHosts();
+  s.stop("Detection complete");
+  if (hosts.length === 0) {
+    p.log.error(
+      "No supported AI hosts detected. Install Claude Code, Claude Desktop, Cursor, or Codex CLI and try again."
+    );
+    process.exit(6);
+  }
+  for (const host of hosts) {
+    const status = host.alreadyInstalled ? pc.yellow("already configured") : pc.dim("not configured");
+    const version = host.version ? pc.dim(` (${host.version})`) : "";
+    p.log.info(`${host.alreadyInstalled ? "\u26A0" : "\u2713"} ${host.name}${version}  ${status}`);
+  }
+  const unconfigured = hosts.filter((h) => !h.alreadyInstalled);
+  const toInstall = unconfigured.length > 0 ? unconfigured : hosts;
+  const selected = await p.multiselect({
+    message: "Install Peppermint MCP into which hosts?",
+    options: toInstall.map((h) => ({
+      value: h.id,
+      label: h.name,
+      hint: h.alreadyInstalled ? "will reinstall" : void 0
+    })),
+    initialValues: toInstall.map((h) => h.id)
+  });
+  if (p.isCancel(selected)) {
+    p.cancel("Cancelled.");
+    process.exit(0);
+  }
+  const selectedHosts = hosts.filter(
+    (h) => selected.includes(h.id)
+  );
+  s.start(`Checking server at ${options.server}...`);
+  const serverCheck = await checkServerReachable(options.server);
+  if (!serverCheck.reachable) {
+    s.stop("Server unreachable");
+    p.log.error(
+      `Cannot reach ${options.server}: ${serverCheck.error}
+Check your internet connection and try again.`
+    );
+    process.exit(4);
+  }
+  s.stop(
+    `Server reachable ${pc.dim(`(${serverCheck.latencyMs}ms)`)}`
+  );
+  let apiKey;
+  if (needsAuth(selectedHosts)) {
+    const base = serverBase(options.server);
+    const existing = loadCredentials(base);
+    if (existing) {
+      apiKey = existing.api_key;
+      p.log.success(`Authenticated as ${pc.bold(existing.email || "user")} (cached)`);
+    } else {
+      p.log.info("Opening browser for authentication...");
+      try {
+        const creds = await authenticateWithBrowser(base);
+        apiKey = creds.api_key;
+        p.log.success(`Authenticated as ${pc.bold(creds.email || "user")}`);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : "Authentication failed";
+        p.log.error(msg);
+        process.exit(3);
+      }
+    }
+  }
+  p.log.step("Installing...");
+  const results = [];
+  for (const host of selectedHosts) {
+    const result = await installHost(host, options.server, apiKey, options.dryRun);
+    const icon = result.success ? pc.green("\u2713") : pc.red("\u2717");
+    p.log.info(`  ${icon} ${host.name}  ${pc.dim(result.message)}`);
+    results.push({ host, result });
+  }
+  if (options.verify && !options.dryRun) {
+    p.log.step("Verifying...");
+    for (const { host } of results) {
+      const check = checkHostConfig(host.id, host.configPath);
+      const icon = check.status === "pass" ? pc.green("\u2713") : check.status === "warn" ? pc.yellow("\u26A0") : pc.red("\u2717");
+      p.log.info(`  ${icon} ${host.name}  ${pc.dim(check.message)}`);
+    }
+  }
+  const needRestart = results.filter((r) => r.result.needsRestart);
+  const failed = results.filter((r) => !r.result.success);
+  p.outro(
+    failed.length > 0 ? pc.red(`${failed.length} host(s) failed. Check the output above.`) : needRestart.length > 0 ? pc.green("Done!") + pc.dim(
+      ` Restart ${needRestart.map((r) => r.host.name).join(", ")} to finish.`
+    ) : pc.green("Done! Peppermint MCP is ready.")
+  );
+  if (failed.length > 0) process.exit(2);
+}
+async function listCommand(options) {
+  p.intro(pc.green("\u{1F33F} Peppermint MCP Wizard \u2014 List"));
+  const hosts = await detectHosts();
+  if (hosts.length === 0) {
+    p.log.warn("No supported AI hosts detected.");
+    process.exit(6);
+  }
+  for (const host of hosts) {
+    const status = host.alreadyInstalled ? pc.green("configured") : pc.dim("not configured");
+    const version = host.version ? pc.dim(` (${host.version})`) : "";
+    p.log.info(`${host.name}${version}  ${status}`);
+  }
+  p.outro(`${hosts.length} host(s) detected`);
+}
+async function doctorCommand(options) {
+  p.intro(pc.green("\u{1F33F} Peppermint MCP Wizard \u2014 Doctor"));
+  const serverCheck = await checkServerReachable(options.server);
+  const serverIcon = serverCheck.reachable ? pc.green("\u2713") : pc.red("\u2717");
+  p.log.info(
+    `${serverIcon} Server  ${serverCheck.reachable ? pc.dim(`(${serverCheck.latencyMs}ms)`) : pc.red(serverCheck.error || "unreachable")}`
+  );
+  const base = serverBase(options.server);
+  const creds = loadCredentials(base);
+  const credsIcon = creds ? pc.green("\u2713") : pc.yellow("\u26A0");
+  p.log.info(
+    `${credsIcon} Credentials  ${creds ? pc.dim(creds.email || "API key stored") : pc.yellow("no stored credentials")}`
+  );
+  const hosts = await detectHosts();
+  for (const host of hosts) {
+    const check = checkHostConfig(host.id, host.configPath);
+    const icon = check.status === "pass" ? pc.green("\u2713") : check.status === "warn" ? pc.yellow("\u26A0") : pc.red("\u2717");
+    p.log.info(`${icon} ${host.name}  ${pc.dim(check.message)}`);
+  }
+  p.outro("Health check complete");
+}
+async function removeCommand(options) {
+  p.intro(pc.green("\u{1F33F} Peppermint MCP Wizard \u2014 Remove"));
+  const hosts = await detectHosts();
+  const installed = hosts.filter((h) => h.alreadyInstalled);
+  if (installed.length === 0) {
+    p.log.info("Peppermint is not installed in any detected hosts.");
+    process.exit(0);
+  }
+  const selected = await p.multiselect({
+    message: "Remove Peppermint MCP from which hosts?",
+    options: installed.map((h) => ({
+      value: h.id,
+      label: h.name
+    })),
+    initialValues: installed.map((h) => h.id)
+  });
+  if (p.isCancel(selected)) {
+    p.cancel("Cancelled.");
+    process.exit(0);
+  }
+  const selectedHosts = hosts.filter(
+    (h) => selected.includes(h.id)
+  );
+  for (const host of selectedHosts) {
+    const result = await removeHost(host, options.dryRun);
+    const icon = result.success ? pc.green("\u2713") : pc.red("\u2717");
+    p.log.info(`${icon} ${host.name}  ${pc.dim(result.message)}`);
+  }
+  p.outro("Removal complete");
+}
+var program = new Command().name("peppermint-mcp-wizard").description("One-command installer for Peppermint MCP").version("0.1.0");
+program.command("add", { isDefault: true }).description("Detect hosts, authenticate, install MCP config").option("--server <url>", "MCP server URL", DEFAULT_SERVER).option("--dry-run", "Print changes without writing", false).option("--no-verify", "Skip post-install verification").action((opts) => addCommand({ server: opts.server, dryRun: opts.dryRun, verify: opts.verify }));
+program.command("list").description("List detected AI hosts and their Peppermint status").option("--server <url>", "MCP server URL", DEFAULT_SERVER).action((opts) => listCommand({ server: opts.server }));
+program.command("doctor").description("Run health checks on existing installation").option("--server <url>", "MCP server URL", DEFAULT_SERVER).action((opts) => doctorCommand({ server: opts.server }));
+program.command("remove").description("Remove Peppermint MCP from selected hosts").option("--server <url>", "MCP server URL", DEFAULT_SERVER).option("--dry-run", "Print changes without writing", false).action((opts) => removeCommand({ server: opts.server, dryRun: opts.dryRun }));
+program.parse();

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@peppermint-mcp/wizard",
+  "version": "0.1.0",
+  "description": "One-command installer for Peppermint MCP across AI coding hosts",
+  "type": "module",
+  "bin": {
+    "peppermint-mcp-wizard": "./dist/cli.js"
+  },
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "peppermint",
+    "mcp",
+    "claude",
+    "cursor",
+    "codex",
+    "ai",
+    "memory"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@clack/prompts": "^0.9.1",
+    "commander": "^13.1.0",
+    "jsonc-parser": "^3.3.1",
+    "open": "^10.1.0",
+    "picocolors": "^1.1.1",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.3",
+    "vitest": "^3.1.1"
+  }
+}