@robinbraemer/codemode

codemode

Two MCP tools that replace hundreds. Give an AI agent your OpenAPI spec and a request handler — it discovers and calls your entire API by writing JavaScript in a sandboxed runtime.

Instead of defining individual MCP tools for every API endpoint (list-pods, create-product, get-logs, ...), CodeMode exposes just two tools:

• search — the agent writes JS to filter your OpenAPI spec and discover endpoints
• execute — the agent writes JS to call your API via an injected client

This is the same pattern Cloudflare uses to expose 2,500+ API endpoints through just two MCP tools, reducing context window usage by 99.9%.

Try It

Requires mise for tooling (Node.js, pnpm, Task):

git clone https://github.com/akua-dev/codemode.git
cd codemode
mise install   # installs Node 24, pnpm 10, Task
task install   # installs dependencies
task example   # runs the Petstore demo

Fetches the real Petstore OpenAPI spec from the web, then runs search + execute against a local Hono mock — no API keys needed.

Install

pnpm add @robinbraemer/codemode

# Install a sandbox runtime (at least one):
pnpm add @robinbraemer/llrt    # Native LLRT — default candidate
pnpm add isolated-vm           # V8 isolates — data-only Node.js fallback

If both are installed, the auto-selector (createExecutor) picks native LLRT first, then isolated-vm on Node for data-only execution. Request-capable execution requires LLRT. QuickJSExecutor is still exported for explicit advanced use, but it is not selected automatically because its host-callback bridge cannot enforce all byte limits before values cross into host JavaScript.

Quick Start

import { CodeMode } from '@robinbraemer/codemode';
import { Hono } from 'hono';

const app = new Hono();
app.get('/v1/clusters', (c) => c.json([{ id: '1', name: 'prod' }]));
app.post('/v1/clusters', async (c) => {
  const body = await c.req.json();
  return c.json({ id: '2', ...body }, 201);
});

const codemode = new CodeMode({
  spec: myOpenAPISpec,              // OpenAPI 3.x spec, or async getter
  request: app.request.bind(app),   // in-process, no network hop
});

// The agent searches the spec to discover endpoints...
const search = await codemode.callTool('search', {
  code: `async () => {
    const results = [];
    for (const [path, methods] of Object.entries(spec.paths)) {
      for (const [method, op] of Object.entries(methods)) {
        if (op.tags?.some(t => t.toLowerCase() === 'clusters')) {
          results.push({ method: method.toUpperCase(), path, summary: op.summary });
        }
      }
    }
    return results;
  }`
});

// ...then executes API calls
const result = await codemode.callTool('execute', {
  code: `async () => {
    const res = await api.request({ method: "GET", path: "/v1/clusters" });
    return res.body;
  }`
});

MCP Server Integration

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { CodeMode } from '@robinbraemer/codemode';
import { registerTools } from '@robinbraemer/codemode/mcp';

const codemode = new CodeMode({
  spec: () => fetchOpenAPISpec(),
  request: app.request.bind(app),
});

const server = new McpServer({ name: 'my-api', version: '1.0.0' });
registerTools(codemode, server);

const transport = new StdioServerTransport();
await server.connect(transport);

How It Works

AI Agent
  │ writes JavaScript code
  ▼
CodeMode MCP Server
  │
  ├─ search(code) → runs JS with preprocessed OpenAPI spec
  │   → ref-resolved paths view with only essential fields kept
  │   → agent discovers endpoints, schemas, parameters
  │
  └─ execute(code) → runs JS with injected request client
      → api.request() calls your handler in-process
      → no network hop, auth handled automatically

All code runs in a fresh sandbox runtime. The sandbox has zero I/O by default — no require, no process, no fetch, no filesystem. Request-capable execution uses injected host callbacks (spec for search, {namespace}.request() for execute) and is supported by LLRT.

Each tool call gets a fresh sandbox with no state carried over between calls.

API

new CodeMode(options)

Successful spec preprocessing is cached. Concurrent searches share an in-flight async spec provider, while a failed preparation is retried by a later search.

Data-only input first has a 100,000-node structural inspection limit. Built-in executors additionally reject cycles, bigint, and custom toJSON hooks, then preflight the fully expanded transport shape before marshalling it into a sandbox. Shared aliases count once per transport occurrence, with limits of 500,000 expanded occurrences and 10 MiB of encoded input. Custom executors still receive the alias-preserving structured clone and remain responsible for their own transport limits.

SandboxOptions

Methods

codemode.tools(): ToolDefinition[]

Returns MCP-compatible tool definitions for search and execute.

codemode.callTool(name, { code }): Promise<ToolCallResult>

Route a tool call. Returns { content: [{ type: "text", text }], isError? }.

codemode.search(code): Promise<ToolCallResult>

Run search code directly (shorthand for callTool('search', { code })).

codemode.execute(code): Promise<ToolCallResult>

Run execute code directly (shorthand for callTool('execute', { code })).

codemode.setToolNames(search, execute): this

Override default tool names. Useful when running multiple CodeMode instances.

codemode.dispose(): void

Clean up sandbox resources.

Sandbox API

Inside search

The spec global is the preprocessed OpenAPI paths view; resolvable $ref pointers are expanded inline:

// Find endpoints by tag
async () => {
  const results = [];
  for (const [path, methods] of Object.entries(spec.paths)) {
    for (const [method, op] of Object.entries(methods)) {
      if (op.tags?.some(t => t.toLowerCase() === 'clusters')) {
        results.push({ method: method.toUpperCase(), path, summary: op.summary });
      }
    }
  }
  return results;
}

// Get endpoint with requestBody schema (resolvable refs are expanded)
async () => {
  const op = spec.paths['/v1/products']?.post;
  return { summary: op?.summary, requestBody: op?.requestBody };
}

// Spec shape
async () => ({
  endpoints: Object.keys(spec.paths).length,
})

Inside execute

The {namespace}.request() function makes API calls through the host handler:

// GET with query params
async () => {
  const res = await api.request({
    method: "GET",
    path: "/v1/clusters",
    query: { limit: 10 },
  });
  return res.body;
}

// POST with body
async () => {
  const res = await api.request({
    method: "POST",
    path: "/v1/products",
    body: { name: "Redis", chart: "bitnami/redis" },
  });
  return { status: res.status, body: res.body };
}

// Chain calls
async () => {
  const list = await api.request({ method: "GET", path: "/v1/clusters" });
  const details = await Promise.all(
    list.body.map(c =>
      api.request({ method: "GET", path: `/v1/clusters/${c.id}` })
    )
  );
  return details.map(d => d.body);
}

Request options:

Response: { status: number, headers: Record<string, string>, body: unknown }

Spec Preprocessing

CodeMode automatically preprocesses your OpenAPI spec before passing it to the search sandbox:

• $ref resolution — resolvable $ref pointers are expanded inline; circular refs become { $circular: ref }, and refs beyond maxRefDepth become { $circular: ref, $reason: "max depth exceeded" }
• Field extraction — only essential fields kept per operation: summary, description, tags, parameters, requestBody, responses
• Output shape — only { paths } is passed to search; info, servers, and components are omitted because operation fields and resolved references are represented in the paths view

You can also use the preprocessing utilities directly:

import { resolveRefs, processSpec, extractTags } from '@robinbraemer/codemode';

const processed = processSpec(rawSpec);
const tags = extractTags(rawSpec);

Executors

CodeMode ships three executor backends. LlrtNativeExecutor is the default and the only request-capable backend. IsolatedVMExecutor is the Node.js data-only fallback, and QuickJSExecutor is an explicit data-only compatibility backend.

Use createExecutor() for automatic selection, or pass an executor instance explicitly:

import { CodeMode, createExecutor, IsolatedVMExecutor, LlrtNativeExecutor } from '@robinbraemer/codemode';

// Automatic — picks native LLRT first, then data-only isolated-vm on Node
const codemode = new CodeMode({
  spec,
  request: handler,
  executor: await createExecutor({ memoryMB: 128, timeoutMs: 60_000 }),
});

// Or explicit
const codemode = new CodeMode({
  spec,
  request: handler,
  executor: new IsolatedVMExecutor({
    memoryMB: 128,
    timeoutMs: 60_000,   // CPU time limit
    wallTimeMs: 120_000, // total elapsed time limit
  }),
});

QuickJSExecutor caveats

• Not a production backend and not auto-selected. Use this only by constructing new QuickJSExecutor(...) explicitly. Production request-capable callers should use LlrtNativeExecutor.
• Host callbacks are disabled. QuickJS cannot enforce host-call byte limits before guest values are dumped into host JavaScript, and sequential host awaits still hit upstream release-asyncify crashes. QuickJSExecutor now fails closed when function globals are provided.
• Return-value semantics differ from isolated-vm. Final values cross via a JSON.stringify envelope. Date, Map, Set, BigInt are converted to strings/objects, not preserved as instances. isolated-vm uses structured clone and preserves them. Stick to plain JSON-safe shapes in sandboxed code that targets both backends.
• CPU timeout is wall-clock-based. isolated-vm uses true CPU time; QuickJS uses elapsed time.

Custom Executor

Implement the Executor interface to use your own sandbox:

CodeMode passes a fresh structured clone of the processed spec to each search() call, so mutations made by a custom executor cannot change later searches.

CodeMode calls executeData() for search() and executeWithCapabilities() for execute(). Implement the latter when the custom runtime needs to expose the request capability; the legacy execute() method remains available for direct executor use.

import {
  CodeMode,
  emptyExecuteStats,
  type CapabilityManifest,
  type ExecuteResult,
  type Executor,
} from '@robinbraemer/codemode';

class MyExecutor implements Executor {
  async executeData(_code: string, _input: Record<string, unknown>): Promise<ExecuteResult> {
    // Run data-only code in the sandbox.
    return { result: undefined, stats: emptyExecuteStats() };
  }

  async executeWithCapabilities(
    _code: string,
    _input: Record<string, unknown>,
    _capabilities: CapabilityManifest,
  ): Promise<ExecuteResult> {
    // Run code with declared capabilities, such as `{namespace}.request()`.
    return { result: undefined, stats: emptyExecuteStats() };
  }

  async execute(_code: string, _globals: Record<string, unknown>): Promise<ExecuteResult> {
    // Legacy direct-executor entrypoint.
    return { result: undefined, stats: emptyExecuteStats() };
  }

  dispose() { /* clean up */ }
}

const codemode = new CodeMode({
  spec,
  request: handler,
  executor: new MyExecutor(),
});

Token Efficiency

License

MIT