diff --git a/packages/plugin-code-execution/README.md b/packages/plugin-code-execution/README.md index 2ce4a74..2201843 100644 --- a/packages/plugin-code-execution/README.md +++ b/packages/plugin-code-execution/README.md @@ -1,4 +1,7 @@ -# @mcpc/agentic-js-sandbox +# @mcpc/plugin-code-execution + +[![JSR](https://jsr.io/badges/@mcpc/plugin-code-execution)](https://jsr.io/@mcpc/plugin-code-execution) +[![npm](https://img.shields.io/npm/v/@mcpc-tech/plugin-code-execution)](https://www.npmjs.com/package/@mcpc-tech/plugin-code-execution) Secure JavaScript code execution sandbox using Deno for MCPC agents. This package provides a safe environment to execute user-provided JavaScript code @@ -10,19 +13,18 @@ with MCP tool access via JSON-RPC IPC. execution - 🔌 **JSON-RPC IPC**: Tool calls are transmitted via JSON-RPC between sandbox and host -- 🚀 **Easy Integration**: Drop-in replacement for the built-in code execution - mode +- 🚀 **Easy Integration**: Plugin-based integration with MCPC - 📦 **Zero Config**: Automatically locates Deno binary from npm package - 🛡️ **Resource Limits**: Configurable timeouts and memory limits ## Installation ```bash -npm install @mcpc/agentic-js-sandbox +npm install @mcpc/plugin-code-execution # or -pnpm add @mcpc/agentic-js-sandbox +pnpm add @mcpc/plugin-code-execution # or -yarn add @mcpc/agentic-js-sandbox +yarn add @mcpc/plugin-code-execution ``` ## Usage @@ -31,7 +33,7 @@ yarn add @mcpc/agentic-js-sandbox ```typescript import { mcpc } from "@mcpc/core"; -import { createSandboxExecutor } from "@mcpc/agentic-js-sandbox"; +import { createCodeExecutionPlugin } from "@mcpc/plugin-code-execution/plugin"; const server = await mcpc( [{ name: "my-agent", version: "1.0.0" }, { @@ -53,13 +55,17 @@ const server = await mcpc( }, }, }, - options: { - mode: "code_execution", - // Use custom sandbox executor - customExecutor: createSandboxExecutor({ - timeout: 30000, // 30 seconds - memoryLimit: 512, // 512 MB + plugins: [ + createCodeExecutionPlugin({ + sandbox: { + timeout: 30000, // 30 seconds + memoryLimit: 512, // 512 MB + permissions: [], // No extra permissions + }, }), + ], + options: { + mode: "custom", }, }], ); @@ -83,16 +89,20 @@ passing Deno permission flags directly: ```typescript // No permissions - can only call MCP tools -createSandboxExecutor(); +createCodeExecutionPlugin(); // Allow network access to specific domains -createSandboxExecutor({ - permissions: ["--allow-net=github.com,api.example.com"], +createCodeExecutionPlugin({ + sandbox: { + permissions: ["--allow-net=github.com,api.example.com"], + }, }); // Allow reading specific directories -createSandboxExecutor({ - permissions: ["--allow-read=/tmp,/var/log"], +createCodeExecutionPlugin({ + sandbox: { + permissions: ["--allow-read=/tmp,/var/log"], + }, }); ``` @@ -109,13 +119,15 @@ interface SandboxConfig { Example with custom permissions: ```typescript -createSandboxExecutor({ - timeout: 60000, - permissions: [ - "--allow-net=api.example.com", - "--allow-read=/tmp", - "--allow-env=HOME,USER", - ], +createCodeExecutionPlugin({ + sandbox: { + timeout: 60000, + permissions: [ + "--allow-net=api.example.com", + "--allow-read=/tmp", + "--allow-env=HOME,USER", + ], + }, }); ``` @@ -140,7 +152,7 @@ createSandboxExecutor({ ## Comparison with Built-in Executor -| Feature | Built-in (`new Function`) | Sandbox (`npm:deno`) | +| Feature | Built-in (`new Function`) | Plugin Sandbox (`deno`) | | ----------- | ------------------------- | --------------------------- | | Security | Low (same process) | High (isolated) | | Performance | Fast | Slower (IPC overhead) | @@ -151,9 +163,7 @@ createSandboxExecutor({ See `examples/` directory for complete examples: -- `basic-usage.ts` - Simple code execution -- `file-operations.ts` - Working with filesystem MCP tools -- `custom-permissions.ts` - Custom Deno permissions +- `basic-usage.ts` - Simple code execution with plugin integration ## Development