Tamperbox MCP

A code-mode Model Context Protocol server for the Tamperbox API. Discover operation schemas, then write JavaScript to chain calls and return only the results you need.

Two MCP tools. Eight API operations. stdio and Streamable HTTP. Node.js 22+.

This repository implements the MCP adapter and sandbox. Transforms run on the Tamperbox API. It does not require an OpenAI or Anthropic key to start.

Try the tools before automating

Start at tamperbox.dev to explore the tools interactively. Trying a small example makes it easier to understand the accepted input, the output format, and why a tool returns a warning or rejects a value before asking an AI client to automate it.

The Pipeline editor supports all five transforms available through this MCP server:

1. Click Load synthetic example to load a sample JWT and a JWT → YAML workflow.

2. Click Run next step to inspect the decoded JSON, then run the next step to see the YAML. Run locally runs the whole workflow.

3. Change the input, add a step, or adjust an option and compare the output and warnings. Use the same sample with MCP to understand how the browser workflow maps to code.

The Pipeline editor runs locally in your browser without uploading its input. This MCP server sends operation inputs to the Tamperbox API. The website also contains tools and interactive features beyond this server's eight operations; use tamperbox_discover for the exact schemas supported by your installed MCP version.

Related MCP server: WebMCP Script

Available operations

Call these functions as await tamperbox.<name>(args) inside tamperbox_execute. The five transforms take an input artifact containing a mediaType and a text value, plus operation-specific options. Their result contains an output artifact, warnings, and provenance.

Understand inputs and results

An artifact is { "mediaType": "…", "value": "…" }. Its value is always text, including serialized JSON. This lets one operation's output become another operation's input without guessing the format. Use JSON.stringify(data) to send a JavaScript object as JSON text, or JSON.parse(response.output.value) when you need to work with a JSON result as an object.

For example, run this code through tamperbox_execute:

const formatted = await tamperbox.json_format({
  input: { mediaType: 'application/json', value: '{"example":true}' },
  options: { indent: 2 },
});
return formatted.output;

Expected MCP result:

{
  "result": {
    "mediaType": "application/json",
    "value": "{\n  \"example\": true\n}"
  },
  "apiCalls": 1
}

The operation response and the MCP result are two different layers. formatted also contains warnings and provenance; this example returns only its output. Return the whole response to retain those fields. Warnings explain limitations such as unverified JWTs or lossy conversions. Provenance identifies the provider, engine version, operation, attribution, and editorUrl for exploring the tool in your browser. An editor link does not automatically load your input or result.

The outer result is whatever your code returns. apiCalls counts bridge calls attempted, including host-validation failures; guest serialization failures are excluded. It is not a count of upstream HTTP requests. Successful MCP responses provide the same object as structured content and JSON text for client compatibility.

Run from source

npm ci
npm run build
node dist/cli.js

The default stdio transport writes only MCP messages to stdout. Connect your client using node /absolute/path/to/tamperbox-mcp/dist/cli.js. The repository is prepared for npm distribution; the package must be published before using npx -y tamperbox-mcp@0.1.0.

For a one-shot shell call, pipe JavaScript into the example client:

printf 'return 6 * 7;\n' | node examples/stdio-execute.mjs
# {"result":42,"apiCalls":0}

The client waits for the response before disconnecting. Piping raw MCP requests directly into the server closes its stdin at EOF and cancels active work. See shell usage.

For a local HTTP endpoint:

node dist/cli.js --transport http --port 3000

Connect to http://127.0.0.1:3000/mcp. /health returns readiness of the process, not upstream API availability. Public hosting requires HTTPS termination and explicit host configuration; see deployment.

Code mode

Your AI client sees two MCP tools:

First call tamperbox_discover with {"query":"json"} or {"names":["jwt_decode","json_to_yaml"]}. Use the returned examples and schemas to build arguments; the website is useful for exploring behavior, while discovery defines the callable contract.

Then call tamperbox_execute with code containing an async function body:

const decoded = await tamperbox.jwt_decode({
  input: {
    mediaType: 'application/jwt',
    value: 'eyJhbGciOiJub25lIn0.eyJzdWIiOiJleGFtcGxlIn0.',
  },
});
const yaml = await tamperbox.json_to_yaml({ input: decoded.output });
return {
  output: yaml.output,
  warnings: decoded.warnings,
  provenance: yaml.provenance,
};

The result is { "result": <your returned JSON>, "apiCalls": 2 }. apiCalls counts bridge calls attempted, including host-validation failures, against the per-execution call budget. It does not count upstream HTTP requests: validation can reject a bridge call before any request is sent. Arguments rejected during guest serialization never reach the bridge and are not counted. The field name is retained for compatibility.

Decoding a JWT does not verify its signature, validity or trust. API conversion does not execute requests and may lose unsupported features.

Use await, loops, conditionals, array methods and Promise.all. Batches queue automatically with at most four API calls in flight; all queued calls count toward the 20-call budget. There is no fetch, filesystem, process, package import, timer API or host environment inside the guest. console, TextEncoder, TextDecoder, atob, btoa and Intl are also unavailable. Use return to produce a result. An omitted return becomes null; cyclic, BigInt, function, symbol and non-finite results are rejected. JSON objects follow JSON serialization semantics (for example, undefined object fields are omitted). Await every API call; outstanding calls are cancelled when execution ends.

Guest failures return bounded details.name, details.message (up to 1,024 characters), and a one-based details.line when a source location is available. Locations account for JavaScript line terminators, including CR and Unicode separators. Incomplete code detected at the wrapper's closing line points to the last submitted line. These diagnostics are returned only to the caller and can contain values from the submitted code. Uncaught API failures identify the operation in details.operation (up to 64 characters), including when no guest source line is available. API failures remain redacted; guest catch blocks can inspect error.operation, error.code, error.status when available, and error.details.validation for input errors. The VM provides no host stack traces or raw upstream error bodies.

Operation arguments must serialize to JSON. Functions, symbols and objects whose toJSON() returns undefined produce a guest TypeError before dispatch and do not consume the API call budget. Omitting arguments or passing undefined still defaults to {}. Normal JSON serialization rules apply to nested properties.

The 64 MiB cap covers the guest VM’s WebAssembly linear memory, not total process RSS. Node heaps, native runtime overhead and transport buffers need additional memory. Successful MCP responses repeat the result as text and structured content for compatibility, so the 2 MiB result limit is not a limit on total HTTP/MCP message size.

Connect an AI client

Integration instructions cover ChatGPT custom MCP plugins, Codex, OpenAI Responses API, Claude Code, Claude Desktop, Anthropic Messages API, VS Code and other MCP clients. Ready-to-edit examples are in examples.

Local stdio works from this checkout. Remote integrations need a deployed, reachable HTTPS URL for this server. The existing mcp.tamperbox.dev service is a separate implementation; this repository does not claim it is deployed there. Marketplace and registry publication require account ownership and provider review; see release guide.

Data and execution limits

Code executes in a fresh QuickJS WebAssembly VM within a worker thread. Only allowlisted API calls cross the sandbox boundary. Inputs to those calls leave the machine and are sent to https://api.tamperbox.dev by default; code itself is not sent to that API. If you host this server remotely, the hosting server receives the code and all embedded inputs. The MCP client/model provider also sees tool requests and returned results. This server does not persist or log code, inputs or outputs; hosting/proxy and provider logging policies are separate.

See security for boundaries and architecture for implementation details. Use browser-local Tamperbox tools for sensitive material you cannot send to a remote API.

Develop and verify

npm ci
npm run check
npm run test:live  # opt-in: calls all eight public API operations with synthetic data

Tests cover contracts, real stdio and HTTP MCP clients, API errors, sandbox escapes, cancellation, resource limits and packaging. Coverage gates apply to in-process host modules; the CLI and VM worker are verified through separate processes and are not included in that percentage. The default suite is offline except for loopback HTTP; it never needs model-provider credentials. See testing and the verification record.

MIT licensed. Contributions should include a failing regression test before the fix; see CONTRIBUTING.md.