@mcploom/codexec

Executor-agnostic core for guest JavaScript that can call host tools directly or wrap MCP servers and clients into callable namespaces.

What You Get

• Resolve host tools into deterministic guest namespaces with name sanitization.
• Validate tool inputs and outputs with JSON Schema, full Zod schemas, or MCP SDK-style raw Zod shapes.
• Normalize user code before execution and generate namespace typings from resolved schemas.
• Wrap MCP servers or clients into codexec providers, or expose code-execution tools from an MCP server.

Pair It With an Executor

@mcploom/codexec does not execute code on its own. Pair it with one of the executor packages:

| Package | Best for | | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | @mcploom/codexec-quickjs | Easiest setup, no native addon, good default backend | | @mcploom/codexec-remote | Same executor API, but with a caller-supplied remote boundary | | @mcploom/codexec-process | QuickJS execution in a child process with a stronger lifecycle split | | @mcploom/codexec-worker | QuickJS execution on a worker thread with a message boundary | | @mcploom/codexec-isolated-vm | Native isolated-vm backend when you specifically want that runtime |

Examples

• Basic provider execution
• Process-backed provider execution
• Remote provider execution
• Worker-backed provider execution
• Wrap MCP tools into a provider
• Expose MCP code-execution tools from a server
• Run the same flow on isolated-vm
• Full examples index

Install

npm install @mcploom/codexec @mcploom/codexec-quickjs

Swap in @mcploom/codexec-isolated-vm when you want the native executor instead. Swap in @mcploom/codexec-process when you want the QuickJS runtime to live in a fresh child process. Swap in @mcploom/codexec-remote when you want the same API but a caller-managed remote transport boundary.

Security Posture

• Codexec gives you fresh execution state, JSON-only tool boundaries, schema validation, timeout handling, memory limits, and bounded logs.
• Codexec does not give you a hard security boundary for hostile code by itself. The actual boundary depends on which executor you pair it with.
• Providers are explicit capability grants. Every tool you expose is authority you are handing to guest code.
• In the default deployment model, provider and MCP tool definitions are controlled by the application, not by the end user.
• Third-party MCP integrations should be reviewed as dependency-trust decisions, not folded into the primary end-user attacker model.
• If the code source is hostile, prefer stronger isolation such as @mcploom/codexec-process, @mcploom/codexec-remote, a container, or a VM.

Architecture Docs

• Codexec architecture overview
• Codexec core architecture
• Codexec executors
• Codexec MCP adapters and protocol

Exports

• @mcploom/codexec
  • ExecutionOptions
  • resolveProvider
  • normalizeCode
  • sanitizeToolName
  • extractProviderManifests
  • createToolCallDispatcher
  • JSON Schema type generation and executor/result types
• @mcploom/codexec/mcp
  • createMcpToolProvider
  • openMcpToolProvider
  • getMcpToolSourceServerInfo
  • codeMcpServer

Basic Usage

import { resolveProvider } from "@mcploom/codexec";
import { QuickJsExecutor } from "@mcploom/codexec-quickjs";
import * as z from "zod";

const provider = resolveProvider({
  name: "tools",
  tools: {
    add: {
      inputSchema: z.object({
        x: z.number(),
        y: z.number(),
      }),
      execute: async (input) => {
        const { x, y } = input as { x: number; y: number };
        return { sum: x + y };
      },
    },
  },
});

const executor = new QuickJsExecutor();
const result = await executor.execute(
  "await tools.add({ x: 2, y: 5 })",
  [provider],
  { timeoutMs: 250 },
);

MCP Adapters

Use @mcploom/codexec/mcp when you want to wrap an MCP server or client into a tool provider, or expose code-execution tools from an MCP server. Wrapped tools preserve raw MCP CallToolResult envelopes so guest code can inspect structuredContent first and fall back to content.