premanmcp 0.3.4 → 0.4.0

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() {
@@ -42,6 +42,62 @@ applyRepoPremanConfig();
 const BACKEND_URL = process.env.PREMAN_BACKEND || "https://api.preman.live";
 const FRONTEND_URL = process.env.PREMAN_FRONTEND || "https://app.preman.live";
 let API_KEY = process.env.PREMAN_API_KEY || "";
+function detectCodingAgent() {
+    const forced = (process.env.PREMAN_CODING_AGENT || "").trim().toLowerCase();
+    if (forced)
+        return forced.replace("-", "_");
+    if (process.env.CLAUDECODE || process.env.CLAUDE_CODE)
+        return "claude_code";
+    if (process.env.CODEX_HOME || process.env.OPENAI_CODEX)
+        return "codex";
+    if (process.env.CURSOR_AGENT || process.env.CURSOR_TRACE_ID || process.env.CURSOR_SESSION_ID) {
+        return "cursor";
+    }
+    return "cursor";
+}
+/** Prove this MCP session is live to the workbench coding-agent link. */
+async function heartbeatWorkbenchLink() {
+    if (!API_KEY)
+        return null;
+    try {
+        const resp = await fetch(`${BACKEND_URL}/workbench/coding-agent/heartbeat`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${API_KEY}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                pair_code: process.env.PREMAN_PAIR_CODE || undefined,
+                agent: detectCodingAgent(),
+                project_path: process.cwd(),
+                client_label: "premanmcp",
+                source: "preman_status",
+            }),
+        });
+        const text = await resp.text();
+        let data = {};
+        try {
+            data = text ? JSON.parse(text) : {};
+        }
+        catch {
+            data = { detail: text };
+        }
+        if (!resp.ok) {
+            return {
+                ok: false,
+                status: resp.status,
+                detail: data.detail || data.message || text,
+            };
+        }
+        return { ok: true, ...data };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            detail: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
 const PREMAN_CONTROL_PLANE_HOSTS = new Set([
     "api.preman.live",
     "preman.live",
@@ -107,7 +163,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 +230,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 +243,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 +251,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 +329,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 +346,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 +362,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 +379,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 +388,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 +724,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 +916,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 +956,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,11 +971,12 @@ 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.",
                         }),
                     }],
             };
         }
+        const workbench = await heartbeatWorkbenchLink();
         return {
             content: [{
                     type: "text",
@@ -844,13 +987,17 @@ export function createServer() {
                         backend_url: BACKEND_URL,
                         frontend_base_url: FRONTEND_BASE,
                         endpoints_page_url: buildAgentDashboardUrl("/endpoints"),
+                        coding_agent: workbench,
                         _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.",
+                                workbench && workbench.connected
+                                    ? "Coding agent is linked to PreMan workbench — call discover_endpoints_from_codebase or get_endpoints."
+                                    : "If PreMan workbench shows pairing, set PREMAN_PAIR_CODE then call preman_status again.",
+                                "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.",
                             ],
-                            related_tools: ["get_endpoints", "test_api", "import_collection"],
+                            related_tools: ["get_endpoints", "test_api", "import_collection", "discover_endpoints_from_codebase"],
                         },
                     }),
                 }],
@@ -876,7 +1023,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 +1035,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 +1044,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 +1097,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 +1111,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 +1163,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.",
@@ -1118,6 +1267,54 @@ export function createServer() {
             return toolError(e.message, inferErrorCode(e.message));
         }
     });
+    // ── preman_get_fix_task ───────────────────────────────────────────
+    server.tool("preman_get_fix_task", "Pull pending coding-agent fix tasks built from fired PreMan alerts. Each task packages a failing endpoint: title, expected vs actual, failure stats, and a reproducible curl (package.repro.curl). Fix the endpoint using the curl, then call preman_complete_fix_task with the fix_task_id. Check package.auto_pr: when eligible is true, push your fix on the branch it names and call preman_open_fix_pr.", {
+        status: z.enum(["open", "delivered", "resolved"]).optional().default("open").describe("'open' (default) hands out new tasks and marks them delivered; 'delivered' re-fetches ones already pulled; 'resolved' for history"),
+        limit: z.number().optional().default(5).describe("Max tasks to return (capped at 20)"),
+    }, async (args) => {
+        try {
+            const result = await callBackend("preman_get_fix_task", args);
+            return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                next_actions: ["No open fix tasks means no alerts have been handed off. Create a handoff from a fired alert in the dashboard."],
+            });
+        }
+    });
+    // ── preman_complete_fix_task ──────────────────────────────────────
+    server.tool("preman_complete_fix_task", "Mark a fix task resolved once its endpoint failure is fixed.", {
+        fix_task_id: z.string().describe("The id from a preman_get_fix_task result"),
+        resolution_note: z.string().optional().default("").describe("Optional note on what was fixed"),
+    }, async (args) => {
+        try {
+            const result = await callBackend("preman_complete_fix_task", args);
+            return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                related_tools: ["preman_get_fix_task"],
+            });
+        }
+    });
+    // ── preman_open_fix_pr ────────────────────────────────────────────
+    server.tool("preman_open_fix_pr", "Open a pull request for a fix branch you already pushed (Auto-PR, Tier 2). Only for fix tasks whose package.auto_pr.eligible is true. Patch and push the preman/fix-* branch with your own git credentials first — PreMan never pushes code. PreMan then verifies the branch exists, re-checks the endpoint in production, and opens a PR with that evidence. PreMan never merges: a human reviews and merges.", {
+        fix_task_id: z.string().describe("The id from a preman_get_fix_task result"),
+        branch: z.string().describe("The branch you pushed — must match package.auto_pr.branch"),
+        summary: z.string().optional().default("").describe("Short description of the fix, included in the PR body"),
+        local_rerun: z.string().optional().default("").describe("Your local test/re-run output, included as agent-reported evidence"),
+    }, async (args) => {
+        try {
+            const result = await callBackend("preman_open_fix_pr", args);
+            return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                related_tools: ["preman_get_fix_task", "preman_complete_fix_task"],
+                next_actions: ["Auto-PR requires the repo to have opted in and the fix task to be an API_BUG failure mapped to that repo."],
+            });
+        }
+    });
     return server;
 }
 // ── Start ─────────────────────────────────────────────────────────────

package/dist/user_auth_flow.js

@@ -58,6 +58,34 @@ 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). If the backend does not support this endpoint yet, use user_auth_signup instead.", {
+        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) {
+                if (r.status_code === 404) {
+                    return toolError("This backend does not support email-only signup yet. Use user_auth_signup with email and password, then user_auth_verify_otp.", "backend_error", {
+                        next_actions: ["Call user_auth_signup with email and password.", "Then call user_auth_verify_otp with the email code."],
+                        related_tools: ["user_auth_signup", "user_auth_verify_otp"],
+                    });
+                }
+                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,11 +1,12 @@
 {
   "name": "premanmcp",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "Turn APIs into agent-callable MCP tools with auth, testing, and audit logs",
   "type": "module",
   "bin": {
     "premanmcp": "bin/cli.js",
-    "preman-mcp": "bin/cli.js"
+    "preman-mcp": "bin/cli.js",
+    "preman": "bin/cli.js"
   },
   "scripts": {
     "build": "tsc -p tsconfig.server.json",