fetchsandbox-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FetchSandbox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# fetchsandbox-mcp
+
+Turn any OpenAPI spec into a working sandbox your AI agent can use, right from your IDE.
+
+This is the Model Context Protocol (MCP) server for [FetchSandbox](https://fetchsandbox.com). It exposes three tools that let Claude Code, Cursor, Cline, or any MCP-compatible client ingest an OpenAPI spec, list its workflows, and run them — with realistic, schema-validated responses for every endpoint.
+
+## Why
+
+Agents read raw OpenAPI specs and hallucinate. They guess field names, invent IDs that won't exist, and produce broken curl commands. FetchSandbox turns the spec into a stateful, AJV-validated sandbox so the agent can actually call the API and see real-shaped responses.
+
+Plug it into your IDE once, and any time you ask your agent "let me try the Stripe API" or "show me the GitHub issue lifecycle," it can do that — for real, end-to-end.
+
+## Install
+
+The MCP runs as a stdio process spawned by your IDE. There's nothing to install globally — `npx` runs the latest published version on demand.
+
+### Claude Code (`~/.config/claude/claude_code_settings.json` or your project's `.mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "fetchsandbox": {
+      "command": "npx",
+      "args": ["-y", "fetchsandbox-mcp"]
+    }
+  }
+}
+```
+
+### Cursor (`~/.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "fetchsandbox": {
+      "command": "npx",
+      "args": ["-y", "fetchsandbox-mcp"]
+    }
+  }
+}
+```
+
+Restart your IDE after editing the config. The tools `import_spec`, `list_workflows`, and `run_workflow` become available to your agent.
+
+## Tools
+
+### `import_spec`
+
+Ingest an OpenAPI 3.x spec and get a sandbox you can call. Pass either a public URL or pasted content.
+
+```
+url:     "https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json"
+content: "<paste OpenAPI JSON or YAML here>"
+name:    "Optional friendly name"
+```
+
+Returns `spec_id`, `sandbox_id`, `base_url` (proxy that serves real-shaped responses), workflow list, and a `dashboard_url` to view everything in the browser.
+
+### `list_workflows`
+
+List the named, runnable workflows the engine inferred or curated for an imported spec.
+
+```
+spec_id: "<id from import_spec>"
+```
+
+### `run_workflow`
+
+Execute one workflow and return the step-by-step request/response trace. Template variables (`{{step1.id}}`) are resolved automatically between steps.
+
+```
+sandbox_id:    "<id from import_spec>"
+workflow_name: "<id or name from list_workflows>"
+```
+
+## Configuration
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `FETCHSANDBOX_BASE_URL` | `https://fetchsandbox.com` | Override for stage testing or self-hosted backends. |
+| `FETCHSANDBOX_TELEMETRY` | (on) | Set to `0` to disable anonymous usage telemetry. |
+
+### What we record
+
+When telemetry is on, each tool call records: an opaque per-machine session id (random UUID stored at `~/.fetchsandbox/session.json`), the tool name, latency, success/failure, and the spec URL or `"pasted"`. We do **not** record spec content, request bodies, or credentials. We use this to count daily-active sessions and learn which APIs people are bringing to the platform — full breakdown is open-source in [`mcp_telemetry.py`](https://github.com/rnagulapalle/sandbox/blob/main/backend/app/flows/mcp_telemetry.py).
+
+To opt out:
+
+```bash
+export FETCHSANDBOX_TELEMETRY=0
+```
+
+## Example session
+
+> **You:** Try the Stripe API. Use this spec: https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json
+>
+> **Agent:** *(calls `import_spec`)* Imported. 471 endpoints, 12 workflows including customer-create, subscription-lifecycle, refund-flow.
+>
+> **You:** Run the subscription-lifecycle one.
+>
+> **Agent:** *(calls `run_workflow`)* All 5 steps passed: created customer (cus_LJ4nQ...), attached payment method (pm_8K2...), created subscription (sub_R6F...), updated to a different price (sub.items.0 swap), canceled subscription. Here's the trace: ...
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Links
+
+- [FetchSandbox](https://fetchsandbox.com)
+- [Source code](https://github.com/rnagulapalle/sandbox/tree/main/mcp)
+- [Issues](https://github.com/rnagulapalle/sandbox/issues)

package/dist/client.d.ts

@@ -0,0 +1,7 @@
+export declare class ToolError extends Error {
+    status?: number;
+    constructor(message: string, status?: number);
+}
+export declare function getBaseUrl(): string;
+export declare function postJson<T>(path: string, body: unknown): Promise<T>;
+export declare function getJson<T>(path: string): Promise<T>;

package/dist/client.js

@@ -0,0 +1,114 @@
+/**
+ * Thin HTTP client for the FetchSandbox backend.
+ *
+ * Base URL defaults to https://fetchsandbox.com. Override via
+ * FETCHSANDBOX_BASE_URL for stage testing or self-hosted deployments.
+ *
+ * Errors are normalized into ToolError so tools can surface them to the
+ * agent as readable text instead of a stack trace.
+ */
+import { getSessionId } from "./session.js";
+const DEFAULT_BASE_URL = "https://fetchsandbox.com";
+const REQUEST_TIMEOUT_MS = 30_000;
+// Retry only on transient failures: nginx 502/503/504 + network errors.
+// 4xx responses (bad spec, validation errors) should fail fast.
+const RETRY_STATUSES = new Set([502, 503, 504]);
+const MAX_RETRIES = 1;
+const RETRY_BACKOFF_MS = 1500;
+export class ToolError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = "ToolError";
+        this.status = status;
+    }
+}
+export function getBaseUrl() {
+    return (process.env.FETCHSANDBOX_BASE_URL || DEFAULT_BASE_URL).replace(/\/+$/, "");
+}
+function buildHeaders(extra) {
+    const headers = {
+        "user-agent": `fetchsandbox-mcp/0.1.0 (node ${process.version})`,
+        accept: "application/json",
+        ...(extra ?? {}),
+    };
+    const sid = getSessionId();
+    if (sid)
+        headers["x-mcp-session-id"] = sid;
+    return headers;
+}
+async function readErrorMessage(res) {
+    try {
+        const body = await res.text();
+        if (!body)
+            return `HTTP ${res.status}`;
+        try {
+            const j = JSON.parse(body);
+            if (typeof j === "object" && j !== null && "detail" in j)
+                return String(j.detail);
+        }
+        catch {
+            // not JSON
+        }
+        return body.slice(0, 500);
+    }
+    catch {
+        return `HTTP ${res.status}`;
+    }
+}
+async function fetchWithRetry(url, init, method, path) {
+    let lastErr;
+    let lastStatus = null;
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), REQUEST_TIMEOUT_MS);
+        try {
+            const res = await fetch(url, { ...init, signal: ctrl.signal });
+            clearTimeout(timer);
+            if (res.ok)
+                return res;
+            // Retry on transient upstream errors only.
+            if (RETRY_STATUSES.has(res.status) && attempt < MAX_RETRIES) {
+                lastStatus = res.status;
+                await new Promise((r) => setTimeout(r, RETRY_BACKOFF_MS));
+                continue;
+            }
+            // Non-retryable error — surface as ToolError immediately.
+            throw new ToolError(await readErrorMessage(res), res.status);
+        }
+        catch (e) {
+            clearTimeout(timer);
+            if (e instanceof ToolError)
+                throw e;
+            lastErr = e;
+            const errName = e.name;
+            const isAbort = errName === "AbortError";
+            // Retry network-level failures (DNS, ECONNRESET, timeouts)
+            if (attempt < MAX_RETRIES && (isAbort || errName === "TypeError" || errName === "FetchError")) {
+                await new Promise((r) => setTimeout(r, RETRY_BACKOFF_MS));
+                continue;
+            }
+            if (isAbort) {
+                throw new ToolError(`Request timed out after ${REQUEST_TIMEOUT_MS / 1000}s: ${method} ${path}`);
+            }
+            throw new ToolError(`Network error calling ${path}: ${e.message}`);
+        }
+    }
+    // Loop exhausted with retries exhausted on transient status code.
+    throw new ToolError(`Upstream returned ${lastStatus ?? "error"} after ${MAX_RETRIES + 1} attempts: ${method} ${path}`, lastStatus ?? undefined);
+}
+export async function postJson(path, body) {
+    const url = `${getBaseUrl()}${path}`;
+    const res = await fetchWithRetry(url, {
+        method: "POST",
+        headers: buildHeaders({ "content-type": "application/json" }),
+        body: JSON.stringify(body),
+    }, "POST", path);
+    return (await res.json());
+}
+export async function getJson(path) {
+    const url = `${getBaseUrl()}${path}`;
+    const res = await fetchWithRetry(url, { headers: buildHeaders() }, "GET", path);
+    return (await res.json());
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+/**
+ * fetchsandbox-mcp — Model Context Protocol server.
+ *
+ * Exposes three tools to any MCP client (Claude Code, Cursor, Cline, etc.):
+ *   - import_spec      Ingest an OpenAPI spec; get a sandbox you can call.
+ *   - list_workflows   List named, runnable workflows for an imported spec.
+ *   - run_workflow     Execute a workflow and return the step trace.
+ *
+ * Talks to the FetchSandbox backend over HTTPS. Defaults to fetchsandbox.com;
+ * override with FETCHSANDBOX_BASE_URL for stage or self-hosted use.
+ *
+ * Distribution: npx -y fetchsandbox-mcp.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { ToolError, getBaseUrl } from "./client.js";
+import { importSpecTool, runImportSpec } from "./tools/import_spec.js";
+import { listWorkflowsTool, runListWorkflows } from "./tools/list_workflows.js";
+import { runRunWorkflow, runWorkflowTool } from "./tools/run_workflow.js";
+const VERSION = "0.1.0";
+const server = new Server({ name: "fetchsandbox", version: VERSION }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [importSpecTool, listWorkflowsTool, runWorkflowTool],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const { name, arguments: args } = req.params;
+    try {
+        let result;
+        const a = (args ?? {});
+        switch (name) {
+            case importSpecTool.name:
+                result = await runImportSpec({
+                    url: typeof a.url === "string" ? a.url : undefined,
+                    content: typeof a.content === "string" ? a.content : undefined,
+                    name: typeof a.name === "string" ? a.name : undefined,
+                });
+                break;
+            case listWorkflowsTool.name:
+                result = await runListWorkflows({
+                    spec_id: typeof a.spec_id === "string" ? a.spec_id : "",
+                });
+                break;
+            case runWorkflowTool.name:
+                result = await runRunWorkflow({
+                    sandbox_id: typeof a.sandbox_id === "string" ? a.sandbox_id : "",
+                    workflow_name: typeof a.workflow_name === "string" ? a.workflow_name : "",
+                });
+                break;
+            default:
+                throw new ToolError(`Unknown tool: ${name}`);
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        return {
+            content: [{ type: "text", text: friendlyError(name, msg, e) }],
+            isError: true,
+        };
+    }
+});
+function friendlyError(toolName, msg, err) {
+    // Surface common backend errors as agent-readable hints instead of raw HTTP.
+    const status = err instanceof ToolError ? err.status : undefined;
+    const m = msg.toLowerCase();
+    if (m.includes("not a valid openapi spec") || m.includes("missing 'openapi'")) {
+        return (`Error: that file isn't an OpenAPI 3.x spec — it's missing the top-level "openapi" key. ` +
+            `If you have a Swagger 2.0 spec, convert it first (e.g. with swagger-converter). Original: ${msg}`);
+    }
+    if (m.includes("non-public ip") || m.includes("loopback") || m.includes("did not resolve")) {
+        return (`Error: that URL can't be fetched — it's either non-public, points to a private network, or doesn't resolve. ` +
+            `Public OpenAPI URLs (raw.githubusercontent.com, vendor docs portals) work; localhost and internal hosts don't. ` +
+            `Original: ${msg}`);
+    }
+    if (m.includes("must be http")) {
+        return `Error: spec URL must use http or https. Original: ${msg}`;
+    }
+    if (m.includes("spec url returned http 404")) {
+        return (`Error: the spec URL returned 404. Double-check the link and try again. ` +
+            `For GitHub, use the raw.githubusercontent.com URL, not the github.com page URL. Original: ${msg}`);
+    }
+    if (m.includes("exceeds") && m.includes("mb cap")) {
+        return (`Error: spec is too large. Hard cap is 20 MB. Original: ${msg}`);
+    }
+    if (m.includes("workflow") && m.includes("not found")) {
+        return (`Error: that workflow name isn't recognized. Call list_workflows(spec_id=...) first to see ` +
+            `the exact ids. Original: ${msg}`);
+    }
+    if (m.includes("sandbox") && m.includes("not found")) {
+        return (`Error: that sandbox_id isn't recognized — sandboxes from previous sessions don't persist. ` +
+            `Call import_spec again to get a fresh one. Original: ${msg}`);
+    }
+    if (status === 502 || status === 503 || status === 504) {
+        return (`Error: backend returned ${status} (service unavailable). The MCP retried once; if you see this, ` +
+            `the upstream is down. Try again in a minute. Original: ${msg}`);
+    }
+    if (m.includes("timed out")) {
+        return (`Error: backend didn't respond within 30s. Large specs (Stripe, GitHub) sometimes take 10-15s ` +
+            `on first import; if it's still slow, try a different network. Original: ${msg}`);
+    }
+    // Default: pass through the message as-is.
+    return `Error in ${toolName}: ${msg}`;
+}
+async function main() {
+    // Print to stderr only — stdout is reserved for the MCP protocol.
+    process.stderr.write(`[fetchsandbox-mcp ${VERSION}] connected to ${getBaseUrl()}\n`);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    process.stderr.write(`[fetchsandbox-mcp] fatal: ${err?.stack ?? err}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/session.d.ts

@@ -0,0 +1,2 @@
+export declare function telemetryEnabled(): boolean;
+export declare function getSessionId(): string | undefined;

package/dist/session.js

@@ -0,0 +1,47 @@
+/**
+ * Stable per-machine session id, persisted at ~/.fetchsandbox/session.json.
+ *
+ * Used as X-MCP-Session-Id on every backend request so DAU is countable.
+ * The id is opaque (random uuid) and reveals nothing about the machine.
+ *
+ * Disabled entirely when FETCHSANDBOX_TELEMETRY=0 — in that case sessionId
+ * returns undefined and the client omits the header.
+ */
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const SESSION_DIR = join(homedir(), ".fetchsandbox");
+const SESSION_FILE = join(SESSION_DIR, "session.json");
+let cached = null; // null = not yet loaded
+export function telemetryEnabled() {
+    return process.env.FETCHSANDBOX_TELEMETRY !== "0";
+}
+export function getSessionId() {
+    if (!telemetryEnabled())
+        return undefined;
+    if (cached !== null)
+        return cached ?? undefined;
+    try {
+        const raw = readFileSync(SESSION_FILE, "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed.id === "string") {
+            cached = parsed.id;
+            return cached;
+        }
+    }
+    catch {
+        // fall through to creation
+    }
+    const id = randomUUID();
+    try {
+        mkdirSync(SESSION_DIR, { recursive: true });
+        writeFileSync(SESSION_FILE, JSON.stringify({ id, createdAt: new Date().toISOString() }, null, 2));
+    }
+    catch {
+        // best-effort; if we can't write, still return the id for this run
+    }
+    cached = id;
+    return cached;
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,eAAe,CAAC,CAAC;AACrD,MAAM,YAAY,GAAG,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC;AAEvD,IAAI,MAAM,GAA8B,IAAI,CAAC,CAAC,wBAAwB;AAEtE,MAAM,UAAU,gBAAgB;IAC9B,OAAO,OAAO,CAAC,GAAG,CAAC,sBAAsB,KAAK,GAAG,CAAC;AACpD,CAAC;AAED,MAAM,UAAU,YAAY;IAC1B,IAAI,CAAC,gBAAgB,EAAE;QAAE,OAAO,SAAS,CAAC;IAC1C,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,MAAM,IAAI,SAAS,CAAC;IAChD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;QAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,MAAM,IAAI,OAAO,MAAM,CAAC,EAAE,KAAK,QAAQ,EAAE,CAAC;YAC5C,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;YACnB,OAAO,MAAO,CAAC;QACjB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,2BAA2B;IAC7B,CAAC;IACD,MAAM,EAAE,GAAG,UAAU,EAAE,CAAC;IACxB,IAAI,CAAC;QACH,SAAS,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5C,aAAa,CAAC,YAAY,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IACpG,CAAC;IAAC,MAAM,CAAC;QACP,mEAAmE;IACrE,CAAC;IACD,MAAM,GAAG,EAAE,CAAC;IACZ,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/tools/import_spec.d.ts

@@ -0,0 +1,49 @@
+export interface ImportSpecInput {
+    url?: string;
+    content?: string;
+    name?: string;
+}
+interface WorkflowSummary {
+    name: string;
+    title: string;
+    description: string;
+    steps_count: number;
+    source_type: string;
+}
+export interface ImportSpecResponse {
+    spec_id: string;
+    sandbox_id: string;
+    name: string;
+    version: string;
+    endpoint_count: number;
+    workflow_count: number;
+    base_url: string;
+    dashboard_url: string;
+    workflows_preview: WorkflowSummary[];
+    workflows_truncated: boolean;
+    next_step_hint: string;
+}
+export declare const importSpecTool: {
+    readonly name: "import_spec";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly url: {
+                readonly type: "string";
+                readonly description: string;
+            };
+            readonly content: {
+                readonly type: "string";
+                readonly description: string;
+            };
+            readonly name: {
+                readonly type: "string";
+                readonly description: string;
+            };
+        };
+        readonly additionalProperties: false;
+    };
+};
+export declare function runImportSpec(input: ImportSpecInput): Promise<ImportSpecResponse>;
+export {};

package/dist/tools/import_spec.js

@@ -0,0 +1,46 @@
+import { postJson, ToolError } from "../client.js";
+export const importSpecTool = {
+    name: "import_spec",
+    description: "Ingest an OpenAPI spec and get a working sandbox you can call immediately. " +
+        "Use this when the user wants to try, test, or learn an API. Accepts a public " +
+        "URL to an OpenAPI 3.x JSON or YAML file (e.g. raw.githubusercontent.com link), " +
+        "or pasted spec content as a string. Returns a sandbox_id that can be used with " +
+        "list_workflows and run_workflow, plus a base_url that proxies real-feeling, " +
+        "schema-validated responses for every endpoint in the spec. " +
+        "Pick this tool the moment the user mentions an OpenAPI URL or pastes a spec. " +
+        "Note on URLs: this MCP runs locally (in the user's IDE process), but the spec " +
+        "fetch happens on the FetchSandbox backend — so private addresses (localhost, " +
+        "127.0.0.1, 10.x, 192.168.x, internal company hosts) will be rejected. For those, " +
+        "have the user paste the spec content directly via the `content` parameter.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            url: {
+                type: "string",
+                description: "Public URL to an OpenAPI 3.x file (JSON or YAML). Use this for any " +
+                    "publicly reachable spec — GitHub raw links, docs portals, vendor SDKs.",
+            },
+            content: {
+                type: "string",
+                description: "Pasted OpenAPI spec content (JSON or YAML). Use this when the user " +
+                    "pastes the spec inline or has it on disk. Provide the raw text exactly.",
+            },
+            name: {
+                type: "string",
+                description: "Optional friendly name for the spec. Defaults to info.title from the " +
+                    "spec, or the URL hostname.",
+            },
+        },
+        additionalProperties: false,
+    },
+};
+export async function runImportSpec(input) {
+    if (!input.url && !input.content) {
+        throw new ToolError("Provide either 'url' or 'content'.");
+    }
+    if (input.url && input.content) {
+        throw new ToolError("Provide 'url' or 'content', not both.");
+    }
+    return postJson("/api/mcp/import-spec", input);
+}
+//# sourceMappingURL=import_spec.js.map

package/dist/tools/import_spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"import_spec.js","sourceRoot":"","sources":["../../src/tools/import_spec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AA8BnD,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,IAAI,EAAE,aAAa;IACnB,WAAW,EACT,6EAA6E;QAC7E,+EAA+E;QAC/E,iFAAiF;QACjF,iFAAiF;QACjF,8EAA8E;QAC9E,6DAA6D;QAC7D,+EAA+E;QAC/E,gFAAgF;QAChF,+EAA+E;QAC/E,mFAAmF;QACnF,4EAA4E;IAC9E,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,GAAG,EAAE;gBACH,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,qEAAqE;oBACrE,wEAAwE;aAC3E;YACD,OAAO,EAAE;gBACP,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,qEAAqE;oBACrE,yEAAyE;aAC5E;YACD,IAAI,EAAE;gBACJ,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,uEAAuE;oBACvE,4BAA4B;aAC/B;SACF;QACD,oBAAoB,EAAE,KAAK;KAC5B;CACO,CAAC;AAEX,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,KAAsB;IACxD,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QACjC,MAAM,IAAI,SAAS,CAAC,oCAAoC,CAAC,CAAC;IAC5D,CAAC;IACD,IAAI,KAAK,CAAC,GAAG,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QAC/B,MAAM,IAAI,SAAS,CAAC,uCAAuC,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,QAAQ,CAAqB,sBAAsB,EAAE,KAAK,CAAC,CAAC;AACrE,CAAC"}

package/dist/tools/list_workflows.d.ts

@@ -0,0 +1,34 @@
+export interface ListWorkflowsInput {
+    spec_id: string;
+}
+export interface WorkflowItem {
+    id: string;
+    name: string;
+    description?: string;
+    steps?: unknown[];
+}
+export interface ListWorkflowsResponse {
+    spec_id: string;
+    workflows: Array<{
+        id: string;
+        name: string;
+        description: string;
+        steps_count: number;
+    }>;
+}
+export declare const listWorkflowsTool: {
+    readonly name: "list_workflows";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly spec_id: {
+                readonly type: "string";
+                readonly description: "The spec_id returned by import_spec.";
+            };
+        };
+        readonly required: readonly ["spec_id"];
+        readonly additionalProperties: false;
+    };
+};
+export declare function runListWorkflows(input: ListWorkflowsInput): Promise<ListWorkflowsResponse>;

package/dist/tools/list_workflows.js

@@ -0,0 +1,36 @@
+import { getJson, ToolError } from "../client.js";
+export const listWorkflowsTool = {
+    name: "list_workflows",
+    description: "List the named, runnable workflows discovered for a previously-imported " +
+        "spec. Workflows are realistic multi-step API journeys (e.g. 'create " +
+        "customer then attach payment method then create subscription'). Use this " +
+        "after import_spec when the user asks 'what can I do?' or 'show me the " +
+        "common flows' or wants to pick one to run. Returns id, name, description, " +
+        "and step count for each workflow.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            spec_id: {
+                type: "string",
+                description: "The spec_id returned by import_spec.",
+            },
+        },
+        required: ["spec_id"],
+        additionalProperties: false,
+    },
+};
+export async function runListWorkflows(input) {
+    if (!input.spec_id)
+        throw new ToolError("spec_id is required.");
+    const raw = await getJson(`/api/specs/${encodeURIComponent(input.spec_id)}/workflows`);
+    return {
+        spec_id: input.spec_id,
+        workflows: (raw.workflows || []).map((w) => ({
+            id: w.id || w.name || "",
+            name: w.name || w.id || "",
+            description: w.description || "",
+            steps_count: Array.isArray(w.steps) ? w.steps.length : 0,
+        })),
+    };
+}
+//# sourceMappingURL=list_workflows.js.map

package/dist/tools/list_workflows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list_workflows.js","sourceRoot":"","sources":["../../src/tools/list_workflows.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AA2BlD,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,IAAI,EAAE,gBAAgB;IACtB,WAAW,EACT,0EAA0E;QAC1E,sEAAsE;QACtE,2EAA2E;QAC3E,wEAAwE;QACxE,4EAA4E;QAC5E,mCAAmC;IACrC,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,OAAO,EAAE;gBACP,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,sCAAsC;aACpD;SACF;QACD,QAAQ,EAAE,CAAC,SAAS,CAAC;QACrB,oBAAoB,EAAE,KAAK;KAC5B;CACO,CAAC;AAEX,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,KAAyB;IAC9D,IAAI,CAAC,KAAK,CAAC,OAAO;QAAE,MAAM,IAAI,SAAS,CAAC,sBAAsB,CAAC,CAAC;IAChE,MAAM,GAAG,GAAG,MAAM,OAAO,CACvB,cAAc,kBAAkB,CAAC,KAAK,CAAC,OAAO,CAAC,YAAY,CAC5D,CAAC;IACF,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,SAAS,EAAE,CAAC,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC3C,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,IAAI,IAAI,EAAE;YACxB,IAAI,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE;YAC1B,WAAW,EAAE,CAAC,CAAC,WAAW,IAAI,EAAE;YAChC,WAAW,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;SACzD,CAAC,CAAC;KACJ,CAAC;AACJ,CAAC"}

package/dist/tools/run_workflow.d.ts

@@ -0,0 +1,42 @@
+export interface RunWorkflowInput {
+    sandbox_id: string;
+    workflow_name: string;
+}
+interface BackendStepResult {
+    name?: string;
+    description?: string;
+    status?: string;
+    detail?: string;
+    duration_ms?: number;
+    data?: unknown;
+}
+export interface NormalizedRunResult {
+    workflow_name: string;
+    description: string;
+    status: "pass" | "fail";
+    total_duration_ms: number;
+    steps_passed: number;
+    steps_total: number;
+    steps: BackendStepResult[];
+}
+export declare const runWorkflowTool: {
+    readonly name: "run_workflow";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly sandbox_id: {
+                readonly type: "string";
+                readonly description: "The sandbox_id returned by import_spec.";
+            };
+            readonly workflow_name: {
+                readonly type: "string";
+                readonly description: string;
+            };
+        };
+        readonly required: readonly ["sandbox_id", "workflow_name"];
+        readonly additionalProperties: false;
+    };
+};
+export declare function runRunWorkflow(input: RunWorkflowInput): Promise<NormalizedRunResult>;
+export {};

package/dist/tools/run_workflow.js

@@ -0,0 +1,47 @@
+import { postJson, ToolError } from "../client.js";
+export const runWorkflowTool = {
+    name: "run_workflow",
+    description: "Execute one workflow against a previously-imported sandbox and return the " +
+        "step-by-step request/response trace. Each step shows the HTTP call, the " +
+        "schema-validated response body, and whether the step passed. Template " +
+        "variables (e.g. {{step1.id}}) are resolved automatically between steps so " +
+        "later steps can reference IDs returned by earlier ones. Use this after " +
+        "list_workflows when the user picks one, or directly if they name a " +
+        "specific workflow.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            sandbox_id: {
+                type: "string",
+                description: "The sandbox_id returned by import_spec.",
+            },
+            workflow_name: {
+                type: "string",
+                description: "Workflow id or name from list_workflows. Case-insensitive; dashes and " +
+                    "underscores are interchangeable.",
+            },
+        },
+        required: ["sandbox_id", "workflow_name"],
+        additionalProperties: false,
+    },
+};
+export async function runRunWorkflow(input) {
+    if (!input.sandbox_id)
+        throw new ToolError("sandbox_id is required.");
+    if (!input.workflow_name)
+        throw new ToolError("workflow_name is required.");
+    const path = `/api/sandboxes/${encodeURIComponent(input.sandbox_id)}/workflows/${encodeURIComponent(input.workflow_name)}/run`;
+    const raw = await postJson(path, {});
+    const steps = raw.steps ?? [];
+    const passedSteps = steps.filter((s) => s.status === "passed").length;
+    return {
+        workflow_name: raw.flow_name ?? input.workflow_name,
+        description: raw.flow_description ?? "",
+        status: raw.passed ? "pass" : "fail",
+        total_duration_ms: raw.total_duration_ms ?? 0,
+        steps_passed: passedSteps,
+        steps_total: steps.length,
+        steps,
+    };
+}
+//# sourceMappingURL=run_workflow.js.map

package/dist/tools/run_workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run_workflow.js","sourceRoot":"","sources":["../../src/tools/run_workflow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAmCnD,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,IAAI,EAAE,cAAc;IACpB,WAAW,EACT,4EAA4E;QAC5E,0EAA0E;QAC1E,wEAAwE;QACxE,4EAA4E;QAC5E,yEAAyE;QACzE,qEAAqE;QACrE,oBAAoB;IACtB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,yCAAyC;aACvD;YACD,aAAa,EAAE;gBACb,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,wEAAwE;oBACxE,kCAAkC;aACrC;SACF;QACD,QAAQ,EAAE,CAAC,YAAY,EAAE,eAAe,CAAC;QACzC,oBAAoB,EAAE,KAAK;KAC5B;CACO,CAAC;AAEX,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,KAAuB;IAC1D,IAAI,CAAC,KAAK,CAAC,UAAU;QAAE,MAAM,IAAI,SAAS,CAAC,yBAAyB,CAAC,CAAC;IACtE,IAAI,CAAC,KAAK,CAAC,aAAa;QAAE,MAAM,IAAI,SAAS,CAAC,4BAA4B,CAAC,CAAC;IAC5E,MAAM,IAAI,GAAG,kBAAkB,kBAAkB,CAAC,KAAK,CAAC,UAAU,CAAC,cAAc,kBAAkB,CACjG,KAAK,CAAC,aAAa,CACpB,MAAM,CAAC;IACR,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAmB,IAAI,EAAE,EAAE,CAAC,CAAC;IACvD,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;IAC9B,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,MAAM,CAAC;IACtE,OAAO;QACL,aAAa,EAAE,GAAG,CAAC,SAAS,IAAI,KAAK,CAAC,aAAa;QACnD,WAAW,EAAE,GAAG,CAAC,gBAAgB,IAAI,EAAE;QACvC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM;QACpC,iBAAiB,EAAE,GAAG,CAAC,iBAAiB,IAAI,CAAC;QAC7C,YAAY,EAAE,WAAW;QACzB,WAAW,EAAE,KAAK,CAAC,MAAM;QACzB,KAAK;KACN,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "fetchsandbox-mcp",
+  "version": "0.1.0",
+  "description": "Turn any OpenAPI spec into a working sandbox your AI agent can use. MCP server for Claude Code, Cursor, and any other MCP-compatible LLM IDE.",
+  "license": "MIT",
+  "author": "FetchSandbox",
+  "homepage": "https://fetchsandbox.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rnagulapalle/sandbox.git",
+    "directory": "mcp"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "openapi",
+    "sandbox",
+    "api",
+    "claude",
+    "cursor",
+    "agent"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "fetchsandbox-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}