@justanothermldude/mcp-exec 0.1.0

package/README.md

@@ -0,0 +1,344 @@
+# @meta-mcp/exec
+
+MCP execution utilities for sandboxed TypeScript/JavaScript code execution with OS-level isolation.
+
+## Installation
+
+```bash
+npm install @meta-mcp/exec
+```
+
+## Overview
+
+This package provides secure code execution capabilities with:
+
+- **Sandbox Isolation**: OS-level sandboxing via `@anthropic-ai/sandbox-runtime` (sandbox-exec on macOS, bubblewrap on Linux)
+- **MCP Bridge**: HTTP bridge allowing sandboxed code to call MCP tools
+- **Wrapper Generation**: Auto-generate type-safe TypeScript wrappers for MCP tools
+
+## Quick Start
+
+### Basic Code Execution
+
+```typescript
+import { executeCode } from '@meta-mcp/exec';
+
+const result = await executeCode({
+  code: 'console.log("Hello from sandbox!")',
+  timeout_ms: 5000,
+});
+
+console.log(result.output);  // ['Hello from sandbox!']
+console.log(result.durationMs);  // execution time in ms
+```
+
+### Using as MCP Server
+
+```bash
+# Start the mcp-exec server
+npx @meta-mcp/exec
+
+# Or with specific config
+SERVERS_CONFIG=~/.meta-mcp/servers.json npx @meta-mcp/exec
+```
+
+## API Reference
+
+### executeCode
+
+Execute code in a sandboxed environment.
+
+```typescript
+import { executeCode } from '@meta-mcp/exec';
+
+const result = await executeCode({
+  code: string;       // TypeScript/JavaScript code to execute
+  timeout_ms?: number; // Max execution time (default: 30000)
+});
+
+// Result type
+interface ExecutionResult {
+  output: string[];    // stdout lines
+  error?: string;      // stderr content
+  durationMs: number;  // execution time
+}
+```
+
+### SandboxExecutor
+
+Create a custom executor with specific configuration:
+
+```typescript
+import { SandboxExecutor, createExecutor } from '@meta-mcp/exec';
+
+// Using factory function
+const executor = createExecutor({
+  mcpBridgePort: 4000,
+  additionalWritePaths: ['/tmp/my-app'],
+  enableLogMonitor: true,
+});
+
+// Using class directly
+const executor = new SandboxExecutor({
+  mcpBridgePort: 4000,
+  additionalWritePaths: ['/tmp/my-app'],
+});
+
+// Execute code
+const result = await executor.execute('console.log(1 + 1)', 5000);
+
+// Check status
+executor.checkDependencies();   // true if sandbox-runtime available
+executor.isSandboxingEnabled(); // true if OS sandboxing active
+
+// Update config
+executor.updateConfig({ mcpBridgePort: 5000 });
+
+// Clean up
+await executor.reset();
+```
+
+### MCPBridge
+
+HTTP bridge for MCP tool access from sandboxed code:
+
+```typescript
+import { MCPBridge } from '@meta-mcp/exec';
+import { ServerPool, createConnection, getServerConfig } from '@meta-mcp/core';
+
+// Create server pool
+const connectionFactory = async (serverId: string) => {
+  const config = getServerConfig(serverId);
+  if (!config) throw new Error(`Server not found: ${serverId}`);
+  return createConnection(config);
+};
+const pool = new ServerPool(connectionFactory);
+
+// Create and start bridge
+const bridge = new MCPBridge(pool, {
+  port: 3000,
+  host: '127.0.0.1',
+});
+
+await bridge.start();
+
+// Bridge endpoints:
+// GET  /health - Health check
+// POST /call   - Execute MCP tool call
+
+// Check status
+bridge.isRunning();  // true
+bridge.getPort();    // 3000
+bridge.getHost();    // '127.0.0.1'
+
+// Stop bridge
+await bridge.stop();
+```
+
+### Wrapper Generator
+
+Generate type-safe TypeScript wrappers for MCP tools:
+
+```typescript
+import { generateToolWrapper, generateServerModule } from '@meta-mcp/exec';
+import type { ToolDefinition } from '@meta-mcp/core';
+
+// Generate wrapper for single tool
+const tool: ToolDefinition = {
+  name: 'read_file',
+  description: 'Read contents of a file',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      path: { type: 'string', description: 'File path to read' },
+    },
+    required: ['path'],
+  },
+};
+
+const wrapper = generateToolWrapper(tool, 'filesystem');
+// Generates TypeScript function that calls bridge endpoint
+
+// Generate module for all server tools
+const tools: ToolDefinition[] = [/* ... */];
+const module = generateServerModule(tools, 'filesystem');
+// Generates complete TypeScript module with all tool wrappers
+```
+
+**Generated wrapper example:**
+
+```typescript
+export interface ReadFileInput {
+  /** File path to read */
+  path: string;
+}
+
+/**
+ * Read contents of a file
+ * @param input.path - File path to read
+ * @returns Promise resolving to tool result
+ */
+export async function read_file(input: ReadFileInput): Promise<unknown> {
+  const response = await fetch('http://localhost:3000/call', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      server_name: 'filesystem',
+      tool_name: 'read_file',
+      arguments: input,
+    }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Tool call failed: ${response.statusText}`);
+  }
+
+  return response.json();
+}
+```
+
+### MCP Server
+
+Create the mcp-exec MCP server programmatically:
+
+```typescript
+import { createMcpExecServer } from '@meta-mcp/exec';
+import { ServerPool, createConnection, getServerConfig } from '@meta-mcp/core';
+
+// Create pool
+const connectionFactory = async (serverId: string) => {
+  const config = getServerConfig(serverId);
+  if (!config) throw new Error(`Server not found: ${serverId}`);
+  return createConnection(config);
+};
+const pool = new ServerPool(connectionFactory);
+
+// Create server
+const { server, listToolsHandler, callToolHandler, shutdown } = createMcpExecServer(pool);
+
+// List available tools
+const tools = await listToolsHandler();
+// => { tools: [{ name: 'execute_code', inputSchema: {...} }] }
+
+// Call execute_code tool
+const result = await callToolHandler({
+  name: 'execute_code',
+  arguments: {
+    code: 'console.log("Hello!")',
+    timeout_ms: 5000,
+  },
+});
+
+// Graceful shutdown
+await shutdown();
+```
+
+## Types
+
+```typescript
+import type {
+  ExecuteCodeInput,
+  ExecutionResult,
+  SandboxExecutorConfig,
+  MCPBridgeConfig,
+  CallRequest,
+  CallResponse,
+} from '@meta-mcp/exec';
+
+interface ExecuteCodeInput {
+  code: string;
+  timeout_ms?: number;
+}
+
+interface ExecutionResult {
+  output: string[];
+  error?: string;
+  durationMs: number;
+}
+
+interface SandboxExecutorConfig {
+  mcpBridgePort?: number;
+  additionalWritePaths?: string[];
+  enableLogMonitor?: boolean;
+}
+
+interface MCPBridgeConfig {
+  port?: number;
+  host?: string;
+}
+
+interface CallRequest {
+  server: string;
+  tool: string;
+  args?: Record<string, unknown>;
+}
+
+interface CallResponse {
+  success: boolean;
+  content?: unknown[];
+  isError?: boolean;
+  error?: string;
+}
+```
+
+## CLI Usage
+
+```bash
+# Start the MCP server
+mcp-exec
+
+# Show version
+mcp-exec --version
+
+# Show help
+mcp-exec --help
+```
+
+## Using Wrappers in Sandboxed Code
+
+When code runs in the sandbox, it can call MCP tools via the HTTP bridge:
+
+```typescript
+// Code running inside sandbox
+const result = await fetch('http://localhost:3000/call', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    server: 'filesystem',
+    tool: 'read_file',
+    args: { path: '/tmp/test.txt' },
+  }),
+});
+
+const data = await result.json();
+console.log(data.content[0].text);
+```
+
+Or use generated wrappers:
+
+```typescript
+// Import generated wrappers
+import { read_file, write_file } from './filesystem-wrappers';
+
+// Type-safe tool calls
+const content = await read_file({ path: '/tmp/test.txt' });
+await write_file({ path: '/tmp/output.txt', content: 'Hello!' });
+```
+
+## Security
+
+- **Network Isolation**: Sandbox only allows connections to the local bridge (e.g., `localhost:3000`)
+- **Filesystem Isolation**: Write access restricted to configured paths
+- **Timeout Enforcement**: Code execution automatically terminated after timeout
+- **OS-Level Sandboxing**: Uses `sandbox-exec` (macOS) or `bubblewrap` (Linux)
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SERVERS_CONFIG` | `~/.meta-mcp/servers.json` | Path to servers configuration |
+| `MCP_DEFAULT_TIMEOUT` | none | Global timeout for MCP tool calls (ms) |
+
+## License
+
+MIT

package/dist/bridge/index.d.ts

@@ -0,0 +1,3 @@
+export { MCPBridge } from './server.js';
+export type { CallRequest, CallResponse, MCPBridgeConfig } from './server.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/bridge/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bridge/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}

package/dist/bridge/index.js

@@ -0,0 +1,3 @@
+// MCP Bridge HTTP server exports
+export { MCPBridge } from './server.js';
+//# sourceMappingURL=index.js.map

package/dist/bridge/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/bridge/index.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/dist/bridge/server.d.ts

@@ -0,0 +1,84 @@
+import type { ServerPool } from '@justanothermldude/meta-mcp-core';
+/**
+ * Request body for the /call endpoint
+ */
+export interface CallRequest {
+    /** Name of the MCP server to call */
+    server: string;
+    /** Name of the tool to invoke */
+    tool: string;
+    /** Arguments to pass to the tool */
+    args?: Record<string, unknown>;
+}
+/**
+ * Response from the /call endpoint
+ */
+export interface CallResponse {
+    /** Whether the call was successful */
+    success: boolean;
+    /** Tool result content (when success is true) */
+    content?: unknown[];
+    /** Error message (when success is false) */
+    error?: string;
+    /** Whether the result indicates an error from the tool */
+    isError?: boolean;
+}
+/**
+ * Configuration options for MCPBridge
+ */
+export interface MCPBridgeConfig {
+    /** Port to listen on (default: 3000) */
+    port?: number;
+    /** Host to bind to (default: '127.0.0.1') */
+    host?: string;
+}
+/**
+ * MCP Bridge HTTP server that allows sandboxed code to call
+ * MCP tools via HTTP requests to localhost.
+ */
+export declare class MCPBridge {
+    private readonly pool;
+    private readonly port;
+    private readonly host;
+    private server;
+    constructor(pool: ServerPool, config?: MCPBridgeConfig);
+    /**
+     * Start the HTTP bridge server
+     * @returns Promise that resolves when server is listening
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the HTTP bridge server
+     * @returns Promise that resolves when server is closed
+     */
+    stop(): Promise<void>;
+    /**
+     * Get the port the server is listening on
+     */
+    getPort(): number;
+    /**
+     * Get the host the server is bound to
+     */
+    getHost(): string;
+    /**
+     * Check if the server is running
+     */
+    isRunning(): boolean;
+    /**
+     * Handle incoming HTTP requests
+     */
+    private handleRequest;
+    /**
+     * Handle POST /call endpoint for tool invocation
+     */
+    private handleCallRequest;
+    /**
+     * Handle GET /health endpoint
+     */
+    private handleHealthRequest;
+    /**
+     * Send an error response
+     */
+    private sendError;
+}
+//# sourceMappingURL=server.d.ts.map

package/dist/bridge/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/bridge/server.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAiB,MAAM,kCAAkC,CAAC;AAGlF;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,iDAAiD;IACjD,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC;IACpB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,wCAAwC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAwKD;;;GAGG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,MAAM,CAAuB;gBAEzB,IAAI,EAAE,UAAU,EAAE,MAAM,GAAE,eAAoB;IAM1D;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB5B;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB3B;;OAEG;IACH,OAAO,IAAI,MAAM;IAIjB;;OAEG;IACH,OAAO,IAAI,MAAM;IAIjB;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,OAAO,CAAC,aAAa;IAwBrB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IA+GzB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAS3B;;OAEG;IACH,OAAO,CAAC,SAAS;CAQlB"}