@execbox/core

Provider, schema, and MCP adapter contracts for execbox. Use it to resolve host tools into callable guest namespaces before running code with an executor such as @execbox/quickjs.

Use @execbox/core When

• you want to expose host capabilities to guest code through explicit tool providers
• you want one execution contract across inline and worker-hosted QuickJS
• you want to wrap MCP servers or clients into callable namespaces

Pair It With an Executor

@execbox/core defines the provider and tool boundary. Guest execution happens in an executor package.

| Package | Start here when | | -------------------------------------------------------------------- | --------------------------------------------------------------- | | @execbox/quickjs | You want the default path with inline or worker-hosted QuickJS. |

Install

Most users start with QuickJS:

npm install @execbox/core @execbox/quickjs

Provider Boundary

Providers are explicit capability grants. resolveProvider() validates the namespace, normalizes tool schemas, creates guest-safe tool names, wraps tool execution with schema checks, and keeps original-to-safe name maps for callers that need to explain MCP or generated tool names.

Tool inputs and results should be JSON-compatible data. Keep host-only values such as clients, handles, secrets, and tenant routing inside the tool implementation.

Runtime Implementer Surface

Most application code can skip this section.

Application code should usually import from @execbox/core or @execbox/core/mcp. The @execbox/core/protocol and @execbox/core/runtime subpaths exist for execbox-owned runtime packages. @execbox/core/protocol carries the worker-hosted QuickJS message contract, while @execbox/core/runtime contains the manifest dispatcher, runtime option defaults, timeout helpers, log formatting, code normalization, and error normalization used to keep runtime implementations aligned.

Smallest Working Usage

import { resolveProvider } from "@execbox/core";
import { QuickJsExecutor } from "@execbox/quickjs";

const provider = resolveProvider({
  name: "tools",
  tools: {
    greet: {
      inputSchema: {
        type: "object",
        required: ["name"],
        properties: {
          name: { type: "string" },
        },
      },
      execute: async (input) => ({
        message: `Hello, ${(input as { name: string }).name}!`,
      }),
    },
  },
});

const executor = new QuickJsExecutor();
const result = await executor.execute(`await tools.greet({ name: "World" })`, [
  provider,
]);

console.log(result);

MCP Support

Use @execbox/core/mcp when you want MCP on either side of the provider boundary:

• wrap an upstream MCP server or client into a provider with createMcpToolProvider() or openMcpToolProvider()
• expose execbox code execution back out through an MCP server with codeMcpServer()
• preserve raw MCP CallToolResult envelopes so guest code can inspect structuredContent first and fall back to content

Operational Notes

• Providers are the capability boundary. If guest code can call a tool, it can exercise that authority.
• Execbox gives you JSON-only tool/result boundaries, schema validation, bounded logs, and timeout-aware execution controls.
• Hard isolation depends on the executor and deployment boundary you choose, not on @execbox/core by itself.

Read Next

• Getting Started
• Providers & Tools
• Runtime Choices
• MCP Integration
• Examples
• Security & Boundaries
• Architecture Overview