Node Code Sandbox MCP

Instructions

Implementation Reference

• src/tools/initialize.ts:31-92 (handler)

  The handler function that executes the logic for sandbox_initialize: creates a Docker container with labels, mounts a volume, sets resource limits, registers it, and returns the container ID or error.

  export default async function initializeSandbox({
    image = DEFAULT_NODE_IMAGE,
    port,
  }: {
    image?: string;
    port?: number;
  }): Promise<McpResponse> {
    if (!isDockerRunning()) {
      return {
        content: [textContent(DOCKER_NOT_RUNNING_ERROR)],
      };
    }
  
    const containerId = `js-sbx-${randomUUID()}`;
    const creationTimestamp = Date.now();
  
    const portOption = port ? `-p ${port}:${port}` : `--network host`; // prefer --network host if no explicit port mapping
  
    // Construct labels
    const labels = [
      `mcp-sandbox=true`,
      `mcp-server-run-id=${serverRunId}`,
      `mcp-creation-timestamp=${creationTimestamp}`,
    ];
    const labelArgs = labels.map((label) => `--label "${label}"`).join(' ');
    const { memFlag, cpuFlag } = computeResourceLimits(image);
  
    try {
      execSync(
        `docker run -d ${portOption} ${memFlag} ${cpuFlag} ` +
          `--workdir /workspace -v ${getFilesDir()}:/workspace/files ` +
          `${labelArgs} ` + // Add labels here
          `--name ${containerId} ${image} tail -f /dev/null`
      );
  
      // Register the container only after successful creation
      activeSandboxContainers.set(containerId, creationTimestamp);
      logger.info(`Registered container ${containerId}`);
  
      return {
        content: [textContent(containerId)],
      };
    } catch (error) {
      logger.error(`Failed to initialize container ${containerId}`, error);
      // Ensure partial cleanup if execSync fails after container might be created but before registration
      try {
        execSync(`docker rm -f ${containerId}`);
      } catch (cleanupError: unknown) {
        // Ignore cleanup errors - log it just in case
        logger.warning(
          `Ignoring error during cleanup attempt for ${containerId}: ${String(cleanupError)}`
        );
      }
      return {
        content: [
          textContent(
            `Failed to initialize sandbox container: ${error instanceof Error ? error.message : String(error)}`
          ),
        ],
      };
    }
  }

• src/tools/initialize.ts:23-29 (schema)

  Zod schema defining input arguments for the sandbox_initialize tool: optional image and port.

  export const argSchema = {
    image: z.string().optional(),
    port: z
      .number()
      .optional()
      .describe('If set, maps this container port to the host'),
  };

• src/server.ts:51-56 (registration)

  MCP server tool registration for sandbox_initialize, linking name, description, schema, and handler.

  server.tool(
    'sandbox_initialize',
    'Start a new isolated Docker container running Node.js. Used to set up a sandbox session for multiple commands and scripts.',
    initializeSchema,
    initializeSandbox
  );