premanmcp 0.10.7 → 0.12.0

package/README.md

@@ -4,14 +4,24 @@ Turn your APIs into MCP tools that coding agents can discover, call, test, and a
 
 PreMan is agent-first API infrastructure. It lets backend teams expose endpoints to AI coding agents through MCP, add an auth layer around those tools, and see exactly which agent called what.
 
-## Connect
+## Start
+
+```bash
+npm exec -y premanmcp@latest -- onboard
+```
+
+Create the account, verify the email, and get the PreMan app installed and opened
+already signed in. A bare `preman` in a terminal does the same thing.
+
+## Connect a coding agent
 
 ```bash
 npm exec -y premanmcp@latest -- connect
 ```
 
-Pick your coding agent from the list — Cursor, Claude Code, or Codex — and PreMan
-writes that agent's MCP config for you. No hand-edited config anywhere.
+Optional, and separate from starting out. Pick your coding agent from the list — Cursor,
+Claude Code, or Codex — and PreMan writes that agent's MCP config for you. No hand-edited
+config anywhere.
 
 Local development form:
 
@@ -82,10 +92,18 @@ preman github                      # or connect it in the dashboard
 preman status                      # which of those are done
 ```
 
-`preman onboard` (or `setup`) is the prompted walk through all of it — sign in, coding
-agent, endpoints, runner, GitHub, AWS, Slack — one question per step, `b` to go back, and a
-summary at the end. `connect --guide` runs the old full pass inside connect itself:
-discovery, a first test, the runner, the desktop app and the integration prompts.
+`preman onboard` (or `setup`, or a bare `preman` in a terminal) is what someone starting
+out runs: create the account and verify the email, then install the PreMan app and open it
+already signed in, then GitHub, AWS, Slack — one question per step, `b` to go back, and a
+summary at the end. Connecting a coding agent is no longer part of starting out; run
+`preman connect` when you actually want one wired into an IDE. `connect --guide` still runs
+the full pass inside connect itself: discovery, a first test, the runner, the desktop app
+and the integration prompts.
+
+The app opens signed in because the CLI leaves the key it just minted in
+`~/.preman/desktop-session.json`, which the app reads once and deletes. An app too old to
+look for it, or a machine that is not macOS, falls back to signing in on the app's own
+login screen with the account you just created.
 
 Useful flags: `--agent cursor|claude-code|codex` skips the picker, `--project` writes
 project-local config, `--print` shows the config without writing it, `--no-hook` leaves

package/bin/api_tools.js

@@ -9,6 +9,7 @@
 import { readFileSync } from "node:fs";
 
 import { callBackendJson, cliInvocation, makeArgs, resolveApiKey } from "./shared.js";
+import { printPlayground } from "./desktop.js";
 
 export const ENDPOINTS_HELP = `
 Endpoints:
@@ -144,6 +145,13 @@ export async function endpointsCommand(commandArgs) {
     if (requests.length) {
       process.stdout.write(`runnable as: ${requests.join(", ")}\n`);
     }
+    const url = result.ui?.url || result.url;
+    printPlayground(url);
+    if (result.campaign?.id) {
+      process.stdout.write(
+        `test campaign ${result.campaign.id}: ${result.campaign.queued || 0} queued, ${result.campaign.skipped || 0} skipped\n`,
+      );
+    }
     return undefined;
   }
 

package/bin/cli.js

@@ -22,7 +22,6 @@ import {
   CONNECT_HELP,
   DISPATCH_HELP,
   connectCommand,
-  discoverEndpoints,
   dispatchCommand,
   resolveAgentForPairing,
   writeCursorConfig,
@@ -39,7 +38,7 @@ import { STATUS_HELP, statusCommand } from "./status.js";
 import { HOOK_HELP, hookCommand, scheduleHookRepair } from "./hook.js";
 import { RUNNER_HELP, runnerCommand } from "./runner.js";
 import { VERIFY_HELP, verifyCommand } from "./verify.js";
-import { DESKTOP_HELP, installDesktopCommand } from "./desktop.js";
+import { DESKTOP_HELP, installDesktopCommand, openDesktopSignedIn } from "./desktop.js";
 import { ACCOUNT_HELP, doctorCommand, loginBrowser, logoutCommand, watchCommand } from "./account.js";
 import {
   CREDENTIALS_FILE,
@@ -57,8 +56,11 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.join(__dirname, "..");
 
 const args = process.argv.slice(2);
+// A bare `preman` in a terminal is someone starting out, so it runs setup:
+// account first, then the app. Piped or redirected (no TTY) it is an MCP host
+// launching the server, which must stay the behaviour for `start`.
 const command = args.length === 0 && process.stdin.isTTY
-  ? "connect"
+  ? "onboard"
   : args[0] === "--help" || args[0] === "-h"
   ? "help"
   : args[0] && !args[0].startsWith("-")
@@ -89,8 +91,8 @@ function printHelp() {
     ["runner start|status|stop", "Run PreMan's queued agent work on this machine"],
     ["doctor", "Diagnose credentials, backend, target, integrations"],
     ["install-desktop", "Download and install the PreMan desktop app"],
-    ["onboard", "Sign in, then agent, endpoints, runner, GitHub, AWS, Slack"],
-    ["connect [options]", "Pick a coding agent and connect it"],
+    ["onboard", "Create an account, install the app signed in, then integrations"],
+    ["connect [options]", "Pick a coding agent and connect it (optional)"],
     ["dispatch [options]", "Let PreMan start agent runs for you"],
     ["aws | github | slack", "Connect one integration on its own"],
     ["login [--browser]", "Create/login to PreMan from the terminal"],
@@ -254,14 +256,13 @@ async function main() {
   } else if (command === "dispatch") {
     await dispatchCommand(commandArgs);
   } else if (command === "onboard" || command === "setup") {
-    // makeArgs/authenticateTerminal/connectCommand are injected rather than
+    // makeArgs/authenticateTerminal/the desktop pair are injected rather than
     // imported there, so integrations.js stays free of a cycle back into the CLI.
     await onboardCommand(commandArgs, {
       makeArgs,
       authenticateTerminal,
-      connectCommand,
-      discoverEndpoints,
-      runnerCommand,
+      installDesktop: installDesktopCommand,
+      openDesktopSignedIn,
     });
   } else if (command === "aws") {
     await awsCommand(makeArgs(commandArgs));

package/bin/connect/guide.js

@@ -12,7 +12,7 @@ import path from "node:path";
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { callTool as callPremanTool, printTestSummary } from "../api_tools.js";
-import { installDesktopCommand } from "../desktop.js";
+import { installDesktopCommand, printPlayground } from "../desktop.js";
 import { hookStatus, installHook } from "../hook.js";
 import { MARK, awsCommand, githubCommand, slackCommand } from "../integrations.js";
 import { confirmRunnerOnline, pairingIsLive, readRunnerState, registerRunner, runnerIsAlive, startBackground } from "../runner.js";
@@ -198,6 +198,18 @@ export async function discoverEndpoints(
     process.stdout.write(
       `${MARK.ok()} ${after.registered} endpoint(s) · ${after.runnable} runnable\n`
     );
+    try {
+      const listed = await callPremanTool(args, "get_endpoints", {
+        limit: 100,
+        include_schemas: true,
+      });
+      const share = await callPremanTool(args, "share_endpoints_with_ui", {
+        endpoints: listed.endpoints || [],
+      });
+      printPlayground(share.ui?.url || share.url);
+    } catch {
+      // Mapping succeeded; a missing Playground link must not look like discovery failed.
+    }
     return after;
   } catch (error) {
     process.stdout.write(`${MARK.fail()} Could not read your endpoints: ${error.message}\n`);

package/bin/desktop.js

@@ -11,13 +11,13 @@
  * has to do.
  */
 
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
-import { cliInvocation, makeArgs } from "./shared.js";
+import { CREDENTIALS_DIR, cliInvocation, makeArgs } from "./shared.js";
 
 export const DESKTOP_HELP = `
 Install-desktop options:
@@ -29,9 +29,88 @@ Install-desktop options:
 
 const RELEASES_BASE = "https://github.com/PreMan-Inc/PreMan-Desktop/releases";
 const RELEASE_API = "https://api.github.com/repos/PreMan-Inc/PreMan-Desktop/releases/latest";
-const APP_NAME = "PreMan.app";
+export const APP_NAME = "PreMan.app";
 const DOWNLOAD_TIMEOUT_MS = 300_000;
 
+/**
+ * Where the desktop app looks for a session the CLI just established.
+ *
+ * The key travels through a file rather than the `preman://` URL because a URL
+ * is handed to LaunchServices, which records it; the file sits in the directory
+ * that already holds the same key, with the same 0600 mode, so this adds no new
+ * class of exposure. The app deletes it on read, which is what makes it
+ * single-use -- the CLI cannot know whether an installed app is new enough to
+ * consume it, so expiry is enforced on the reading side.
+ */
+export const DESKTOP_SESSION_FILE = path.join(CREDENTIALS_DIR, "desktop-session.json");
+
+export function installedAppPath(destination = "/Applications") {
+  return path.join(destination, APP_NAME);
+}
+
+export function desktopAppInstalled(destination = "/Applications") {
+  return process.platform === "darwin" && existsSync(installedAppPath(destination));
+}
+
+/**
+ * Hand the account the CLI just signed in to over to the desktop app.
+ *
+ * Returns what actually happened rather than a boolean, because the caller has
+ * something different to say in each case: an app that is not installed is not
+ * a failure, it is the fallback where the customer signs in themselves.
+ */
+export function writeDesktopSession(creds) {
+  const apiKey = String(creds?.api_key || "").trim();
+  if (!apiKey.startsWith("pm_live_")) return { state: "no-key" };
+  mkdirSync(CREDENTIALS_DIR, { recursive: true, mode: 0o700 });
+  writeFileSync(
+    DESKTOP_SESSION_FILE,
+    `${JSON.stringify({ api_key: apiKey, user_email: creds?.user_email ?? null, created_at: new Date().toISOString() }, null, 2)}\n`,
+    { mode: 0o600 }
+  );
+  return { state: "written", path: DESKTOP_SESSION_FILE };
+}
+
+/**
+ * Install-or-not aside, get the customer into the app signed in.
+ *
+ * The session is written before the app is launched so a cold start finds it on
+ * first read, rather than racing a window that is already loading.
+ */
+export function openDesktopSignedIn(creds, { destination = "/Applications" } = {}) {
+  if (!desktopAppInstalled(destination)) {
+    return { state: "not-installed" };
+  }
+  const handoff = writeDesktopSession(creds);
+  spawn("open", ["-a", "PreMan"], { stdio: "ignore", detached: true }).unref();
+  return { state: handoff.state === "written" ? "opened-signed-in" : "opened", handoff: handoff.state };
+}
+
+/**
+ * Open a Playground session URL in PreMan.app on macOS when it is installed.
+ * Windows/Linux (and Mac without the app) get the website URL printed instead.
+ */
+export function openPlayground(url) {
+  const target = String(url || "").trim();
+  if (!target) return "none";
+  const app = path.join("/Applications", APP_NAME);
+  if (process.platform === "darwin" && existsSync(app)) {
+    spawn("open", ["-a", "PreMan", target], { stdio: "ignore", detached: true }).unref();
+    return "desktop";
+  }
+  return "web";
+}
+
+export function printPlayground(url) {
+  const target = String(url || "").trim();
+  if (!target) return;
+  const where = openPlayground(target);
+  process.stdout.write(`Watch it: ${target}\n`);
+  if (where === "desktop") {
+    process.stdout.write("Opened in PreMan desktop\n");
+  }
+}
+
 export function dmgUrl(arch) {
   return `${RELEASES_BASE}/latest/download/PreMan-mac-${arch}.dmg`;
 }
@@ -200,8 +279,8 @@ export async function installDesktopCommand(commandArgs = []) {
     chmodSync(target, 0o755);
 
     process.stdout.write(
-      `\nInstalled ${target}\n\nNext: open PreMan and it will pair with this account.\n` +
-        `Then run \`${cliInvocation()} status\` to see endpoint health.\n`
+      `\nInstalled ${target}\n\nNext: open PreMan and sign in with the account you use here.\n` +
+        `\`${cliInvocation()} onboard\` installs it and opens it already signed in.\n`
     );
     return { state: "installed", version, arch, path: target };
   } finally {

package/bin/integrations.js

@@ -337,17 +337,6 @@ export async function slackCommand(args) {
 // The guided run
 // ---------------------------------------------------------------------------
 
-/**
- * Why a step that needs a connected agent cannot run on its own.
- *
- * Both of these drive the agent `connect` just linked, so skipping that step
- * leaves them without one -- which is a thing to say plainly, with the command
- * that does it later, rather than a stack trace about a missing id.
- */
-function needsAgent(command) {
-  return `no coding agent connected yet -- run '${cliInvocation()} connect', then '${cliInvocation()} ${command}'`;
-}
-
 /** "yes" | "no" | "back" -- back only offered once there is somewhere to go. */
 async function askStep(question, { assumeYes, canGoBack }) {
   if (assumeYes) return "yes";
@@ -368,7 +357,7 @@ async function askStep(question, { assumeYes, canGoBack }) {
  */
 export async function onboardCommand(
   commandArgs,
-  { makeArgs, authenticateTerminal, connectCommand, discoverEndpoints, runnerCommand }
+  { makeArgs, authenticateTerminal, installDesktop, openDesktopSignedIn }
 ) {
   const args = makeArgs(commandArgs);
   const assumeYes = args.has("--yes");
@@ -378,32 +367,30 @@ export async function onboardCommand(
   const creds = await authenticateTerminal(args);
   connected(`Signed in as ${creds.user_email || "your account"}.`);
 
-  // Which agent the endpoints and runner steps drive. `connect` decided it, by
-  // detection or by asking, and this is the answer rather than a second prompt.
-  let linked = null;
-
   const steps = [
     {
-      name: "coding agent",
-      question: "Connect your coding agent?",
+      name: "PreMan app",
+      question: "Install the PreMan app and open it signed in?",
       run: async () => {
-        linked = (await connectCommand([...commandArgs, "--skip-login"])) || null;
-      },
-    },
-    {
-      name: "endpoints",
-      question: "Map this repository's endpoints?",
-      run: () => {
-        if (!linked?.agent) throw new Error(needsAgent("endpoints discover"));
-        return discoverEndpoints(args, linked.agent, linked.serverName);
-      },
-    },
-    {
-      name: "runner",
-      question: "Let PreMan run your agent here when it finds something to fix?",
-      run: () => {
-        if (!linked?.agent) throw new Error(needsAgent("runner start --background"));
-        return runnerCommand(["start", "--background", "--agent", linked.agent.id]);
+        const installed = await installDesktop([...commandArgs]);
+        if (installed?.state === "unsupported") {
+          // Not a failure: the download link has already been printed, and the
+          // account this step exists to create is finished either way.
+          process.stdout.write("Sign in there with the account you just used.\n");
+          return;
+        }
+        const opened = openDesktopSignedIn(creds);
+        if (opened.state === "opened-signed-in") {
+          process.stdout.write("Opened PreMan, signed in as this account.\n");
+        } else if (opened.state === "not-installed") {
+          process.stdout.write(
+            "PreMan is not in /Applications yet \u2014 open it once installed and sign in.\n"
+          );
+        } else {
+          // The app is there but the session could not be handed over, so say so
+          // rather than let the customer wonder why they are at a login screen.
+          process.stdout.write("Opened PreMan \u2014 sign in with the account you just used.\n");
+        }
       },
     },
     { name: "GitHub", question: "Connect GitHub?", run: () => githubCommand(args) },
@@ -464,8 +451,9 @@ export async function onboardCommand(
 
 export const INTEGRATIONS_HELP = `
 Setup options:
-  preman onboard              Sign in, then agent, endpoints, runner, GitHub,
-                              AWS and Slack, one prompt per step
+  preman onboard              Create or sign in to an account, install the
+                              PreMan app signed in, then GitHub, AWS and Slack,
+                              one prompt per step
   preman aws                  Connect an AWS account and stream a log group
   preman github               Install the PreMan GitHub App
   preman slack                Add PreMan to a Slack workspace

package/dist/server.js

@@ -381,7 +381,8 @@ export function createServer() {
             "",
             "## Tool taxonomy",
             "- **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, generate_endpoint_tests, run_stress_test, import_collection, test_endpoint_by_id, register_discovered_endpoints, run_tests, delete_collection",
+            "- **Action tools** (execute tests / mutate state): test_api, generate_tests, generate_endpoint_tests, run_stress_test, start_test_campaign, import_collection, test_endpoint_by_id, register_discovered_endpoints, run_tests, delete_collection",
+            "- **Create-then-delete contracts**: propose_lifecycle_contracts (propose a POST/DELETE pairing), approve_lifecycle_contracts (user decision — ask first)",
             "- **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_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)",
@@ -396,7 +397,8 @@ export function createServer() {
             "- 'migrate / move / switch from Postman', 'bring my Postman workspace over': migrate_from_postman — it imports AND creates scheduled suites, environments and alerts in one call. Prefer it over import_collection whenever the user frames this as leaving Postman.",
             "- 'generate tests for endpoint X' / 'write unit tests for X and run them': generate_endpoint_tests (set include_code=true and write the returned code_artifacts to disk when the user wants test files).",
             "- 'stress / load test X': run_stress_test. Read-only unless the user explicitly authorises writes — never set allow_writes yourself.",
-            "- After discover_endpoints_from_codebase, call register_discovered_endpoints with the JSON array it asked for, then verify_endpoints_live to confirm they respond.",
+            "- After discover_endpoints_from_codebase, call register_discovered_endpoints with the JSON array it asked for. That streams endpoints to the Playground and starts a read-safe test campaign. Then verify_endpoints_live if you need a live probe.",
+            "- 'why aren't my POSTs tested?' / 'test the creates too': POSTs are skipped because nothing undoes them. Read the code, pair each POST with the DELETE that reverses it via propose_lifecycle_contracts, then ask the user to approve. Approve once and every campaign creates and deletes a real record. Never call approve_lifecycle_contracts without the user saying yes.",
             "- App-auth flows (signup, OTP, login, change_password) live under the user_auth_* tools and do not need an pm_live_ key.",
             "- PREMAN_BACKEND / backend_url is the PreMan control plane. It is NOT the target API upstream for a generated MCP unless the user's own API is PreMan. Prefer base_url from verify_endpoints_live results.",
             "",
@@ -541,7 +543,7 @@ export function createServer() {
         }
     });
     // ── register_discovered_endpoints ─────────────────────────────────
-    server.tool("register_discovered_endpoints", "Save discovered endpoints into PreMan and set them up as runnable requests. Use after discover_endpoints_from_codebase with the JSON array its brief asked you to build; then call verify_endpoints_live to confirm they respond.", {
+    server.tool("register_discovered_endpoints", "Save discovered endpoints into PreMan, stream them to the Playground, and start a read-safe test campaign. Use after discover_endpoints_from_codebase. Mutating endpoints stay skipped until start_test_campaign(allow_writes=true).", {
         endpoints: z.array(z.record(z.any())).optional().describe("Discovery-shaped endpoint objects (method, path_template, schemas, confidence, …); max 100"),
         endpoint_ids: z.array(z.string()).optional().describe("Alternatively, existing registry ids to set up as runnable requests"),
         project_id: z.string().optional().describe("Scope registration to a project"),
@@ -550,12 +552,64 @@ export function createServer() {
     }, async (args) => {
         try {
             const result = await callBackend("register_discovered_endpoints", args);
-            return withFrontendUrl(result, "/endpoints");
+            return withFrontendUrl(result, "/try");
         }
         catch (e) {
             return toolError(e.message, inferErrorCode(e.message), {
                 next_actions: ["Run discover_endpoints_from_codebase first and pass its endpoints array here."],
-                related_tools: ["discover_endpoints_from_codebase", "verify_endpoints_live"],
+                related_tools: ["discover_endpoints_from_codebase", "start_test_campaign", "verify_endpoints_live"],
+            });
+        }
+    });
+    server.tool("start_test_campaign", "Fan out tests across registered endpoints: functional scenarios, GET-only stress, and security-lite negatives (missing auth / empty body). Read-only by default. Not a scanner or exploit runner.", {
+        endpoint_ids: z.array(z.string()).optional().describe("Registry ids from register_discovered_endpoints"),
+        allow_writes: z.boolean().optional().default(false).describe("Permit POST/PUT/PATCH functional jobs; DELETE stays skipped"),
+    }, async (args) => {
+        try {
+            const result = await callBackend("start_test_campaign", args);
+            return withFrontendUrl(result, "/try");
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                next_actions: ["Call register_discovered_endpoints first, then pass its endpoint_ids."],
+                related_tools: ["register_discovered_endpoints", "get_endpoints"],
+            });
+        }
+    });
+    // ── create-then-delete contracts ──────────────────────────────────
+    server.tool("propose_lifecycle_contracts", "Propose that a POST be tested for real by deleting what it creates. You read the customer's routes and response models, so you know which DELETE undoes which POST and where the new id appears. PreMan re-checks eligibility itself: billing-, auth- and notification-shaped creates are always rejected because a DELETE cannot claw back money or unsend an email. Proposals do nothing until the user approves them.", {
+        contracts: z
+            .array(z.object({
+            create_endpoint_id: z.string().describe("Registry id of the POST"),
+            cleanup_endpoint_id: z.string().describe("Registry id of the DELETE that undoes it"),
+            id_source: z.string().optional().describe("Where the new id sits in the create response, e.g. 'json.id' or 'json.data.id'"),
+            evidence: z.string().optional().describe("Why this pairing is correct (route/model you read)"),
+        }))
+            .describe("Pairings to propose; max 100"),
+    }, async (args) => {
+        try {
+            const result = await callBackend("propose_lifecycle_contracts", args);
+            return withFrontendUrl(result, "/try");
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                next_actions: ["Register the endpoints first so both ids exist, then propose the pairing."],
+                related_tools: ["register_discovered_endpoints", "approve_lifecycle_contracts"],
+            });
+        }
+    });
+    server.tool("approve_lifecycle_contracts", "Approve (or reject) create-then-delete contracts. ASK THE USER FIRST — never approve on their behalf. An approved create runs for real on every campaign from then on, teardown included; the teardown is scoped to the id that run just created and can never delete anything else.", {
+        contract_ids: z.array(z.string()).describe("Ids from propose_lifecycle_contracts or register_discovered_endpoints' lifecycle_proposals"),
+        approve: z.boolean().optional().default(true).describe("False records a rejection so the pairing stops being re-proposed"),
+    }, async (args) => {
+        try {
+            const result = await callBackend("approve_lifecycle_contracts", args);
+            return withFrontendUrl(result, "/try");
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                next_actions: ["Confirm with the user which POST endpoints they want exercised for real, then retry."],
+                related_tools: ["propose_lifecycle_contracts", "start_test_campaign"],
             });
         }
     });
@@ -1278,6 +1332,90 @@ export function createServer() {
             });
         }
     });
+    // ── Collections test generation ────────────────────────────────────
+    // The dashboard's Generate Tests / Review flagged / Setup fixtures /
+    // Enrich with agent buttons, so an agent can run them without clicking.
+    server.tool("generate_saved_tests", "Generate scheduled test suites for every endpoint already saved in a PreMan workspace. This is the dashboard's Collections 'Generate Tests' button: it clones the workspace's connected GitHub repository, matches the discovered routes onto the saved endpoints by method and path, and writes heuristic cases onto the ones it matches. No model is involved, so nothing invents a body for a DELETE. Write, destructive, low-confidence, and path-parameter routes come back flagged and disabled — clear them with review_generated_tests. This is not generate_tests, which writes cases for a single endpoint you describe.", {
+        action: z
+            .enum(["generate", "status"])
+            .optional()
+            .describe("generate (default) runs the scan; status is read-only counts"),
+        integration_id: z
+            .string()
+            .optional()
+            .describe("Connected repo to scan. Omit to use the one with the most synced endpoints."),
+        workspace_id: z.string().optional().describe("Defaults to the caller's own workspace"),
+    }, async (args) => {
+        try {
+            const result = await callBackend("generate_saved_tests", args);
+            return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                next_actions: [
+                    "Connect a GitHub repository to this workspace in Settings → Integrations, then retry.",
+                ],
+                related_tools: ["review_generated_tests", "setup_test_fixtures", "enrich_generated_tests"],
+            });
+        }
+    });
+    server.tool("review_generated_tests", "List and approve the generated test suites PreMan flagged for human review. This is the dashboard's 'Review flagged' button. generate_saved_tests deliberately leaves mutating and ambiguous routes disabled; this is how a reviewed suite gets turned on. Approving enables the suite's read-only schedule and does not raise the unattended write policy, so a DELETE stays gated at run time. List first and show the user each suite and its reason; only use approve_all when they asked to clear the whole queue.", {
+        action: z
+            .enum(["list", "approve", "approve_all"])
+            .optional()
+            .describe("list (default) | approve one request_id | approve_all (max 50)"),
+        request_id: z.string().optional().describe("Saved request to approve; required for approve"),
+        workspace_id: z.string().optional().describe("Defaults to the caller's own workspace"),
+    }, async (args) => {
+        try {
+            const result = await callBackend("review_generated_tests", args);
+            return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                next_actions: ["Call review_generated_tests with action='list' to see the queue."],
+                related_tools: ["generate_saved_tests", "enrich_generated_tests"],
+            });
+        }
+    });
+    server.tool("setup_test_fixtures", "Fill the {id} path parameters in saved PreMan endpoints with real record ids. This is the dashboard's 'Setup fixtures' button: a happy-path test for GET /users/{id} needs an id that exists, so PreMan calls the sibling list route read-only, harvests ids from the response, and falls back to the endpoint's schema example. It never mints a fake UUID that would only 404 and never fires a write. Harvested values are stored in workspace settings and returned as a .env snippet. This does not approve anything.", {
+        action: z
+            .enum(["setup", "list"])
+            .optional()
+            .describe("setup (default) harvests ids; list reports what is still missing"),
+        workspace_id: z.string().optional().describe("Defaults to the caller's own workspace"),
+    }, async (args) => {
+        try {
+            const result = await callBackend("setup_test_fixtures", args);
+            return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                next_actions: ["Save at least one endpoint with a {id} path parameter, then retry."],
+                related_tools: ["generate_saved_tests", "review_generated_tests"],
+            });
+        }
+    });
+    server.tool("enrich_generated_tests", "Add model-written test cases on top of PreMan's heuristic suites. This is the dashboard's 'Enrich with agent' button. generate_saved_tests writes deterministic cases only; this pass asks a model for a few extra edge cases per suite. It touches review-cleared suites only, skips destructive and billing-sensitive requests unless workspace policy already allows that risk, skips suites already enriched, and stops after 40 suites per call so a large collection cannot fan out into hundreds of model calls. Leftovers come back as remaining.", {
+        action: z
+            .enum(["enrich", "list"])
+            .optional()
+            .describe("enrich (default) runs the pass; list returns the eligible suites"),
+        workspace_id: z.string().optional().describe("Defaults to the caller's own workspace"),
+    }, async (args) => {
+        try {
+            const result = await callBackend("enrich_generated_tests", args);
+            return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                next_actions: [
+                    "Run generate_saved_tests first, then clear the review queue with review_generated_tests.",
+                ],
+                related_tools: ["generate_saved_tests", "review_generated_tests"],
+            });
+        }
+    });
     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"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "premanmcp",
-  "version": "0.10.7",
+  "version": "0.12.0",
   "description": "Turn APIs into agent-callable MCP tools with auth, testing, and audit logs",
   "type": "module",
   "bin": {
@@ -15,7 +15,7 @@
     "open-mcp-preview-in-cursor": "node scripts/open-cursor-preview.mjs",
     "test": "npm run build && npm run test:connect && npm run test:node",
     "test:connect": "node scripts/smoke-connect.mjs",
-    "test:node": "node --test --test-timeout=90000 scripts/smoke-account.mjs scripts/smoke-cli-entrypoint.mjs scripts/smoke-launcher-config.mjs scripts/smoke-runner.mjs scripts/smoke-repo-config.mjs scripts/smoke-onboard.mjs scripts/smoke-local-detect.mjs scripts/smoke-prepush-hook.mjs scripts/smoke-cli-identity.mjs scripts/smoke-runner-heartbeat.mjs scripts/smoke-verify-prepush.mjs scripts/smoke-push-diff.mjs scripts/smoke-progress-reporter.mjs scripts/smoke-verify-plan.mjs scripts/smoke-install-desktop.mjs scripts/smoke-api-tools.mjs scripts/smoke-tests-workbench.mjs scripts/smoke-bin-scope.mjs"
+    "test:node": "node --test --test-timeout=90000 scripts/smoke-account.mjs scripts/smoke-cli-entrypoint.mjs scripts/smoke-launcher-config.mjs scripts/smoke-runner.mjs scripts/smoke-repo-config.mjs scripts/smoke-onboard.mjs scripts/smoke-local-detect.mjs scripts/smoke-prepush-hook.mjs scripts/smoke-cli-identity.mjs scripts/smoke-runner-heartbeat.mjs scripts/smoke-verify-prepush.mjs scripts/smoke-push-diff.mjs scripts/smoke-progress-reporter.mjs scripts/smoke-verify-plan.mjs scripts/smoke-install-desktop.mjs scripts/smoke-desktop-session.mjs scripts/smoke-api-tools.mjs scripts/smoke-tests-workbench.mjs scripts/smoke-bin-scope.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^0.1.0",