premanmcp 0.13.0 → 0.15.0

package/dist/server.js

@@ -384,6 +384,7 @@ export function createServer() {
             "- **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",
+            "- **SDK tools**: generate_sdk (builds a client from endpoints PreMan already discovered - takes no OpenAPI file), get_sdk_generation (poll a run), get_sdk_languages (roster + whether the toolchain is present)",
             "- **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.",
@@ -392,6 +393,7 @@ export function createServer() {
             "- '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.",
             "- 'list endpoints already saved in my PreMan dashboard': use get_endpoints. NEVER use discover_endpoints_from_codebase for this.",
             "- 'preview my MCP before deploying': mcp_preview (read-only). 'actually deploy': mcp_deploy.",
+            "- 'generate an SDK / client library for my API', 'I use Speakeasy / Fern': generate_sdk. Do NOT ask the user for an OpenAPI file or run a spec export first - PreMan builds the spec from the endpoints it already discovered, and needing a file is the chore this replaces. Pass open_pr=true only when the user asks for a pull request rather than a download.",
             "- 'test the login endpoint' / 'hit POST /auth/login with body': test_api with the full URL. Use test_endpoint_by_id ONLY when the user references a saved endpoint by id/uuid.",
             "- 'import my Postman/OpenAPI/Bruno/curl collection': import_collection.",
             "- '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.",
@@ -699,6 +701,193 @@ export function createServer() {
             });
         }
     });
+    // ── generate_sdk ──────────────────────────────────────────────────
+    //
+    // Straight to the REST API rather than through /mcp/call-tool, because the
+    // SDK endpoints take the same pm_live_ key and adding a backend tool wrapper
+    // would buy nothing. The spec is deliberately not a parameter: PreMan already
+    // holds one for every connected repository, and asking an agent to supply the
+    // document describing the API PreMan has been scanning is the exact chore
+    // this feature exists to remove.
+    async function sdkFetch(method, path, body) {
+        requireAuth();
+        const resp = await fetch(`${BACKEND_URL}${path}`, {
+            method,
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${API_KEY}`,
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        const text = await resp.text();
+        let parsed = null;
+        try {
+            parsed = text ? JSON.parse(text) : null;
+        }
+        catch {
+            parsed = { raw: text };
+        }
+        if (!resp.ok) {
+            const detail = (parsed && (parsed.detail?.[0]?.msg || parsed.detail)) || text || resp.statusText;
+            throw new Error(`${resp.status} ${typeof detail === "string" ? detail : JSON.stringify(detail)}`);
+        }
+        return parsed;
+    }
+    /** Resolve a repo name like "acme/api" to a connected integration id. */
+    async function resolveIntegration(hint) {
+        const rows = await sdkFetch("GET", "/integrations/github");
+        if (!Array.isArray(rows) || rows.length === 0) {
+            throw new Error("no GitHub repository is connected; connect one before generating an SDK");
+        }
+        if (!hint) {
+            if (rows.length === 1)
+                return rows[0];
+            const names = rows.map((r) => r.repo_url).join(", ");
+            throw new Error(`several repositories are connected, so name one with repo: ${names}`);
+        }
+        const needle = hint.toLowerCase();
+        const hit = rows.find((r) => String(r.id) === hint) ||
+            rows.find((r) => String(r.repo_url || "").toLowerCase().includes(needle));
+        if (!hit) {
+            throw new Error(`no connected repository matches "${hint}"; connected: ${rows
+                .map((r) => r.repo_url)
+                .join(", ")}`);
+        }
+        return hit;
+    }
+    server.tool("generate_sdk", "Generate a client SDK from the endpoints PreMan already discovered for a connected repository. Takes no OpenAPI file - PreMan builds the spec itself. Returns a download URL. Use open_pr=true to open a pull request instead of producing an archive.", {
+        repo: z
+            .string()
+            .optional()
+            .describe("Which connected repository, as an integration id or any part of the repo URL such as 'acme/api'. Optional when only one is connected."),
+        languages: z
+            .array(z.string())
+            .optional()
+            .describe("Languages to generate. Defaults to ['python']. Call get_sdk_languages for the roster."),
+        halves: z
+            .array(z.enum(["client", "server"]))
+            .optional()
+            .describe("Client, server, or both. Defaults to ['client'], which is what a consumer of the API needs."),
+        open_pr: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Open a pull request against the repository instead of returning an archive. Requires the repository to have opted in to automatic pull requests."),
+        wait_seconds: z
+            .number()
+            .optional()
+            .default(150)
+            .describe("How long to wait for the run before handing back an id to poll. 0 returns immediately."),
+    }, async (args) => {
+        try {
+            const integration = await resolveIntegration(args.repo);
+            const integrationId = String(integration.id);
+            // Read the spec first so an empty or fully excluded surface is reported
+            // as that, rather than as a generation which fails a minute later.
+            const preview = await sdkFetch("GET", `/sdk/integrations/${integrationId}/spec`);
+            const run = await sdkFetch("POST", "/sdk/generate", {
+                integration_id: integrationId,
+                languages: args.languages ?? ["python"],
+                halves: args.halves ?? ["client"],
+                open_pr: args.open_pr ?? false,
+            });
+            const dashPath = "/endpoints";
+            emitActivity("navigate", { path: dashPath });
+            const deadline = Date.now() + Math.max(0, args.wait_seconds ?? 150) * 1000;
+            let current = run;
+            while (Date.now() < deadline &&
+                !["succeeded", "failed", "cancelled"].includes(String(current.status))) {
+                await new Promise((r) => setTimeout(r, 5000));
+                current = await sdkFetch("GET", `/sdk/generations/${run.id}`);
+            }
+            const done = String(current.status) === "succeeded";
+            return withFrontendUrl({
+                ...agentSessionPayload(dashPath),
+                generation_id: run.id,
+                status: current.status,
+                repo: integration.repo_url,
+                operations: preview.operation_count,
+                endpoints_published: preview.endpoint_count,
+                endpoints_excluded: preview.excluded_count,
+                spec_warnings: preview.warnings ?? [],
+                languages: current.languages,
+                files: current.files ?? [],
+                pr_url: current.pr_url ?? null,
+                error: current.error ?? null,
+                download_url: done
+                    ? `${BACKEND_URL}/sdk/generations/${run.id}/download`
+                    : null,
+                _agent_hints: done
+                    ? {
+                        next_actions: [
+                            `Download the archive: curl -H "Authorization: Bearer $PREMAN_API_KEY" -o sdk.zip ${BACKEND_URL}/sdk/generations/${run.id}/download`,
+                        ],
+                    }
+                    : {
+                        next_actions: [
+                            `Still ${current.status}. Poll with get_sdk_generation(generation_id="${run.id}").`,
+                        ],
+                    },
+            }, dashPath);
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                next_actions: [
+                    "Confirm a repository is connected and has discovered endpoints (get_endpoints).",
+                    "If open_pr was true, the repository must have opted in to automatic pull requests.",
+                ],
+                related_tools: ["get_endpoints", "get_sdk_languages", "get_sdk_generation"],
+            });
+        }
+    });
+    // ── get_sdk_generation ────────────────────────────────────────────
+    server.tool("get_sdk_generation", "Poll one SDK generation run started by generate_sdk. Returns status and, once finished, the download URL.", {
+        generation_id: z.string().describe("The generation_id returned by generate_sdk"),
+    }, async (args) => {
+        try {
+            const run = await sdkFetch("GET", `/sdk/generations/${args.generation_id}`);
+            const done = String(run.status) === "succeeded";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            generation_id: run.id,
+                            status: run.status,
+                            attempts: run.attempts,
+                            error: run.error ?? null,
+                            pr_url: run.pr_url ?? null,
+                            files: run.files ?? [],
+                            download_url: done
+                                ? `${BACKEND_URL}/sdk/generations/${run.id}/download`
+                                : null,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                related_tools: ["generate_sdk"],
+            });
+        }
+    });
+    // ── get_sdk_languages ─────────────────────────────────────────────
+    server.tool("get_sdk_languages", "Which languages this PreMan deployment can generate, and whether the generator toolchain is present at all.", {}, async () => {
+        try {
+            const roster = await sdkFetch("GET", "/sdk/languages");
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(roster, null, 2) },
+                ],
+            };
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                related_tools: ["generate_sdk"],
+            });
+        }
+    });
     // ── import_collection ─────────────────────────────────────────────
     server.tool("import_collection", "Import a Postman, OpenAPI, Bruno, or curl collection. Converts to .ot.yaml and saves. Returns slim summary (name, endpoint list, collection_id). Set include_yaml=true to get the full YAML string.", {
         content: z.string().describe("Raw collection content (Postman JSON, OpenAPI YAML, Bruno .bru, curl command)"),
@@ -1517,14 +1706,14 @@ export function createServer() {
             });
         }
     });
-    server.tool("mcp_deploy", "Create and host an MCP server from a preview spec plus an upstream credential. By default this also mints the first consumer token and returns one complete install snippet or hosted URL to give to a coding agent. The upstream secret is encrypted at rest with a Fernet key; it is never returned to clients after this call.", {
+    server.tool("mcp_deploy", "Create and host an MCP server from a preview spec plus an upstream credential. Returns an install snippet to give to a coding agent. By default the MCP is public and NO consumer token is minted: pass initial_consumer_label to mint one, or call mcp_mint_consumer_token afterwards. Do not tell the user they have a token unless raw_consumer_token came back non-null. The upstream secret is encrypted at rest with a Fernet key; it is never returned to clients after this call.", {
         name: z.string().describe("Human-readable name, e.g. 'Acme Auth MCP'"),
         upstream_base_url: z.string().describe("Base URL of the business's real backend. Do not use PREMAN_BACKEND / api.preman.live unless deploying an MCP for PreMan itself."),
         spec: z.any().describe("The spec_preview object returned by mcp_preview"),
         initial_upstream_secret: z.string().describe("API key / bearer / basic value the MCP will use to reach the upstream backend"),
         upstream_auth_style: z.any().optional().describe("Override how the credential is injected. Default: { type:'header', name:'Authorization', prefix:'Bearer ' }"),
         initial_upstream_secret_type: z.string().optional().describe("bearer | api_key | basic | custom"),
-        initial_consumer_label: z.string().optional().describe("Optional label for the first consumer token. Defaults to default-consumer; pass empty only if you want to mint a token later."),
+        initial_consumer_label: z.string().optional().describe("Label for the first consumer token. Omit and no token is minted and the MCP is reachable by anyone holding the URL; pass a label to mint one and get a private, revocable install snippet."),
     }, async (args) => {
         try {
             const deployArgs = { ...args };
@@ -1617,7 +1806,7 @@ export function createServer() {
         }
     });
     // ── 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.", {
+    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 automatically — it merges only its own preman/fix-* branches, only on repositories that turned merging on, and only after you approve.", {
         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"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "premanmcp",
-  "version": "0.13.0",
+  "version": "0.15.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 && npm run test:dmg",
     "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-desktop-session.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-checkout.mjs scripts/smoke-onboard.mjs scripts/smoke-onboard-opening.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-link.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",
     "test:dmg": "node --test --test-timeout=300000 scripts/smoke-install-desktop-volume.mjs"
   },
   "dependencies": {