fetchsandbox-mcp 0.3.4 → 0.3.6

package/README.md

@@ -1,5 +1,8 @@
 # fetchsandbox-mcp
 
+<a href="https://www.producthunt.com/products/fetchsandbox?embed=true&utm_source=badge-featured&utm_medium=badge&utm_campaign=badge-fetchsandbox" target="_blank" rel="noopener noreferrer"><img alt="FetchSandbox - Runnable API integrations for developers and AI agents | Product Hunt" width="250" height="54" src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1175731&theme=light"></a>
+
+
 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 any MCP-compatible agent ingest an OpenAPI spec, list its workflows, and run them — with realistic, schema-validated responses for every endpoint.
@@ -131,39 +134,59 @@ If your agent speaks MCP, it accepts a stdio command. Use:
 
 ## Try it now
 
-After restarting your agent, paste any of these prompts. Each hits a hand-curated workflow with realistic IDs and real state transitions.
-
-### Stripe — accept a payment
+After restarting your agent, paste any of these prompts. Every prompt
+starts with the `./fetchsandbox` dispatch prefix — that's the routing
+signal. The brain matches your symptom to a workflow + scenario,
+reproduces it deterministically, and returns a public receipt URL as
+proof. **Variant prefixes also accepted:** `/fetchsandbox`,
+`@fetchsandbox`, `fs:`.
 
-> Use fetchsandbox to import the Stripe spec from `https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json` and run the `accept_payment` workflow. Show me the trace.
+### Stripe — investigate a webhook bug
 
-The agent imports 587 endpoints, matches the bundled curated Stripe sandbox, and runs a 6-step workflow: create customer (`cus_…`) → create PaymentIntent (`pi_…`, `$49.99 USD`, `requires_payment_method`) → confirm (`requires_capture`) → capture (`succeeded`) → retrieve → verify webhooks (`payment_intent.created`, `payment_intent.succeeded`).
+> `./fetchsandbox stripe webhook bug in prod — payments getting marked paid 2-3 times. fix it with proof.`
 
-### Twilio — send an SMS
+The brain matches the `webhook_duplicate_side_effect` pattern. The
+agent reproduces the bug via `accept_payment` + `webhook_retries`
+scenario, applies the fix from the brain's `fix_pattern`, re-runs to
+confirm, and surfaces the brain's `check_for` items as the audit list.
+Receipt URL is the proof artifact.
 
-> Use fetchsandbox to import the Twilio Messaging spec from `https://raw.githubusercontent.com/twilio/twilio-oai/main/spec/yaml/twilio_messaging_v1.yaml` and run the `send_sms` workflow.
+### Stripe — silent card decline
 
-The agent imports the messaging API and runs a curated send-and-verify flow with realistic Twilio-formatted message SIDs (`SM…`).
+> `./fetchsandbox stripe checkout fails silently when cards are declined — investigate and fix.`
 
-### GitHub — issue lifecycle
+Brain matches `card_decline_not_handled` → reproduces via
+`payment_declined` scenario → recommends the wrap-in-try/except fix
+pattern with `decline_code` surfacing.
 
-> Use fetchsandbox to import the GitHub REST API from `https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json` and run the `issue_lifecycle` workflow.
+### Stripe — webhook signature security
 
-The agent walks the create → comment → close → reopen flow against a real-shaped GitHub sandbox.
+> `./fetchsandbox stripe webhook security audit failed — anyone can post to the endpoint. fix it.`
 
-### Paddle — paste-content variant
+Brain matches `webhook_signature_unverified` → reproduces via
+`auth_failure` scenario → recommends the `stripe.Webhook.construct_event`
+fix with `STRIPE_WEBHOOK_SECRET` env sourcing.
 
-If a vendor doesn't publish their spec at a stable URL (Paddle, Notion, Linear), paste the content directly:
+### Build a new integration
 
-> Here's the Paddle Billing OpenAPI spec — `<paste JSON or YAML>`. Use fetchsandbox to import it and run the `subscriptions_canceled` workflow.
+> `./fetchsandbox help me integrate resend for transactional email`
 
-Same engine path; same curated quality if the spec's `info.title` matches a bundled config.
+Brain surfaces Resend's discovery questions (SPF/DKIM, bounce
+handling, etc.), routes to the right send-email workflow, and walks
+the implementation against a curated Resend sandbox.
 
 ### Any other API
 
-> Use fetchsandbox to import `<your OpenAPI URL>` — list the workflows and tell me which is most interesting.
+> `./fetchsandbox <your question or bug report about any API>`
 
-For specs we don't have curated configs for, the engine auto-enumerates `create + verify` workflows for every detected resource. Honest about what it shows: UUIDs instead of vendor-style IDs, generic enum values instead of API-specific ones — but the request/response shape and template substitution between steps still work.
+For Stripe, Resend, Clerk, Privy, Surge, AgentMail, Twilio, PayPal,
+Paddle, GitHub, OpenAI, Pinecone, Datadog, and 19 others, the brain
+routes via curated knowledge. For specs we don't have curated configs
+for, the engine auto-enumerates `create + verify` workflows for every
+detected resource. Honest about what it shows: UUIDs instead of
+vendor-style IDs, generic enum values instead of API-specific ones —
+but the request/response shape and template substitution between steps
+still work.
 
 ## Tools
 

package/dist/tools/run_workflow.d.ts

@@ -1,6 +1,7 @@
 export interface RunWorkflowInput {
     sandbox_id: string;
     workflow_name: string;
+    scenario?: string;
 }
 interface BackendStepResult {
     name?: string;
@@ -18,6 +19,9 @@ export interface NormalizedRunResult {
     steps_passed: number;
     steps_total: number;
     steps: BackendStepResult[];
+    share_url?: string;
+    flow_run_id?: string;
+    sandbox_id?: string;
 }
 export declare const runWorkflowTool: {
     readonly name: "run_workflow";
@@ -33,6 +37,10 @@ export declare const runWorkflowTool: {
                 readonly type: "string";
                 readonly description: string;
             };
+            readonly scenario: {
+                readonly type: "string";
+                readonly description: string;
+            };
         };
         readonly required: readonly ["sandbox_id", "workflow_name"];
         readonly additionalProperties: false;

package/dist/tools/run_workflow.js

@@ -1,7 +1,13 @@
 import { postJson, ToolError } from "../client.js";
 export const runWorkflowTool = {
     name: "run_workflow",
-    description: "Execute ONE specific workflow by name and return its step-by-step trace. " +
+    description: "Execute ONE specific workflow by name and return its step-by-step trace " +
+        "PLUS a `share_url` — a public, replayable proof URL that renders the " +
+        "full timeline (every request, response, webhook event) for this run. " +
+        "The share_url is the canonical 'here's what happened' artifact: surface " +
+        "it verbatim in any reply that needs evidence (PR comments, Slack " +
+        "threads, blog posts, X replies). Do NOT substitute a docs URL or any " +
+        "other link as the proof — the share_url is the only valid receipt. " +
         "Use ONLY when the user explicitly names a single workflow to run (e.g., " +
         "\"run accept_payment\", \"just check the refund workflow\"). For ANY " +
         "validation-style request — \"validate stripe\", \"check coverage\", \"run " +
@@ -22,6 +28,14 @@ export const runWorkflowTool = {
                 description: "Workflow id or name from list_workflows. Case-insensitive; dashes and " +
                     "underscores are interchangeable.",
             },
+            scenario: {
+                type: "string",
+                description: "OPTIONAL failure scenario to exercise (e.g. payment_declined, " +
+                    "insufficient_funds, fraud_hold). Toggles the sandbox engine's " +
+                    "scenario for the duration of the run, then restores. Use this for " +
+                    "'test with declined card' / 'simulate failure X' intents. Omit " +
+                    "for the happy path.",
+            },
         },
         required: ["sandbox_id", "workflow_name"],
         additionalProperties: false,
@@ -33,7 +47,11 @@ export async function runRunWorkflow(input) {
     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 body = {};
+    if (input.scenario && input.scenario.trim()) {
+        body.scenario = input.scenario.trim();
+    }
+    const raw = await postJson(path, body);
     const steps = raw.steps ?? [];
     const passedSteps = steps.filter((s) => s.status === "passed").length;
     return {
@@ -44,6 +62,9 @@ export async function runRunWorkflow(input) {
         steps_passed: passedSteps,
         steps_total: steps.length,
         steps,
+        share_url: raw.share_url,
+        flow_run_id: raw.flow_run_id,
+        sandbox_id: raw.sandbox_id ?? input.sandbox_id,
     };
 }
 //# sourceMappingURL=run_workflow.js.map

package/dist/tools/run_workflow.js.map

@@ -1 +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,2EAA2E;QAC3E,0EAA0E;QAC1E,uEAAuE;QACvE,4EAA4E;QAC5E,wEAAwE;QACxE,2DAA2D;QAC3D,yEAAyE;QACzE,yEAAyE;QACzE,qBAAqB;IACvB,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"}
+{"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;AAiDnD,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,IAAI,EAAE,cAAc;IACpB,WAAW,EACT,0EAA0E;QAC1E,uEAAuE;QACvE,uEAAuE;QACvE,0EAA0E;QAC1E,mEAAmE;QACnE,uEAAuE;QACvE,qEAAqE;QACrE,0EAA0E;QAC1E,uEAAuE;QACvE,4EAA4E;QAC5E,wEAAwE;QACxE,2DAA2D;QAC3D,yEAAyE;QACzE,yEAAyE;QACzE,qBAAqB;IACvB,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;YACD,QAAQ,EAAE;gBACR,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,gEAAgE;oBAChE,gEAAgE;oBAChE,oEAAoE;oBACpE,iEAAiE;oBACjE,qBAAqB;aACxB;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,IAAI,GAA4B,EAAE,CAAC;IACzC,IAAI,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC;QAC5C,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;IACxC,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAmB,IAAI,EAAE,IAAI,CAAC,CAAC;IACzD,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;QACL,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,UAAU,EAAE,GAAG,CAAC,UAAU,IAAI,KAAK,CAAC,UAAU;KAC/C,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fetchsandbox-mcp",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "mcpName": "io.github.fetchsandbox/mcp",
   "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",