Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 39 additions & 29 deletions packages/plugin-code-execution/README.md
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
Expand All @@ -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" }, {
Expand All @@ -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",
},
}],
);
Expand All @@ -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"],
},
});
```

Expand All @@ -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",
],
},
});
```

Expand All @@ -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) |
Expand All @@ -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

Expand Down