premanmcp 0.10.7 → 0.11.0

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/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,7 +11,7 @@
  * 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 os from "node:os";
@@ -29,9 +29,34 @@ 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;
 
+/**
+ * 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`;
 }

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"],
             });
         }
     });

package/package.json

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