opentestmcp 0.3.0

package/dist/server.js

@@ -0,0 +1,980 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { registerUserAuthFlowTools } from "./user_auth_flow.js";
+import { existsSync, readFileSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { randomUUID } from "node:crypto";
+import { MCP_PREVIEW_RESOURCE_URI, RESOURCE_URI_META_KEY, buildConversionPanelHtml, writeMcpPreviewFile, } from "./mcp-preview-panel.js";
+/**
+ * Load ``OPENTEST_*`` from repo JSON so project URLs win over stale **global** Cursor MCP env
+ * (which often sets the wrong ``OPENTEST_BACKEND``, e.g. Flow port instead of API port).
+ * First match wins: ``.cursor/opentest-mcp.config.json``, then ``opentest-mcp.config.json`` (cwd).
+ */
+function applyRepoOpentestConfig() {
+    const candidates = [
+        path.join(process.cwd(), ".cursor", "opentest-mcp.config.json"),
+        path.join(process.cwd(), "opentest-mcp.config.json"),
+    ];
+    for (const p of candidates) {
+        try {
+            if (!existsSync(p))
+                continue;
+            const j = JSON.parse(readFileSync(p, "utf8"));
+            for (const [key, val] of Object.entries(j)) {
+                if (!key.startsWith("OPENTEST_"))
+                    continue;
+                if (typeof val === "string" && val.trim()) {
+                    process.env[key] = val.trim();
+                }
+            }
+            return;
+        }
+        catch {
+            /* try next path */
+        }
+    }
+}
+applyRepoOpentestConfig();
+const BACKEND_URL = process.env.OPENTEST_BACKEND || "https://flow.opentest.live";
+const FRONTEND_URL = process.env.OPENTEST_FRONTEND || "https://www.flowtest.opentest.live";
+let API_KEY = process.env.OPENTEST_API_KEY || "";
+function normalizeFrontendBaseUrl(url) {
+    return url.replace(/\/+$/, "");
+}
+/** Origin only (no path). */
+const FRONTEND_BASE = normalizeFrontendBaseUrl(FRONTEND_URL);
+/**
+ * Static hosts (S3/CloudFront) 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";
+function buildAgentDashboardUrlForBase(baseUrl, routePath) {
+    const base = normalizeFrontendBaseUrl(baseUrl);
+    const u = new URL(`${base}/`);
+    u.searchParams.set("agent_session", AGENT_SESSION_ID);
+    const p = routePath.startsWith("/") ? routePath : `/${routePath}`;
+    u.searchParams.set(AGENT_ROUTE_PARAM, p);
+    return u.toString();
+}
+function buildAgentDashboardUrl(routePath) {
+    return buildAgentDashboardUrlForBase(FRONTEND_BASE, routePath);
+}
+/** Stable per-process ID the dashboard subscribes to for live follow-along. */
+const AGENT_SESSION_ID = randomUUID();
+// ── Credential Storage ────────────────────────────────────────────────
+const CREDENTIALS_DIR = path.join(os.homedir(), ".opentest");
+const CREDENTIALS_FILE = path.join(CREDENTIALS_DIR, "credentials.json");
+async function loadStoredCredentials() {
+    try {
+        const raw = await fs.readFile(CREDENTIALS_FILE, "utf-8");
+        const creds = JSON.parse(raw);
+        if (creds.api_key && creds.api_key.startsWith("ot_live_"))
+            return creds;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+async function saveCredentials(creds) {
+    await fs.mkdir(CREDENTIALS_DIR, { recursive: true, mode: 0o700 });
+    await fs.writeFile(CREDENTIALS_FILE, JSON.stringify(creds, null, 2), { mode: 0o600 });
+    console.error(`[OpenTest] Credentials saved to ${CREDENTIALS_FILE}`);
+}
+async function clearCredentials() {
+    try {
+        await fs.unlink(CREDENTIALS_FILE);
+        console.error("[OpenTest] Credentials cleared");
+    }
+    catch {
+        // file didn't exist, that's fine
+    }
+}
+async function verifyApiKey(key) {
+    try {
+        const resp = await fetch(`${BACKEND_URL}/mcp/whoami`, {
+            headers: { Authorization: `Bearer ${key}` },
+        });
+        if (!resp.ok)
+            return { valid: false, reachable: true };
+        const data = await resp.json();
+        return { valid: true, reachable: true, email: data.email, key_name: data.key_name };
+    }
+    catch {
+        return { valid: false, reachable: false };
+    }
+}
+async function initAuth() {
+    if (API_KEY) {
+        console.error("[OpenTest] Using API key from OPENTEST_API_KEY env var");
+        return;
+    }
+    const creds = await loadStoredCredentials();
+    if (!creds) {
+        console.error("[OpenTest] No stored credentials. Use opentest_login to authenticate.");
+        return;
+    }
+    const check = await verifyApiKey(creds.api_key);
+    if (check.valid) {
+        API_KEY = creds.api_key;
+        console.error(`[OpenTest] Authenticated as ${creds.user_email ?? "unknown"} (stored credentials)`);
+    }
+    else if (!check.reachable) {
+        API_KEY = creds.api_key;
+        console.error("[OpenTest] Backend unreachable — using stored credentials (will verify on first call)");
+    }
+    else {
+        console.error("[OpenTest] Stored credentials are invalid or expired. Use opentest_login to re-authenticate.");
+        await clearCredentials();
+    }
+}
+// Panel HTML: ./mcp-preview-panel.ts (also used by scripts/emit-mcp-preview.mjs)
+// ── Backend proxy ─────────────────────────────────────────────────────
+function requireAuth() {
+    if (!API_KEY) {
+        throw new Error("Not authenticated. Run the opentest_login tool first to connect your OpenTest account.");
+    }
+}
+async function callBackend(toolName, args) {
+    requireAuth();
+    const headers = {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${API_KEY}`,
+    };
+    const resp = await fetch(`${BACKEND_URL}/mcp/call-tool`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ tool: toolName, arguments: args }),
+    });
+    if (!resp.ok) {
+        const text = await resp.text();
+        throw new Error(`Backend error: ${resp.status} ${text}`);
+    }
+    return resp.json();
+}
+function emitActivity(eventType, data) {
+    fetch(`${BACKEND_URL}/agent/activity/${AGENT_SESSION_ID}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ event_type: eventType, data }),
+    }).catch((err) => {
+        console.error(`[OpenTest] emitActivity(${eventType}) failed: ${err.message}`);
+    });
+}
+/** Build the `_agent_session` block included in every tool response. */
+function agentSessionPayload(dashboardPath = "/endpoints") {
+    return {
+        _agent_session: {
+            session_id: AGENT_SESSION_ID,
+            dashboard_url: buildAgentDashboardUrl(dashboardPath),
+        },
+    };
+}
+/**
+ * Return a structured MCP error response that agents can reliably parse.
+ *
+ * Every error has the same shape: ``{ error, error_code, _agent_hints }``.
+ */
+function toolError(message, code = "backend_error", hints) {
+    const payload = {
+        error: message,
+        error_code: code,
+    };
+    if (hints) {
+        payload._agent_hints = hints;
+    }
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload) }],
+        isError: true,
+    };
+}
+/** Infer an ``ErrorCode`` from an error message for common patterns. */
+function inferErrorCode(msg) {
+    const lower = msg.toLowerCase();
+    if (lower.includes("401") || lower.includes("unauthorized") || lower.includes("not authenticated"))
+        return "auth_required";
+    if (lower.includes("404") || lower.includes("not found"))
+        return "not_found";
+    if (lower.includes("400") || lower.includes("invalid") || lower.includes("missing"))
+        return "invalid_input";
+    return "backend_error";
+}
+// ── Helper: attach OpenTest frontend URL to every tool response ────────
+/** Merge backend payload with `ui.url` pointing at the Endpoints page (for get_endpoints JSON without a separate panel). */
+function enrichEndpointsBrowserUrl(payload) {
+    const prevUi = typeof payload.ui === "object" && payload.ui !== null
+        ? payload.ui
+        : {};
+    return {
+        ...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.",
+        },
+    };
+}
+function withFrontendUrl(payload, path) {
+    const p = path ?? "/endpoints";
+    const prevUi = typeof payload.ui === "object" && payload.ui !== null
+        ? payload.ui
+        : {};
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify({
+                    ...payload,
+                    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.",
+                    },
+                }),
+            }],
+    };
+}
+// ── MCP Server ────────────────────────────────────────────────────────
+export function createServer() {
+    const server = new McpServer({ name: "OpenTest", version: "1.0.0" }, {
+        instructions: [
+            "OpenTest is an API testing platform. It discovers, tests, and monitors API endpoints.",
+            "",
+            "## Tool taxonomy",
+            "- **Read tools** (no side effects): get_endpoints, get_coverage, detect_drift, opentest_status, list_collections, get_collection, list_runs",
+            "- **Action tools** (execute tests / mutate state): test_api, test_flow, 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 / OpenTest)**: opentest_login, opentest_login_complete, opentest_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 OPENTEST_BACKEND /auth/*; no ot_live_ key required)",
+            "",
+            "## Defaults for agents",
+            '- 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.",
+            "",
+            "## Common workflows",
+            "1. **Discover then test**: get_endpoints -> pick untested/failing -> test_api for each.",
+            "2. **Import then generate**: import_collection (Postman/OpenAPI/curl) -> generate_tests -> test_api to run them.",
+            '3. **Coverage audit**: get_coverage on a collection -> generate_tests(coverage_level="comprehensive") for gaps.',
+            "4. **Drift detection**: detect_drift with a collection + base_url -> test_api on drifted endpoints.",
+            "",
+            "## Auth",
+            "OpenTest API tools (get_endpoints, test_api, …) need an ot_live_ key: run opentest_login, then opentest_login_complete.",
+            "To drive the backend's **email/JWT** auth (signup, OTP, login, /auth/me), use the user_auth_* tools — they call OPENTEST_BACKEND /auth/* directly and do not use the API key.",
+        ].join("\n"),
+    });
+    // ── test_api ──────────────────────────────────────────────────────
+    server.tool("test_api", "Execute an HTTP request against an API endpoint. Returns structured JSON: status_code, response_time_ms, body, assertions results, and extracted variables. The endpoint is automatically registered in the OpenTest registry.", {
+        method: z.string().describe("HTTP method (GET, POST, PUT, PATCH, DELETE)"),
+        url: z.string().describe("Full URL to test"),
+        headers: z.record(z.string()).optional().describe("Request headers"),
+        body: z.any().optional().describe("JSON request body"),
+        assertions: z.array(z.any()).optional().describe("List of assertions"),
+        project_id: z.string().optional().describe("Scope endpoint registration to a project"),
+    }, async (args) => {
+        try {
+            emitActivity("test_started", { method: args.method, url: args.url });
+            const result = await callBackend("test_api", args);
+            const runId = result?.run_id != null ? String(result.run_id) : "";
+            const dashPath = `/endpoints?id=${runId}`;
+            emitActivity("test_complete", {
+                run_id: runId,
+                method: args.method,
+                url: args.url,
+                status_code: result?.status_code,
+                passed: result?.status_code >= 200 && result?.status_code < 300,
+                response_time_ms: result?.response_time_ms,
+                path: dashPath,
+            });
+            return withFrontendUrl({
+                ...result,
+                ...agentSessionPayload(dashPath),
+                _request: { method: args.method, url: args.url, headers: args.headers, body: args.body },
+            }, dashPath);
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                next_actions: ["Verify the URL and method are correct, then retry. Call get_endpoints to check available endpoints."],
+                related_tools: ["get_endpoints"],
+            });
+        }
+    });
+    // ── test_endpoint_by_id ───────────────────────────────────────────
+    server.tool("test_endpoint_by_id", "Run test_api against a saved registry endpoint by UUID from get_endpoints (no manual URL assembly). Optional body/headers override the defaults for that call.", {
+        endpoint_id: z.string().describe("UUID from get_endpoints endpoints[].id"),
+        headers: z.record(z.string()).optional().describe("Request headers"),
+        body: z.any().optional().describe("JSON request body (e.g. login credentials)"),
+        assertions: z.array(z.any()).optional().describe("List of assertions"),
+        extract: z.record(z.string()).optional().describe("json_path -> variable name for chaining"),
+    }, async (args) => {
+        try {
+            emitActivity("test_started", { endpoint_id: args.endpoint_id });
+            const result = await callBackend("test_endpoint_by_id", args);
+            const runId = result?.run_id != null ? String(result.run_id) : "";
+            const dashPath = runId ? `/endpoints?id=${runId}` : "/endpoints";
+            emitActivity("test_complete", {
+                run_id: runId,
+                endpoint_id: args.endpoint_id,
+                method: result?.method,
+                url: result?.resolved_url,
+                status_code: result?.status_code,
+                passed: result?.status_code >= 200 && result?.status_code < 300,
+                response_time_ms: result?.response_time_ms,
+                path: dashPath,
+            });
+            return withFrontendUrl({
+                ...result,
+                ...agentSessionPayload(dashPath),
+                _request: {
+                    endpoint_id: args.endpoint_id,
+                    resolved_url: result?.resolved_url,
+                    headers: args.headers,
+                    body: args.body,
+                },
+            }, dashPath);
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                next_actions: ["Verify the endpoint_id exists by calling get_endpoints first."],
+                related_tools: ["get_endpoints", "test_api"],
+            });
+        }
+    });
+    // ── get_endpoints ─────────────────────────────────────────────────
+    server.tool("get_endpoints", "Return endpoint inventory (registry, optionally MCP sessions and collections). Default: structured JSON for agents. Pass format='text' for deprecated human-friendly output, or open_ui=true for the visual dashboard. Schemas stripped by default to save tokens; set include_schemas=true when needed.", {
+        status: z.string().optional().describe("Filter: tested, needed, draft"),
+        method: z.string().optional().describe("Filter by HTTP method"),
+        include_sessions: z.boolean().optional().default(false).describe("Include recent MCP session test results"),
+        include_collections: z.boolean().optional().default(false).describe("Include imported collection endpoints"),
+        include_schemas: z.boolean().optional().default(false).describe("Include request/response schemas per endpoint (default false to save tokens)"),
+        limit: z.number().optional().default(50).describe("Max endpoints per page (default 50)"),
+        offset: z.number().optional().default(0).describe("Pagination offset"),
+        project_id: z.string().optional().describe("Scope to a specific project"),
+        format: z.enum(["json", "text"]).optional().default("json").describe("'json' (default, structured) or 'text' (deprecated human-friendly)"),
+        open_ui: z.boolean().optional().default(false).describe("Also open the visual dashboard (default: false)"),
+    }, async (args) => {
+        try {
+            emitActivity("navigate", { path: "/endpoints", query_params: { status: args.status, method: args.method } });
+            const result = await callBackend("get_endpoints", args);
+            const asRecord = result;
+            if (args.open_ui) {
+                return withFrontendUrl(enrichEndpointsBrowserUrl(asRecord), "/endpoints");
+            }
+            if (args.format === "text" && typeof result === "string") {
+                return { content: [{ type: "text", text: result }] };
+            }
+            const enriched = typeof result === "object" && result !== null && !Array.isArray(result)
+                ? { ...enrichEndpointsBrowserUrl(asRecord), ...agentSessionPayload("/endpoints") }
+                : result;
+            return {
+                content: [{
+                        type: "text",
+                        text: typeof enriched === "string" ? enriched : JSON.stringify(enriched),
+                    }],
+            };
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                next_actions: ["If authentication failed, call opentest_login first. Otherwise check that the backend is running."],
+                related_tools: ["opentest_login"],
+            });
+        }
+    });
+    // ── test_flow ─────────────────────────────────────────────────────
+    server.tool("test_flow", "Run a browser-based UI flow test. Navigates to the URL and executes the task using a headless browser. Returns structured results with pass/fail, steps taken, and screenshots.", {
+        url: z.string().describe("Starting URL to test"),
+        task: z.string().describe("What to test"),
+        context: z.string().optional().describe("Extra context (credentials, form data)"),
+    }, async (args) => {
+        try {
+            emitActivity("test_started", { url: args.url, task: args.task, tool: "test_flow" });
+            const result = await callBackend("test_flow", args);
+            emitActivity("test_complete", { url: args.url, task: args.task, tool: "test_flow", status: result?.status, path: "/runs" });
+            return withFrontendUrl({ ...result, ...agentSessionPayload("/runs") }, "/runs");
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                next_actions: ["If the URL is unreachable, verify it. For simpler tests, use test_api instead."],
+                related_tools: ["test_api"],
+            });
+        }
+    });
+    // ── generate_tests ────────────────────────────────────────────────
+    server.tool("generate_tests", "Generate a .ot.yaml test suite from a natural language description. Returns the YAML content, parsed collection spec, and a collection_id if saved to the dashboard. Use get_coverage afterwards to check gaps.", {
+        description: z.string().describe("What to test in natural language"),
+        endpoint_url: z.string().optional().describe("Optional: full URL of the endpoint to test"),
+        method: z.string().optional().describe("HTTP method (GET, POST, PUT, PATCH, DELETE)"),
+        coverage_level: z.enum(["standard", "comprehensive", "security"]).optional().default("standard").describe("Coverage depth"),
+        project_id: z.string().optional().describe("Scope generated collection to a project"),
+        endpoint_ids: z.array(z.string()).optional().describe("Registry endpoint UUIDs to generate tests for (overrides endpoint_url/method)"),
+    }, async (args) => {
+        try {
+            const result = await callBackend("generate_tests", args);
+            const payload = typeof result === "string" ? JSON.parse(result) : result;
+            const collectionId = payload?.collection_id ?? "";
+            const dashPath = collectionId ? `/collections?id=${collectionId}` : "/collections";
+            emitActivity("navigate", { path: dashPath });
+            emitActivity("data_refresh", { scope: "collections" });
+            return withFrontendUrl({ ...payload, ...agentSessionPayload(dashPath) }, dashPath);
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                next_actions: ["Provide a more specific description, or use endpoint_ids for registry-based generation."],
+                related_tools: ["import_collection", "test_api"],
+            });
+        }
+    });
+    // ── get_coverage ──────────────────────────────────────────────────
+    server.tool("get_coverage", "Analyze API test coverage for a collection. Returns overall_score and top_priorities by default. Set include_endpoint_details=true for per-endpoint breakdown.", {
+        collection_yaml: z.string().optional().describe("Raw .ot.yaml content to analyze"),
+        collection_id: z.string().optional().describe("ID of a saved collection from the dashboard"),
+        include_endpoint_details: z.boolean().optional().default(false).describe("Include per-endpoint analysis (default false to save tokens)"),
+    }, async (args) => {
+        try {
+            const collectionId = args.collection_id ?? "";
+            const dashPath = collectionId ? `/collections?id=${collectionId}&view=coverage` : "/collections";
+            emitActivity("navigate", { path: dashPath });
+            const result = await callBackend("get_coverage", args);
+            return withFrontendUrl({ ...result, ...agentSessionPayload(dashPath) }, dashPath);
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                next_actions: ["Provide a collection_id or collection_yaml. Call list_collections to find available collections."],
+                related_tools: ["import_collection", "list_collections"],
+            });
+        }
+    });
+    // ── 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)"),
+        format_hint: z.enum(["postman", "openapi", "bruno", "curl"]).optional().describe("Format override (auto-detected if omitted)"),
+        include_yaml: z.boolean().optional().default(false).describe("Include the full .ot.yaml string in the response (default false to save tokens)"),
+        project_id: z.string().optional().describe("Scope imported collection to a project"),
+    }, async (args) => {
+        try {
+            const result = await callBackend("import_collection", args);
+            const collectionId = result?.collection_id ?? "";
+            const dashPath = collectionId ? `/collections?id=${collectionId}` : "/collections";
+            emitActivity("navigate", { path: dashPath });
+            emitActivity("data_refresh", { scope: "collections" });
+            return withFrontendUrl({ ...result, ...agentSessionPayload(dashPath) }, dashPath);
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                next_actions: ["Check that the content is valid Postman JSON, OpenAPI YAML, Bruno .bru, or curl. Try format_hint to force detection."],
+                related_tools: ["get_endpoints"],
+            });
+        }
+    });
+    // ── detect_drift ──────────────────────────────────────────────────
+    server.tool("detect_drift", "Detect spec drift by comparing live API responses against a collection spec. Returns a list of drift alerts per endpoint with expected vs actual differences.", {
+        base_url: z.string().describe("Base URL to test against (e.g. https://api.example.com)"),
+        collection_yaml: z.string().optional().describe("Raw .ot.yaml content"),
+        collection_id: z.string().optional().describe("ID of a saved collection from the dashboard"),
+        headers: z.record(z.string()).optional().describe("Request headers applied to all drift-check requests (e.g. auth tokens)"),
+    }, async (args) => {
+        try {
+            emitActivity("navigate", { path: "/endpoints", query_params: { view: "drift" } });
+            const result = await callBackend("detect_drift", args);
+            return withFrontendUrl({ ...result, ...agentSessionPayload("/endpoints?view=drift") }, "/endpoints?view=drift");
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                next_actions: ["Provide a base_url and either a collection_id or collection_yaml. Call list_collections to find saved collections."],
+                related_tools: ["import_collection", "test_api", "list_collections"],
+            });
+        }
+    });
+    // ── run_tests ─────────────────────────────────────────────────────
+    server.tool("run_tests", "Batch-run multiple API endpoints in one call. More efficient than calling test_api N times. Returns per-endpoint results with pass/fail, status codes, and response times.", {
+        endpoints: z.array(z.object({
+            method: z.string().describe("HTTP method"),
+            path: z.string().describe("URL path or full URL"),
+            base_url: z.string().optional().describe("Base URL override for this endpoint"),
+        })).describe("List of endpoints to test"),
+        base_url: z.string().optional().describe("Fallback base URL for endpoints without one"),
+        headers: z.record(z.string()).optional().describe("Request headers applied to all requests"),
+    }, async (args) => {
+        try {
+            emitActivity("test_started", { tool: "run_tests", endpoint_count: args.endpoints.length });
+            const result = await callBackend("run_api_tests", args);
+            emitActivity("test_complete", { tool: "run_tests", total: result?.total, passed: result?.passed, failed: result?.failed });
+            return withFrontendUrl({ ...result, ...agentSessionPayload("/endpoints") }, "/endpoints");
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                next_actions: ["Verify the endpoints array has valid method and path fields. Use test_api for individual endpoint debugging."],
+                related_tools: ["test_api", "get_endpoints"],
+            });
+        }
+    });
+    // ── list_collections ──────────────────────────────────────────────
+    server.tool("list_collections", "List saved collections (Postman, OpenAPI, curl imports). Returns id, name, format, created_at for each. Use get_collection for full details.", {
+        project_id: z.string().optional().describe("Scope to a specific project"),
+    }, async (args) => {
+        try {
+            const result = await callBackend("list_collections", args);
+            emitActivity("navigate", { path: "/collections" });
+            return {
+                content: [{ type: "text", text: JSON.stringify({ ...result, ...agentSessionPayload("/collections") }) }],
+            };
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                next_actions: ["If no collections exist, import one with import_collection."],
+                related_tools: ["import_collection"],
+            });
+        }
+    });
+    // ── get_collection ───────────────────────────────────────────────
+    server.tool("get_collection", "Get details for a single collection by ID. Returns metadata and endpoint list. Set include_content=true to also get the raw YAML string.", {
+        collection_id: z.string().describe("UUID of the collection"),
+        include_content: z.boolean().optional().default(false).describe("Include the raw YAML content (default false to save tokens)"),
+    }, async (args) => {
+        try {
+            const result = await callBackend("get_collection", args);
+            const collectionId = result?.id ?? args.collection_id;
+            const dashPath = `/collections?id=${collectionId}`;
+            emitActivity("navigate", { path: dashPath });
+            return withFrontendUrl({ ...result, ...agentSessionPayload(dashPath) }, dashPath);
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                next_actions: ["Verify the collection_id by calling list_collections first."],
+                related_tools: ["list_collections"],
+            });
+        }
+    });
+    // ── delete_collection ────────────────────────────────────────────
+    server.tool("delete_collection", "Soft-delete a collection by ID. The collection is archived (is_active=false) and no longer appears in list_collections.", {
+        collection_id: z.string().describe("UUID of the collection to delete"),
+    }, async (args) => {
+        try {
+            const result = await callBackend("delete_collection", args);
+            emitActivity("data_refresh", { scope: "collections" });
+            return {
+                content: [{ type: "text", text: JSON.stringify({ ...result, ...agentSessionPayload("/collections") }) }],
+            };
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                next_actions: ["Verify the collection_id by calling list_collections first."],
+                related_tools: ["list_collections"],
+            });
+        }
+    });
+    // ── list_runs ────────────────────────────────────────────────────
+    server.tool("list_runs", "List recent test runs with summary metadata. Heavy fields (logs, video paths) are stripped to save tokens.", {
+        limit: z.number().optional().default(20).describe("Max runs to return (default 20)"),
+    }, async (args) => {
+        try {
+            const result = await callBackend("list_runs", args);
+            emitActivity("navigate", { path: "/runs" });
+            return withFrontendUrl({ ...result, ...agentSessionPayload("/runs") }, "/runs");
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                next_actions: ["If no runs exist, create one with test_api or run_tests."],
+                related_tools: ["test_api", "run_tests", "test_flow"],
+            });
+        }
+    });
+    // ── endpoints_dashboard ───────────────────────────────────────────────
+    server.tool("endpoints_dashboard", "[DEPRECATED -- use get_endpoints with include_sessions=true, include_collections=true instead] Return ALL endpoints aggregated from registry, MCP sessions, and collections.", {
+        filter_method: z.string().optional().describe("Filter by HTTP method: GET, POST, PUT, PATCH, DELETE"),
+        filter_source: z.string().optional().describe("Filter by source: 'collection', 'mcp', or 'project'"),
+        project_id: z.string().optional().describe("Scope to a specific project"),
+        format: z.enum(["json", "text"]).optional().default("json").describe("'json' (default, structured) or 'text' (deprecated terminal UI)"),
+        open_ui: z.boolean().optional().default(false).describe("Also open the visual dashboard (default: false)"),
+    }, async (args) => {
+        try {
+            emitActivity("navigate", { path: "/endpoints" });
+            const result = await callBackend("endpoints_dashboard", args);
+            const asRecord = result;
+            if (args.open_ui) {
+                return withFrontendUrl(enrichEndpointsBrowserUrl(asRecord), "/endpoints");
+            }
+            if (args.format === "text" && typeof result === "string") {
+                return { content: [{ type: "text", text: result }] };
+            }
+            const enriched = typeof result === "object" && result !== null && !Array.isArray(result)
+                ? { ...enrichEndpointsBrowserUrl(asRecord), ...agentSessionPayload("/endpoints") }
+                : result;
+            return {
+                content: [{
+                        type: "text",
+                        text: typeof enriched === "string" ? enriched : JSON.stringify(enriched),
+                    }],
+            };
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                next_actions: ["DEPRECATED: Use get_endpoints instead."],
+                related_tools: ["get_endpoints"],
+            });
+        }
+    });
+    // ── opentest_login ─────────────────────────────────────────────────
+    server.tool("opentest_login", "Authenticate with OpenTest. 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 opentest_login_complete with device_code.", {
+        device_name: z.string().optional().describe("Friendly name for this device (e.g. 'My MacBook')"),
+    }, async (args) => {
+        if (API_KEY) {
+            const check = await verifyApiKey(API_KEY);
+            if (check.valid) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                status: "already_authenticated",
+                                email: check.email,
+                                message: `Already logged in as ${check.email ?? "unknown"}. Use opentest_logout first if you want to switch accounts.`,
+                            }),
+                        }],
+                };
+            }
+        }
+        const deviceName = args.device_name || `${os.hostname()} MCP`;
+        try {
+            const reqResp = await fetch(`${BACKEND_URL}/auth/device/request`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ device_name: deviceName }),
+            });
+            if (!reqResp.ok) {
+                const text = await reqResp.text();
+                throw new Error(`Device auth request failed: ${reqResp.status} ${text}`);
+            }
+            const reqData = await reqResp.json();
+            const deviceCode = reqData.device_code;
+            const userCode = reqData.user_code;
+            const verificationUrl = reqData.verification_url;
+            const expiresIn = reqData.expires_in ?? 600;
+            const pollInterval = reqData.poll_interval ?? 5;
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            status: "awaiting_approval",
+                            user_code: userCode,
+                            verification_url: verificationUrl,
+                            expires_in_seconds: expiresIn,
+                            poll_interval_seconds: pollInterval,
+                            _device_code: deviceCode,
+                            instructions: [
+                                `Open this URL to approve: ${verificationUrl}`,
+                                `Your code is: ${userCode}`,
+                                "Log in (if needed) and click Approve.",
+                                "Then run opentest_login_complete to finish setup.",
+                            ],
+                            _cursor_agent_steps: [
+                                `Use Cursor Agent Browser: browser_navigate to: ${verificationUrl}`,
+                                `The user code is ${userCode}. The user must log in and approve.`,
+                                `After the user approves, call opentest_login_complete with device_code="${deviceCode}" to finish.`,
+                            ],
+                        }),
+                    }],
+            };
+        }
+        catch (e) {
+            return toolError(e.message, "backend_error", { next_actions: ["Retry opentest_login"], related_tools: ["opentest_login"] });
+        }
+    });
+    // ── opentest_login_complete ────────────────────────────────────────
+    // Polls the backend for the approved API key after the user approves
+    // the device request in the browser.
+    server.tool("opentest_login_complete", "Complete the login flow after the user approved the device request in the browser. Polls for the API key and stores it locally.", {
+        device_code: z.string().describe("The device_code returned by opentest_login"),
+    }, async (args) => {
+        const maxAttempts = 60;
+        const pollMs = 5000;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            try {
+                const resp = await fetch(`${BACKEND_URL}/auth/device/poll`, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify({ device_code: args.device_code }),
+                });
+                if (!resp.ok) {
+                    const text = await resp.text();
+                    throw new Error(`Poll error: ${resp.status} ${text}`);
+                }
+                const data = await resp.json();
+                const status = data.status;
+                if (status === "approved" && data.api_key) {
+                    const apiKey = data.api_key;
+                    API_KEY = apiKey;
+                    const check = await verifyApiKey(apiKey);
+                    await saveCredentials({
+                        api_key: apiKey,
+                        backend_url: BACKEND_URL,
+                        user_email: check.email ?? data.user_email,
+                        created_at: new Date().toISOString(),
+                    });
+                    return {
+                        content: [{
+                                type: "text",
+                                text: JSON.stringify({
+                                    status: "authenticated",
+                                    email: check.email,
+                                    message: `Successfully authenticated as ${check.email ?? "unknown"}. Credentials saved — you won't need to log in again.`,
+                                    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).`,
+                                            "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.",
+                                        ],
+                                        related_tools: ["get_endpoints", "test_api", "import_collection"],
+                                    },
+                                }),
+                            }],
+                    };
+                }
+                if (status === "expired") {
+                    return toolError("Device authorization request expired. Run opentest_login again.", "auth_required", {
+                        next_actions: ["Re-run opentest_login"],
+                        related_tools: ["opentest_login"],
+                    });
+                }
+                // Still pending — wait and retry
+                await new Promise((r) => setTimeout(r, pollMs));
+            }
+            catch (e) {
+                return toolError(e.message, "backend_error", { next_actions: ["Re-run opentest_login"], related_tools: ["opentest_login"] });
+            }
+        }
+        return toolError("Timed out waiting for approval. Run opentest_login again.", "auth_required", {
+            next_actions: ["Re-run opentest_login"],
+            related_tools: ["opentest_login"],
+        });
+    });
+    // ── opentest_status ────────────────────────────────────────────────
+    server.tool("opentest_status", "Check OpenTest authentication status and connection info.", {}, async () => {
+        if (!API_KEY) {
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            authenticated: false,
+                            backend_url: BACKEND_URL,
+                            frontend_base_url: FRONTEND_BASE,
+                            endpoints_page_url: buildAgentDashboardUrl("/endpoints"),
+                            message: "Not authenticated. Run opentest_login to connect your account.",
+                        }),
+                    }],
+            };
+        }
+        const check = await verifyApiKey(API_KEY);
+        if (!check.valid) {
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            authenticated: false,
+                            backend_url: BACKEND_URL,
+                            frontend_base_url: FRONTEND_BASE,
+                            endpoints_page_url: buildAgentDashboardUrl("/endpoints"),
+                            message: "Stored API key is no longer valid. Run opentest_login to re-authenticate.",
+                        }),
+                    }],
+            };
+        }
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        authenticated: true,
+                        email: check.email,
+                        key_name: check.key_name,
+                        backend_url: BACKEND_URL,
+                        frontend_base_url: FRONTEND_BASE,
+                        endpoints_page_url: buildAgentDashboardUrl("/endpoints"),
+                        _agent_hints: {
+                            next_actions: [
+                                "browser_navigate to `endpoints_page_url` (SPA shell + ot_agent_route) to open Flow on the Endpoints page (sign in if prompted), then call get_endpoints.",
+                                "Call get_endpoints to see registered API endpoints.",
+                                "Call test_api to test an endpoint.",
+                            ],
+                            related_tools: ["get_endpoints", "test_api", "import_collection"],
+                        },
+                    }),
+                }],
+        };
+    });
+    // ── opentest_logout ────────────────────────────────────────────────
+    server.tool("opentest_logout", "Log out of OpenTest. Clears stored credentials so you can switch accounts or re-authenticate.", {}, async () => {
+        const wasAuthenticated = !!API_KEY;
+        API_KEY = "";
+        await clearCredentials();
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        status: "logged_out",
+                        was_authenticated: wasAuthenticated,
+                        message: wasAuthenticated
+                            ? "Logged out and credentials cleared. Run opentest_login to sign in again."
+                            : "No credentials to clear. Already logged out.",
+                    }),
+                }],
+        };
+    });
+    // ── App user auth (JWT) — same server as opentest-local / OPENTEST_BACKEND
+    registerUserAuthFlowTools(server, BACKEND_URL);
+    // ── Hosted MCP platform tools ──────────────────────────────────────
+    // Thin stdio proxies; all real logic lives in flowtest/mcp/hosted_mcp_tools.py
+    // and is reached via the /mcp/call-tool HTTP bridge.
+    server.tool("discover_endpoints_from_codebase", "Return a brief the coding agent follows to extract HTTP endpoints from the user's codebase. Call this first when the user asks to turn their API into an MCP — the returned instructions tell your agent how to walk the repo and what shape to produce. Then pass the findings to verify_endpoints_live.", {
+        base_path: z.string().optional().describe("Directory to scan (defaults to CWD)"),
+        framework_hint: z.string().optional().describe("fastapi | express | nestjs | rails | django | nextjs"),
+    }, async (args) => {
+        try {
+            const result = await callBackend("discover_endpoints_from_codebase", args);
+            return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                related_tools: ["verify_endpoints_live"],
+            });
+        }
+    });
+    server.tool("verify_endpoints_live", "Probe each proposed endpoint against the user's running local backend and classify the responses (confirmed / unconfirmed / unreachable / review). Collapses agent-extraction ambiguity into deterministic signal. Pass only the endpoints the agent proposed, with method + path_template at minimum.", {
+        endpoints: z.array(z.any()).describe("Endpoints proposed by discover_endpoints_from_codebase"),
+        local_base_url: z.string().describe("Where the backend is running, e.g. http://localhost:8000"),
+    }, async (args) => {
+        try {
+            const result = await callBackend("verify_endpoints_live", args);
+            return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                next_actions: ["Start the local backend, then retry."],
+                related_tools: ["discover_endpoints_from_codebase", "mcp_preview"],
+            });
+        }
+    });
+    server.tool("mcp_preview", "Pick endpoints matching an intent and generate a tool-schema preview. Also writes the same two-pane HTML to opentest-mcp/mcp-preview-last.html and returns preview_file_url — use Cursor Simple Browser or `node opentest-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. Does NOT write to the DB.", {
+        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().describe("Base URL the deployed MCP will proxy to"),
+    }, async (args) => {
+        try {
+            const result = await callBackend("mcp_preview", args);
+            const previewData = (result && typeof result === "object" && !Array.isArray(result))
+                ? result
+                : {};
+            const panelHtml = buildConversionPanelHtml(previewData);
+            const { absolutePath, fileUrl } = await writeMcpPreviewFile(panelHtml);
+            const basePayload = result && typeof result === "object" && !Array.isArray(result)
+                ? result
+                : { raw: result };
+            const withPreviewNav = {
+                ...basePayload,
+                preview_html_path: absolutePath,
+                preview_file_url: fileUrl,
+                _how_to_see_the_ui: [
+                    "Cursor may not show the embedded MCP app (no new tab is opened by default).",
+                    "Run `node opentest-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.",
+                    "File → Open on preview_html_path shows source, not a rendered page.",
+                ],
+            };
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(withPreviewNav, null, 0) },
+                    {
+                        type: "resource",
+                        resource: {
+                            uri: MCP_PREVIEW_RESOURCE_URI,
+                            mimeType: "text/html;profile=mcp-app",
+                            text: panelHtml,
+                        },
+                    },
+                    {
+                        type: "resource_link",
+                        name: "opentest-mcp-preview",
+                        title: "OpenTest · MCP Preview",
+                        uri: MCP_PREVIEW_RESOURCE_URI,
+                        mimeType: "text/html;profile=mcp-app",
+                    },
+                ],
+                _meta: { [RESOURCE_URI_META_KEY]: MCP_PREVIEW_RESOURCE_URI },
+            };
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                related_tools: ["mcp_deploy"],
+            });
+        }
+    });
+    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.", {
+        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"),
+        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."),
+    }, async (args) => {
+        try {
+            const result = await callBackend("mcp_deploy", args);
+            return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                related_tools: ["mcp_mint_consumer_token", "mcp_list_deployed"],
+            });
+        }
+    });
+    server.tool("mcp_list_deployed", "List the hosted MCPs the current user has deployed.", {}, async () => {
+        try {
+            const result = await callBackend("mcp_list_deployed", {});
+            return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message));
+        }
+    });
+    server.tool("mcp_mint_consumer_token", "Mint a consumer token for a hosted MCP. The raw token is returned ONCE — only its hash is stored. Pass upstream_credential_id to map this consumer to a specific upstream credential; omit it to use the MCP's default credential.", {
+        hosted_mcp_id: z.string().describe("The hosted MCP's id"),
+        consumer_label: z.string().describe("Human-readable label for this consumer, e.g. 'acme-beta-bob'"),
+        upstream_credential_id: z.string().optional().describe("Optional credential mapping for this consumer token"),
+    }, async (args) => {
+        try {
+            const result = await callBackend("mcp_mint_consumer_token", args);
+            return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                related_tools: ["mcp_revoke_consumer_token", "mcp_list_deployed"],
+            });
+        }
+    });
+    server.tool("mcp_revoke_consumer_token", "Revoke a consumer token so future invocations by that consumer are rejected. Idempotent — revoking an already-revoked token returns ok:true with already_revoked:true.", {
+        hosted_mcp_id: z.string().describe("The hosted MCP's id"),
+        token_id: z.string().describe("The consumer token's id (from mcp_mint_consumer_token's token.id)"),
+    }, async (args) => {
+        try {
+            const result = await callBackend("mcp_revoke_consumer_token", args);
+            return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message));
+        }
+    });
+    return server;
+}
+// ── Start ─────────────────────────────────────────────────────────────
+async function main() {
+    await initAuth();
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch(console.error);
+process.on("SIGINT", () => { process.exit(0); });
+process.on("SIGTERM", () => { process.exit(0); });