premanmcp 0.3.4 → 0.3.5

package/README.md

@@ -7,19 +7,24 @@ PreMan is agent-first API infrastructure. It lets backend teams expose endpoints
 ## Install
 
 ```bash
-npx premanmcp install
+npm exec -y premanmcp@latest -- install
 ```
 
-This writes an `preman` MCP server into `~/.cursor/mcp.json`:
+Local development form:
+
+```bash
+node bin/cli.js install
+```
+
+First-time users are prompted for email, OTP, and password directly in the terminal. PreMan creates or connects the account, generates an API key, saves it to `~/.preman/credentials.json`, then writes a `preman` MCP server into `~/.cursor/mcp.json`:
 
 ```json
 {
   "mcpServers": {
     "preman": {
-      "command": "npx",
-      "args": ["-y", "premanmcp"],
+      "command": "npm",
+      "args": ["exec", "-y", "--package", "premanmcp@latest", "--", "premanmcp"],
       "env": {
-        "PREMAN_API_KEY": "pm_live_YOUR_API_KEY_HERE",
         "PREMAN_BACKEND": "https://api.preman.live",
         "PREMAN_FRONTEND": "https://app.preman.live"
       }
@@ -28,23 +33,30 @@ This writes an `preman` MCP server into `~/.cursor/mcp.json`:
 }
 ```
 
-Replace `pm_live_YOUR_API_KEY_HERE` with an API key from [PreMan settings](https://app.preman.live/settings/), then restart Cursor or toggle the MCP server off/on.
+Restart Cursor or toggle the MCP server off/on after install. The MCP server loads the saved key automatically.
+
+You can also create or connect your account before install:
+
+```bash
+npm exec -y premanmcp@latest -- login
+```
 
 You can also pass the key directly:
 
 ```bash
-npx premanmcp install --api-key pm_live_xxx
+npm exec -y premanmcp@latest -- install --api-key pm_live_xxx
 ```
 
 For project-local installation:
 
 ```bash
-npx premanmcp install --project
+npm exec -y premanmcp@latest -- install --project
 ```
 
 ## What It Does
 
 - Converts API endpoints into agent-callable MCP tools.
+- Creates/connects a PreMan account from the terminal or IDE agent.
 - Lets agents test real backend endpoints from the IDE.
 - Syncs endpoint inventory across backend and frontend workflows.
 - Adds API-key auth for PreMan MCP access.
@@ -56,7 +68,11 @@ npx premanmcp install --project
 After installing, ask your coding agent:
 
 ```text
-Use the PreMan MCP to convert my login endpoint into an MCP tool.
+Use the PreMan MCP to scan this codebase, deploy a hosted MCP, and give me the install command.
+```
+
+```text
+Use PreMan to sign me up, verify my email OTP, create my API key, then scan this project.
 ```
 
 ```text
@@ -76,7 +92,7 @@ Show me the audit log for this hosted MCP.
 The installer targets Cursor by default:
 
 ```bash
-npx premanmcp install
+npm exec -y premanmcp@latest -- install
 ```
 
 Manual Cursor config:
@@ -85,11 +101,8 @@ Manual Cursor config:
 {
   "mcpServers": {
     "preman": {
-      "command": "npx",
-      "args": ["-y", "premanmcp"],
-      "env": {
-        "PREMAN_API_KEY": "pm_live_YOUR_API_KEY_HERE"
-      }
+      "command": "npm",
+      "args": ["exec", "-y", "--package", "premanmcp@latest", "--", "premanmcp"]
     }
   }
 }
@@ -98,17 +111,18 @@ Manual Cursor config:
 ## Claude Code
 
 ```bash
-claude mcp add preman -- npx -y premanmcp
+claude mcp add preman -- npm exec -y --package premanmcp@latest -- premanmcp
 ```
 
 ## CLI
 
 ```bash
-npx premanmcp                         # Start the MCP server
-npx premanmcp install                 # Install Cursor MCP config
-npx premanmcp install --print         # Print config without writing
-npx premanmcp install --project       # Write .cursor/mcp.json in current repo
-npx premanmcp install --api-key KEY   # Install with your PreMan API key
+npm exec -y premanmcp@latest --       # Start the MCP server
+npm exec -y premanmcp@latest -- login # Create/login and generate a PreMan API key
+npm exec -y premanmcp@latest -- install          # Install Cursor MCP config
+npm exec -y premanmcp@latest -- install --project # Write .cursor/mcp.json in current repo
+npm exec -y premanmcp@latest -- install --print   # Print config without writing
+npm exec -y premanmcp@latest -- install --api-key KEY # Install with your PreMan API key
 ```
 
 Options:
@@ -118,6 +132,7 @@ Options:
 - `--frontend <url>`: PreMan frontend URL. Defaults to `https://app.preman.live`.
 - `--name <name>`: MCP server name. Defaults to `preman`.
 - `--project`: Write `.cursor/mcp.json` in the current project.
+- `--skip-login`: Install config without interactive terminal auth.
 - `--print`: Print the generated MCP config without writing it.
 
 ## Environment Variables
@@ -126,6 +141,8 @@ Options:
 - `PREMAN_BACKEND`: PreMan backend URL.
 - `PREMAN_FRONTEND`: PreMan frontend URL.
 
+If `PREMAN_API_KEY` is omitted, the MCP server loads credentials from `~/.preman/credentials.json`.
+
 ## Product
 
 PreMan helps teams make APIs usable by agents without giving up control. Developers can turn endpoints into MCP servers, hand customers an install snippet or hosted MCP URL, and audit every tool call through PreMan.

package/bin/cli.js

@@ -4,22 +4,25 @@
  * PreMan CLI.
  *
  * Usage:
- *   npx premanmcp install
- *   npx premanmcp install --api-key pm_live_xxx
- *   npx premanmcp
+ *   npm exec -y premanmcp@latest -- login
+ *   npm exec -y premanmcp@latest -- install
+ *   npm exec -y premanmcp@latest -- install --api-key pm_live_xxx
+ *   npm exec -y premanmcp@latest --
  */
 
 import { spawn } from "node:child_process";
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.join(__dirname, "..");
 const DEFAULT_BACKEND = "https://api.preman.live";
 const DEFAULT_FRONTEND = "https://app.preman.live";
-const API_KEY_PLACEHOLDER = "pm_live_YOUR_API_KEY_HERE";
+const CREDENTIALS_DIR = path.join(os.homedir(), ".preman");
+const CREDENTIALS_FILE = path.join(CREDENTIALS_DIR, "credentials.json");
 
 const args = process.argv.slice(2);
 const command = args[0] === "--help" || args[0] === "-h"
@@ -43,22 +46,29 @@ function printHelp() {
   process.stdout.write(`PreMan MCP
 
 Usage:
-  npx premanmcp install [options]  Install PreMan into Cursor MCP config
-  npx premanmcp                   Start the PreMan MCP server
+  npm exec -y premanmcp@latest -- login              Create/login to PreMan from the terminal
+  npm exec -y premanmcp@latest -- install [options]  Install PreMan into Cursor MCP config
+  npm exec -y premanmcp@latest --                    Start the PreMan MCP server
+
+Login options:
+  --email <email>       Pre-fill the email prompt
+  --backend <url>       PreMan backend URL. Defaults to ${DEFAULT_BACKEND}
 
 Install options:
-  --api-key <key>       PreMan API key. Defaults to ${API_KEY_PLACEHOLDER}
+  --api-key <key>       PreMan API key. If omitted, stored CLI credentials are used
   --backend <url>       PreMan backend URL. Defaults to ${DEFAULT_BACKEND}
   --frontend <url>      PreMan frontend URL. Defaults to ${DEFAULT_FRONTEND}
   --name <name>         MCP server name. Defaults to preman
   --project             Write .cursor/mcp.json in the current project
   --global              Write ~/.cursor/mcp.json (default)
+  --skip-login          Install config without interactive terminal auth
   --print               Print the config instead of writing it
 
 Examples:
-  npx premanmcp install
-  npx premanmcp install --api-key pm_live_xxx
-  npx premanmcp install --project --backend http://127.0.0.1:8000
+  npm exec -y premanmcp@latest -- login
+  npm exec -y premanmcp@latest -- install
+  npm exec -y premanmcp@latest -- install --api-key pm_live_xxx
+  npm exec -y premanmcp@latest -- install --project --backend http://127.0.0.1:8000
 `);
 }
 
@@ -73,25 +83,280 @@ function readJsonFile(filePath) {
   }
 }
 
+function readStoredCredentials() {
+  try {
+    const raw = readFileSync(CREDENTIALS_FILE, "utf8").trim();
+    if (!raw) return null;
+    const creds = JSON.parse(raw);
+    if (creds && typeof creds.api_key === "string" && creds.api_key.startsWith("pm_live_")) {
+      return creds;
+    }
+  } catch {
+    // No stored credentials yet.
+  }
+  return null;
+}
+
+function saveStoredCredentials(creds) {
+  mkdirSync(CREDENTIALS_DIR, { recursive: true, mode: 0o700 });
+  writeFileSync(CREDENTIALS_FILE, `${JSON.stringify(creds, null, 2)}\n`, { mode: 0o600 });
+}
+
+function backendUrl() {
+  return argValue("--backend", process.env.PREMAN_BACKEND || DEFAULT_BACKEND).replace(/\/+$/, "");
+}
+
+async function promptText(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return (await rl.question(question)).trim();
+  } finally {
+    rl.close();
+  }
+}
+
+async function promptSecret(question) {
+  if (!process.stdin.isTTY || !process.stdin.setRawMode) {
+    return promptText(question);
+  }
+
+  return new Promise((resolve) => {
+    const stdin = process.stdin;
+    const stdout = process.stdout;
+    const wasRaw = stdin.isRaw;
+    let value = "";
+
+    function cleanup() {
+      stdin.off("data", onData);
+      stdin.setRawMode(Boolean(wasRaw));
+      stdin.pause();
+    }
+
+    function onData(chunk) {
+      const text = String(chunk);
+      if (text === "\u0003") {
+        stdout.write("\n");
+        cleanup();
+        process.exit(130);
+      }
+      if (text === "\r" || text === "\n" || text === "\u0004") {
+        stdout.write("\n");
+        cleanup();
+        resolve(value);
+        return;
+      }
+      if (text === "\u007f" || text === "\b") {
+        if (value.length) {
+          value = value.slice(0, -1);
+          stdout.write("\b \b");
+        }
+        return;
+      }
+      value += text;
+      stdout.write("*");
+    }
+
+    stdout.write(question);
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding("utf8");
+    stdin.on("data", onData);
+  });
+}
+
+async function promptPasswordTwice() {
+  const password = await promptSecret("Create password: ");
+  if (!password || password.length < 6) {
+    throw new Error("Password must be at least 6 characters.");
+  }
+  const confirm = await promptSecret("Confirm password: ");
+  if (password !== confirm) {
+    throw new Error("Passwords do not match.");
+  }
+  return password;
+}
+
+async function callBackendJson(method, routePath, { json, token, query } = {}) {
+  const url = new URL(routePath.replace(/^\/+/, ""), `${backendUrl()}/`);
+  if (query) {
+    for (const [key, value] of Object.entries(query)) {
+      if (value != null && value !== "") url.searchParams.set(key, String(value));
+    }
+  }
+
+  const headers = { Accept: "application/json" };
+  const hasBody = json !== undefined && json !== null;
+  if (hasBody) headers["Content-Type"] = "application/json";
+  if (token) headers.Authorization = `Bearer ${token}`;
+
+  const resp = await fetch(url, {
+    method,
+    headers,
+    body: hasBody ? JSON.stringify(json) : undefined,
+  });
+  const text = await resp.text();
+  let body = {};
+  try {
+    body = text ? JSON.parse(text) : {};
+  } catch {
+    body = { raw: text };
+  }
+  return {
+    status_code: resp.status,
+    ok: resp.ok,
+    ...body,
+  };
+}
+
+function assertOk(result, action) {
+  if (result.ok) return;
+  const detail = result.detail || result.message || result.raw || `${action} failed`;
+  throw new Error(`${action} failed: ${result.status_code} ${detail}`);
+}
+
+async function verifyUnconfirmedAccount(email) {
+  process.stdout.write("This email exists but is not verified. Sending a new OTP.\n");
+  const resend = await callBackendJson("POST", "/auth/resend-otp", { json: { email } });
+  assertOk(resend, "resend OTP");
+  const otp = await promptText("Verification code: ");
+  const verified = await callBackendJson("POST", "/auth/verify-otp", { json: { email, otp } });
+  assertOk(verified, "verify OTP");
+  return verified.access_token;
+}
+
+async function authenticateTerminal() {
+  const explicitKey = argValue("--api-key", process.env.PREMAN_API_KEY || "");
+  if (explicitKey && explicitKey.startsWith("pm_live_")) {
+    const creds = {
+      api_key: explicitKey,
+      backend_url: backendUrl(),
+      user_email: argValue("--email", ""),
+      device_name: os.hostname(),
+      created_at: new Date().toISOString(),
+    };
+    saveStoredCredentials(creds);
+    return creds;
+  }
+
+  const email = (argValue("--email", "") || await promptText("Email: ")).trim().toLowerCase();
+  if (!email) throw new Error("Email is required.");
+
+  process.stdout.write(`Checking PreMan account for ${email}...\n`);
+  const account = await callBackendJson("GET", "/auth/needs-password", { query: { email } });
+  assertOk(account, "check account");
+
+  let accessToken = "";
+
+  if (!account.exists) {
+    process.stdout.write("No PreMan account found. Creating one now.\n");
+    const signup = await callBackendJson("POST", "/auth/start-signup", {
+      json: { email },
+    });
+    assertOk(signup, "start signup");
+    process.stdout.write("Verification code sent. Check your email.\n");
+    const otp = await promptText("Verification code: ");
+    const password = await promptPasswordTwice();
+    const setPassword = await callBackendJson("POST", "/auth/set-password", {
+      json: { email, otp, new_password: password },
+    });
+    assertOk(setPassword, "set password");
+    accessToken = String(setPassword.access_token || "");
+  } else if (account.needs_password) {
+    process.stdout.write("This account needs a password. Sending an OTP first.\n");
+    const resend = await callBackendJson("POST", "/auth/resend-otp", { json: { email } });
+    assertOk(resend, "resend OTP");
+    const otp = await promptText("Verification code: ");
+    const password = await promptPasswordTwice();
+    const setPassword = await callBackendJson("POST", "/auth/set-password", {
+      json: { email, otp, new_password: password },
+    });
+    assertOk(setPassword, "set password");
+    accessToken = String(setPassword.access_token || "");
+  } else {
+    const password = await promptSecret("Password: ");
+    const login = await callBackendJson("POST", "/auth/login", {
+      json: { email, password },
+    });
+    if (!login.ok && login.status_code === 403 && String(login.detail || "").toLowerCase().includes("not verified")) {
+      accessToken = await verifyUnconfirmedAccount(email);
+    } else {
+      assertOk(login, "login");
+      accessToken = String(login.access_token || "");
+    }
+  }
+
+  if (!accessToken) throw new Error("PreMan did not return an access token.");
+
+  const keyName = `PreMan MCP CLI (${os.hostname()})`;
+  const key = await callBackendJson("POST", "/api-keys", {
+    token: accessToken,
+    json: { name: keyName },
+  });
+  assertOk(key, "create API key");
+  if (!key.key || !String(key.key).startsWith("pm_live_")) {
+    throw new Error("PreMan did not return a valid API key.");
+  }
+
+  const creds = {
+    api_key: String(key.key),
+    backend_url: backendUrl(),
+    user_email: email,
+    device_name: os.hostname(),
+    created_at: new Date().toISOString(),
+  };
+  saveStoredCredentials(creds);
+  return creds;
+}
+
 function buildServerConfig() {
-  const apiKey = argValue("--api-key", process.env.PREMAN_API_KEY || API_KEY_PLACEHOLDER);
+  const apiKey = argValue("--api-key", process.env.PREMAN_API_KEY || "");
   const backend = argValue("--backend", process.env.PREMAN_BACKEND || DEFAULT_BACKEND);
   const frontend = argValue("--frontend", process.env.PREMAN_FRONTEND || DEFAULT_FRONTEND);
+  const env = {
+    PREMAN_BACKEND: backend,
+    PREMAN_FRONTEND: frontend,
+  };
+  if (apiKey) {
+    env.PREMAN_API_KEY = apiKey;
+  }
 
   return {
-    command: "npx",
-    args: ["-y", "premanmcp"],
-    env: {
-      PREMAN_API_KEY: apiKey,
-      PREMAN_BACKEND: backend,
-      PREMAN_FRONTEND: frontend,
-    },
+    command: "npm",
+    args: ["exec", "-y", "--package", "premanmcp@latest", "--", "premanmcp"],
+    env,
   };
 }
 
-function installCursorMcp() {
+async function loginCommand() {
+  const creds = await authenticateTerminal();
+  process.stdout.write(`PreMan account ready.
+
+Email: ${creds.user_email || "unknown"}
+Backend: ${creds.backend_url}
+API key: ${creds.api_key}
+Saved to: ${CREDENTIALS_FILE}
+
+You can now run:
+  npm exec -y premanmcp@latest -- install
+`);
+}
+
+async function installCursorMcp() {
   const serverName = argValue("--name", "preman");
   const projectInstall = hasFlag("--project");
+
+  if (
+    !hasFlag("--print") &&
+    !hasFlag("--skip-login") &&
+    !argValue("--api-key", "") &&
+    !process.env.PREMAN_API_KEY &&
+    !readStoredCredentials()
+  ) {
+    process.stdout.write("First, let's create or connect your PreMan account.\n");
+    await authenticateTerminal();
+    process.stdout.write("\n");
+  }
+
   const serverConfig = buildServerConfig();
 
   if (hasFlag("--print")) {
@@ -115,16 +380,17 @@ function installCursorMcp() {
   mkdirSync(path.dirname(configPath), { recursive: true });
   writeFileSync(configPath, rendered, { mode: 0o600 });
 
-  const usedPlaceholder = config.mcpServers[serverName].env.PREMAN_API_KEY === API_KEY_PLACEHOLDER;
+  const hasInlineKey = Boolean(config.mcpServers[serverName].env.PREMAN_API_KEY);
+  const hasStoredKey = Boolean(readStoredCredentials());
   process.stdout.write(`PreMan MCP installed in ${configPath}
 
 Server name: ${serverName}
 Backend: ${config.mcpServers[serverName].env.PREMAN_BACKEND}
 
 Next steps:
-1. ${usedPlaceholder ? `Replace ${API_KEY_PLACEHOLDER} with your PreMan API key in ${configPath}. Find or create one at https://app.preman.live/settings/.` : "Your PreMan API key was written to the MCP config."}
+1. ${hasInlineKey ? "Your PreMan API key was written to the MCP config." : hasStoredKey ? `Your PreMan API key is saved in ${CREDENTIALS_FILE}; the MCP server will load it automatically.` : "Run npm exec -y premanmcp@latest -- login to create/connect your account and generate an API key."}
 2. Restart Cursor or toggle the PreMan MCP server off/on.
-3. Ask your agent: "Use the PreMan MCP to convert my login endpoint into an MCP tool." Then open https://app.preman.live/ to see the session and generated MCP.
+3. Ask your agent: "Use the PreMan MCP to scan this codebase, deploy a hosted MCP, and give me the install command."
 `);
 }
 
@@ -155,14 +421,24 @@ function startServer() {
   });
 }
 
-if (command === "install") {
-  installCursorMcp();
-} else if (command === "help" || command === "--help" || command === "-h") {
-  printHelp();
-} else if (command === "start") {
-  startServer();
-} else {
-  process.stderr.write(`Unknown command: ${command}\n\n`);
-  printHelp();
-  process.exit(1);
+async function main() {
+  if (command === "login") {
+    await loginCommand();
+  } else if (command === "install") {
+    await installCursorMcp();
+  } else if (command === "help" || command === "--help" || command === "-h") {
+    printHelp();
+  } else if (command === "start") {
+    startServer();
+  } else {
+    process.stderr.write(`Unknown command: ${command}\n\n`);
+    printHelp();
+    process.exit(1);
+  }
 }
+
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`[preman] ${message}\n`);
+  process.exit(1);
+});

package/dist/auth_flow_ui.d.ts

@@ -18,6 +18,8 @@ export type ShareAuthFlowResult = {
     session_id: string;
     url: string;
     endpoint_count: number;
+    user_id: number | null;
+    auto_discoverable: boolean;
     upstream_base_url: string;
     endpoints: AuthFlowEndpoint[];
     ui: {
@@ -32,4 +34,5 @@ export declare function shareAuthFlowToUi(opts: {
     upstreamBaseUrl?: string;
     sessionId?: string;
     intent?: string;
+    apiKey?: string;
 }): Promise<ShareAuthFlowResult>;

package/dist/auth_flow_ui.js

@@ -110,6 +110,10 @@ export function buildAuthFlowEndpoints() {
 export async function shareAuthFlowToUi(opts) {
     const backend = opts.backendUrl.replace(/\/+$/, "");
     const frontend = opts.frontendUrl.replace(/\/+$/, "");
+    const apiKey = opts.apiKey?.trim();
+    if (!apiKey) {
+        throw new Error("PreMan authentication required. Run preman_login first so auth-flow sessions can stream to your dashboard.");
+    }
     const upstream = (opts.upstreamBaseUrl || backend).replace(/\/+$/, "") || backend;
     const sessionId = opts.sessionId?.trim() || crypto.randomUUID();
     const endpoints = buildAuthFlowEndpoints().map((ep) => ({
@@ -118,11 +122,16 @@ export async function shareAuthFlowToUi(opts) {
     }));
     const resp = await fetch(`${backend}/agent-sessions/${encodeURIComponent(sessionId)}/endpoints`, {
         method: "POST",
-        headers: { "Content-Type": "application/json", Accept: "application/json" },
+        headers: {
+            "Content-Type": "application/json",
+            Accept: "application/json",
+            Authorization: `Bearer ${apiKey}`,
+        },
         body: JSON.stringify({
             endpoints,
             upstream_base_url: upstream,
             intent: opts.intent || "Auth flow: signup, verify OTP, login, resend OTP",
+            client_label: "premanmcp",
         }),
     });
     const text = await resp.text();
@@ -142,11 +151,13 @@ export async function shareAuthFlowToUi(opts) {
         session_id: sid,
         url,
         endpoint_count: Number(body.endpoint_count ?? endpoints.length),
+        user_id: typeof body.user_id === "number" ? body.user_id : null,
+        auto_discoverable: Boolean(body.auto_discoverable),
         upstream_base_url: upstream,
         endpoints: buildAuthFlowEndpoints(),
         ui: {
             url,
-            note: "Open in Cursor Agent Browser. Test signup → verify-otp → login, or resend-otp. " +
+            note: "Open in Cursor Agent Browser or the Playground session list. Test signup → verify-otp → login, or resend-otp. " +
                 "Schemas are prefilled from routes/auth Pydantic models.",
         },
         related_tools: [

package/dist/server.js

@@ -11,7 +11,7 @@ import { randomUUID } from "node:crypto";
 import { MCP_PREVIEW_RESOURCE_URI, RESOURCE_URI_META_KEY, buildConversionPanelHtml, writeMcpPreviewFile, } from "./mcp-preview-panel.js";
 /**
  * Load ``PREMAN_*`` from repo JSON so project URLs win over stale **global** Cursor MCP env
- * (which often sets the wrong ``PREMAN_BACKEND``, e.g. Flow port instead of API port).
+ * (which often sets the wrong ``PREMAN_BACKEND``, e.g. app port instead of API port).
  * First match wins: ``.cursor/preman-mcp.config.json``, then ``preman-mcp.config.json`` (cwd).
  */
 function applyRepoPremanConfig() {
@@ -107,7 +107,7 @@ function normalizeFrontendBaseUrl(url) {
 /** Origin only (no path). */
 const FRONTEND_BASE = normalizeFrontendBaseUrl(FRONTEND_URL);
 /**
- * Static hosts (S3/CloudFront) often 404 on `/endpoints` because only `/` maps to index.html.
+ * Static hosts often 404 on `/endpoints` because only `/` maps to index.html.
  * Cold-load the SPA shell at `/` and pass the client route in the query so the first request always hits index.html.
  */
 const AGENT_ROUTE_PARAM = "ot_agent_route";
@@ -174,7 +174,7 @@ async function initAuth() {
     }
     const creds = await loadStoredCredentials();
     if (!creds) {
-        console.error("[PreMan] No stored credentials. Use preman_login to authenticate.");
+        console.error("[PreMan] No stored credentials. Run `npm exec -y premanmcp@latest -- login` or use preman_login to authenticate.");
         return;
     }
     const check = await verifyApiKey(creds.api_key);
@@ -187,7 +187,7 @@ async function initAuth() {
         console.error("[PreMan] Backend unreachable — using stored credentials (will verify on first call)");
     }
     else {
-        console.error("[PreMan] Stored credentials are invalid or expired. Use preman_login to re-authenticate.");
+        console.error("[PreMan] Stored credentials are invalid or expired. Run `npm exec -y premanmcp@latest -- login` or use preman_login to re-authenticate.");
         await clearCredentials();
     }
 }
@@ -195,7 +195,7 @@ async function initAuth() {
 // ── Backend proxy ─────────────────────────────────────────────────────
 function requireAuth() {
     if (!API_KEY) {
-        throw new Error("Not authenticated. Run the preman_login tool first to connect your PreMan account.");
+        throw new Error("Not authenticated. Run `npm exec -y premanmcp@latest -- login`, or use user_auth_* then preman_create_api_key, or run preman_login.");
     }
 }
 async function callBackend(toolName, args) {
@@ -273,7 +273,7 @@ function enrichEndpointsBrowserUrl(payload) {
         ui: {
             ...prevUi,
             url: buildAgentDashboardUrl("/endpoints"),
-            note: "Use Agent Browser: browser_navigate to `ui.url` to open the Flow Endpoints page (sign in if prompted). Prefer this over the site homepage.",
+            note: "Use Agent Browser: browser_navigate to `ui.url` to open the PreMan Endpoints page (sign in if prompted). Prefer this over the site homepage.",
         },
     };
 }
@@ -290,7 +290,7 @@ function withFrontendUrl(payload, path) {
                     ui: {
                         ...prevUi,
                         url: buildAgentDashboardUrl(p),
-                        note: "Open this URL in Agent Browser (browser_navigate) to see Flow — Endpoints page first (sign in if prompted). Prefer this link over the site homepage.",
+                        note: "Open this URL in Agent Browser (browser_navigate) to see the PreMan Endpoints page first (sign in if prompted). Prefer this link over the site homepage.",
                     },
                 }),
             }],
@@ -306,9 +306,9 @@ export function createServer() {
             "- **Read tools** (no side effects): get_endpoints, get_coverage, detect_drift, preman_status, list_collections, get_collection, list_runs",
             "- **Action tools** (execute tests / mutate state): test_api, generate_tests, import_collection, test_endpoint_by_id, run_tests, delete_collection",
             "- **MCP conversion tools**: discover_endpoints_from_codebase, verify_endpoints_live, mcp_preview (returns inline two-pane panel), mcp_deploy, mcp_list_deployed, mcp_mint_consumer_token, mcp_revoke_consumer_token",
-            "- **Auth (API key / PreMan)**: preman_login, preman_login_complete, preman_logout",
-            "- **Auth (app JWT — email/OTP/password on your API)**: user_auth_signup, user_auth_verify_otp, user_auth_login, user_auth_needs_password, user_auth_resend_otp, user_auth_forgot_password, user_auth_set_password, user_auth_me, user_auth_change_password, user_auth_delete_account (HTTP to PREMAN_BACKEND /auth/*; no pm_live_ key required)",
-            "- **Auth → Flow UI**: share_user_auth_flow_with_ui — pushes signup, verify-otp, login, resend-otp with JSON schemas to the Playground (no API key). Open ui.url in Agent Browser.",
+            "- **Auth (API key / PreMan)**: preman_create_api_key (JWT -> saved pm_live_ key), preman_login, preman_login_complete, preman_logout",
+            "- **Auth (app JWT — email/OTP/password on your API)**: user_auth_start_signup, user_auth_signup, user_auth_verify_otp, user_auth_login, user_auth_needs_password, user_auth_resend_otp, user_auth_forgot_password, user_auth_set_password, user_auth_me, user_auth_change_password, user_auth_delete_account (HTTP to PREMAN_BACKEND /auth/*; no pm_live_ key required)",
+            "- **Auth to PreMan Playground**: share_user_auth_flow_with_ui pushes signup, verify-otp, login, resend-otp with JSON schemas to the signed-in Playground. Requires preman_login / PREMAN_API_KEY so the session appears in the user's dashboard.",
             "",
             "## Routing — pick the right tool for what the user said",
             "- 'scan / discover / find / list my endpoints' (codebase): use discover_endpoints_from_codebase. NEVER use get_endpoints for this — that returns inventory already saved in PreMan, not source code.",
@@ -323,7 +323,7 @@ export function createServer() {
             '- Always use format="json" (the default) for structured data. Only use format="text" if the user explicitly asks for human-readable output.',
             "- Do NOT set open_ui=true unless the user asks to see the dashboard.",
             "- endpoints_dashboard is DEPRECATED. Use get_endpoints(include_sessions=true, include_collections=true) instead.",
-            "- When opening the Flow web app in a browser, use **ui.url** from tool results (SPA entry `/?agent_session=…&ot_agent_route=/endpoints`, not a bare `/endpoints` path on static hosting). Do **not** start at the site homepage without `ot_agent_route` unless the user explicitly asked for it.",
+            "- When opening the PreMan app in a browser, use **ui.url** from tool results (SPA entry `/?agent_session=...&ot_agent_route=/endpoints`, not a bare `/endpoints` path on static hosting). Do **not** start at the site homepage without `ot_agent_route` unless the user explicitly asked for it.",
             "",
             "## Common workflows",
             "1. **Discover then test**: get_endpoints -> pick untested/failing -> test_api for each.",
@@ -332,7 +332,7 @@ export function createServer() {
             "4. **Drift detection**: detect_drift with a collection + base_url -> test_api on drifted endpoints.",
             "",
             "## Auth",
-            "PreMan API tools (get_endpoints, test_api, …) need an pm_live_ key: run preman_login, then preman_login_complete.",
+            "PreMan API tools (get_endpoints, test_api, …) need an pm_live_ key. Preferred no-browser flow: user_auth_start_signup -> user_auth_set_password -> preman_create_api_key, or user_auth_login -> preman_create_api_key. Browser fallback: preman_login -> preman_login_complete.",
             "To drive the backend's **email/JWT** auth (signup, OTP, login, /auth/me), use the user_auth_* tools — they call PREMAN_BACKEND /auth/* directly and do not use the API key.",
         ].join("\n"),
     });
@@ -668,6 +668,92 @@ export function createServer() {
             });
         }
     });
+    // ── preman_create_api_key ──────────────────────────────────────────
+    // Lets agents complete signup/login entirely in the IDE:
+    // user_auth_* returns a JWT, then this tool mints and stores the pm_live_ key.
+    server.tool("preman_create_api_key", "Mint and save a PreMan pm_live_ API key using a JWT from user_auth_login, user_auth_verify_otp, or user_auth_set_password. Use this to finish account setup without opening the website.", {
+        access_token: z.string().describe("JWT returned by user_auth_login, user_auth_verify_otp, or user_auth_set_password"),
+        name: z.string().optional().describe("API key name. Defaults to this MCP device name."),
+    }, async (args) => {
+        try {
+            const name = args.name || `${os.hostname()} MCP`;
+            const keyResp = await fetch(`${BACKEND_URL}/api-keys`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${args.access_token}`,
+                },
+                body: JSON.stringify({ name }),
+            });
+            const keyText = await keyResp.text();
+            let keyData;
+            try {
+                keyData = keyText ? JSON.parse(keyText) : {};
+            }
+            catch {
+                keyData = { raw: keyText };
+            }
+            if (!keyResp.ok) {
+                throw new Error(`Create API key failed: ${keyResp.status} ${String(keyData.detail ?? keyData.raw ?? keyText)}`);
+            }
+            const apiKey = String(keyData.key || "");
+            if (!apiKey.startsWith("pm_live_")) {
+                throw new Error("Create API key response did not include a valid pm_live_ key.");
+            }
+            API_KEY = apiKey;
+            let email;
+            try {
+                const meResp = await fetch(`${BACKEND_URL}/auth/me`, {
+                    headers: { Authorization: `Bearer ${args.access_token}` },
+                });
+                if (meResp.ok) {
+                    const me = await meResp.json();
+                    email = typeof me.email === "string" ? me.email : undefined;
+                }
+            }
+            catch {
+                // Email is nice to have; the API key is the important credential.
+            }
+            await saveCredentials({
+                api_key: apiKey,
+                backend_url: BACKEND_URL,
+                user_email: email,
+                device_name: name,
+                created_at: new Date().toISOString(),
+            });
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            status: "authenticated",
+                            email,
+                            api_key: apiKey,
+                            key_prefix: keyData.key_prefix,
+                            key_id: keyData.id,
+                            saved_to: CREDENTIALS_FILE,
+                            message: "PreMan account and MCP credentials are ready. You can now scan endpoints, preview, deploy, test, and list hosted MCPs from the agent.",
+                            _agent_hints: {
+                                next_actions: [
+                                    "Call discover_endpoints_from_codebase to scan this project.",
+                                    "Call verify_endpoints_live if you have a base URL to test against.",
+                                    "Call mcp_preview, then mcp_deploy to create a hosted MCP.",
+                                ],
+                                related_tools: ["discover_endpoints_from_codebase", "verify_endpoints_live", "mcp_preview", "mcp_deploy"],
+                            },
+                        }),
+                    }],
+            };
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                next_actions: [
+                    "Get a fresh JWT by calling user_auth_login, user_auth_verify_otp, or user_auth_set_password.",
+                    "Or run `npm exec -y premanmcp@latest -- login` in the terminal.",
+                ],
+                related_tools: ["user_auth_login", "user_auth_verify_otp", "user_auth_set_password"],
+            });
+        }
+    });
     // ── preman_login ─────────────────────────────────────────────────
     server.tool("preman_login", "Authenticate with PreMan. Starts a one-time device authorization flow and returns a verification_url. Use Cursor Agent Browser (browser_navigate to verification_url) or open it manually to approve. Then run preman_login_complete with device_code.", {
         device_name: z.string().optional().describe("Friendly name for this device (e.g. 'My MacBook')"),
@@ -774,7 +860,7 @@ export function createServer() {
                                     endpoints_page_url: buildAgentDashboardUrl("/endpoints"),
                                     _agent_hints: {
                                         next_actions: [
-                                            `browser_navigate to the URL in endpoints_page_url to open Flow on the Endpoints page (sign in to the web app if needed).`,
+                                            `browser_navigate to the URL in endpoints_page_url to open PreMan on the Endpoints page (sign in to the web app if needed).`,
                                             "Call get_endpoints to see your registered API endpoints.",
                                             "Call test_api to test an endpoint.",
                                             "Call import_collection to import a Postman/OpenAPI spec.",
@@ -814,7 +900,7 @@ export function createServer() {
                             backend_url: BACKEND_URL,
                             frontend_base_url: FRONTEND_BASE,
                             endpoints_page_url: buildAgentDashboardUrl("/endpoints"),
-                            message: "Not authenticated. Run preman_login to connect your account.",
+                            message: "Not authenticated. Run `npm exec -y premanmcp@latest -- login`, or use user_auth_* then preman_create_api_key, or run preman_login.",
                         }),
                     }],
             };
@@ -829,7 +915,7 @@ export function createServer() {
                             backend_url: BACKEND_URL,
                             frontend_base_url: FRONTEND_BASE,
                             endpoints_page_url: buildAgentDashboardUrl("/endpoints"),
-                            message: "Stored API key is no longer valid. Run preman_login to re-authenticate.",
+                            message: "Stored API key is no longer valid. Run `npm exec -y premanmcp@latest -- login`, or use user_auth_* then preman_create_api_key, or run preman_login.",
                         }),
                     }],
             };
@@ -846,7 +932,7 @@ export function createServer() {
                         endpoints_page_url: buildAgentDashboardUrl("/endpoints"),
                         _agent_hints: {
                             next_actions: [
-                                "browser_navigate to `endpoints_page_url` (SPA shell + ot_agent_route) to open Flow on the Endpoints page (sign in if prompted), then call get_endpoints.",
+                                "browser_navigate to `endpoints_page_url` (SPA shell + ot_agent_route) to open PreMan on the Endpoints page (sign in if prompted), then call get_endpoints.",
                                 "Call get_endpoints to see registered API endpoints.",
                                 "Call test_api to test an endpoint.",
                             ],
@@ -876,7 +962,7 @@ export function createServer() {
     });
     // ── App user auth (JWT) — same server as preman-local / PREMAN_BACKEND
     registerUserAuthFlowTools(server, BACKEND_URL);
-    server.tool("share_user_auth_flow_with_ui", "Stream signup, verify-otp, login, and resend-otp (send OTP) into the Flow Playground with request/response JSON schemas. No API key required. Use after discover or when the user asks to see auth endpoints in the UI. Pair with user_auth_* tools to execute flows.", {
+    server.tool("share_user_auth_flow_with_ui", "Stream signup, verify-otp, login, and resend-otp (send OTP) into the signed-in PreMan Playground with request/response JSON schemas. Requires preman_login or PREMAN_API_KEY so the session appears in the user's dashboard immediately. Pair with user_auth_* tools to execute flows.", {
         upstream_base_url: z
             .string()
             .optional()
@@ -888,6 +974,7 @@ export function createServer() {
         intent: z.string().optional().describe("Label shown in the Playground session list."),
     }, async (args) => {
         try {
+            requireAuth();
             const result = await shareAuthFlowToUi({
                 backendUrl: BACKEND_URL,
                 frontendUrl: FRONTEND_BASE,
@@ -896,6 +983,7 @@ export function createServer() {
                     : undefined,
                 sessionId: typeof args.session_id === "string" ? args.session_id : undefined,
                 intent: typeof args.intent === "string" ? args.intent : undefined,
+                apiKey: API_KEY || undefined,
             });
             return {
                 content: [{ type: "text", text: JSON.stringify(result) }],
@@ -948,7 +1036,7 @@ export function createServer() {
             });
         }
     });
-    server.tool("share_endpoints_with_ui", "Push discovered or verified endpoints into the PreMan Flow Playground so the user can see them, test them, and convert selected endpoints into hosted MCP tools. Use this after verify_endpoints_live or when the user explicitly asks to stream endpoints to the UI.", {
+    server.tool("share_endpoints_with_ui", "Push discovered or verified endpoints into the PreMan Playground so the user can see them, test them, and convert selected endpoints into hosted MCP tools. Use this after verify_endpoints_live or when the user explicitly asks to stream endpoints to the UI.", {
         endpoints: z.array(z.any()).describe("Endpoints to push. Each item should include method plus path/path_template/url; include schemas when available."),
         upstream_base_url: z.string().optional().describe("Default upstream base URL for testing and MCP generation, e.g. http://127.0.0.1:8000 or https://api.example.com"),
         intent: z.string().optional().describe("Short label for the session, e.g. 'Login endpoint' or 'Auth endpoints'"),
@@ -962,13 +1050,13 @@ export function createServer() {
             return toolError(e.message, inferErrorCode(e.message), {
                 next_actions: [
                     "Make sure PREMAN_API_KEY is set or run preman_login, then retry.",
-                    "If the Flow UI opens but is empty, confirm PREMAN_BACKEND points to the same backend that received this push.",
+                    "If the PreMan Playground opens but is empty, confirm PREMAN_BACKEND points to the same backend that received this push.",
                 ],
                 related_tools: ["verify_endpoints_live", "mcp_preview", "preman_status"],
             });
         }
     });
-    server.tool("mcp_preview", "Pick endpoints matching an intent, generate a tool-schema preview, and automatically share the selected endpoints into the PreMan Flow Playground session so the user can see/test/deploy them in the UI. Also writes the same two-pane HTML to preman-mcp/mcp-preview-last.html and returns preview_file_url — use Cursor Simple Browser or `node preman-mcp/scripts/open-cursor-preview.mjs` if the inline MCP app panel does not appear. LLM selection when OPENAI_API_KEY is set on the backend; else keyword match.", {
+    server.tool("mcp_preview", "Pick endpoints matching an intent, generate a tool-schema preview, and automatically share the selected endpoints into the PreMan Playground session so the user can see/test/deploy them in the UI. Also writes the same two-pane HTML to preman-mcp/mcp-preview-last.html and returns preview_file_url; use Cursor Simple Browser or `node preman-mcp/scripts/open-cursor-preview.mjs` if the inline MCP app panel does not appear. Endpoint selection uses deterministic keyword matching.", {
         intent: z.string().describe("Free text like 'auth endpoints' or 'everything related to orders'"),
         endpoints: z.array(z.any()).describe("Candidate endpoints (typically the confirmed bucket from verify_endpoints_live)"),
         upstream_base_url: z.string().optional().describe("Target business API base URL. Usually inferred from verify_endpoints_live results. Do not use PREMAN_BACKEND / api.preman.live unless the user's API is actually the PreMan backend."),
@@ -1014,7 +1102,7 @@ export function createServer() {
                         : buildAgentDashboardUrl("/endpoints"),
                 },
                 _how_to_see_the_ui: [
-                    "The selected endpoints were automatically shared into the Flow Playground session. Open ui.url or _agent_session.dashboard_url to see them.",
+                    "The selected endpoints were automatically shared into the PreMan Playground session. Open ui.url or _agent_session.dashboard_url to see them.",
                     "Cursor may not show the embedded MCP app (no new tab is opened by default).",
                     "Run `node preman-mcp/scripts/open-cursor-preview.mjs` from the repo root; it copies the http:// URL to the clipboard (macOS) and tries cursor:// + vscode:// Simple Browser handlers.",
                     "If no tab appears: Cmd+Shift+P → “Simple Browser: Show” → paste the http://127.0.0.1:… URL from the script output. In the integrated terminal, Cmd+Click that URL may open the in-editor browser.",

package/dist/user_auth_flow.js

@@ -58,6 +58,28 @@ async function callAuthJson(base, method, path, opts) {
  */
 export function registerUserAuthFlowTools(server, backendUrl) {
     const base = normalizeBase(backendUrl);
+    server.tool("user_auth_start_signup", "Start signup with email only. Sends an OTP; next call user_auth_set_password with email, OTP, and new password. Uses POST /auth/start-signup on PREMAN_BACKEND (no API key).", {
+        email: z.string().describe("User email"),
+    }, async (args) => {
+        try {
+            const r = await callAuthJson(base, "POST", "/auth/start-signup", {
+                json: { email: args.email },
+            });
+            if (!r.ok) {
+                return toolError(String(r.detail ?? r.message ?? "start signup failed"), r.status_code === 400 ? "invalid_input" : "backend_error", {
+                    next_actions: ["If email exists, use user_auth_login or user_auth_resend_otp."],
+                    related_tools: ["user_auth_set_password", "user_auth_login"],
+                });
+            }
+            return jsonOk(r);
+        }
+        catch (e) {
+            const m = e instanceof Error ? e.message : String(e);
+            return toolError(m, "backend_error", {
+                next_actions: ["Ensure PREMAN_BACKEND is running and JWT_SECRET is set on the server."],
+            });
+        }
+    });
     server.tool("user_auth_signup", "Register with email and password. Sends an OTP; next call user_auth_verify_otp. Uses POST /auth/signup on PREMAN_BACKEND (no API key).", {
         email: z.string().describe("User email"),
         password: z.string().describe("Password (min 6 characters on the server)"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "premanmcp",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "Turn APIs into agent-callable MCP tools with auth, testing, and audit logs",
   "type": "module",
   "bin": {