@scalebox/mcp 0.0.1

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * Scalebox MCP Server CLI.
+ * Usage: npx -y @scalebox-dev/scalebox-mcp --api-key YOUR_API_KEY [--api-url URL]
+ * Or set env: SCALEBOX_API_KEY, SCALEBOX_API_URL
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * Scalebox MCP Server CLI.
+ * Usage: npx -y @scalebox-dev/scalebox-mcp --api-key YOUR_API_KEY [--api-url URL]
+ * Or set env: SCALEBOX_API_KEY, SCALEBOX_API_URL
+ */
+const args = process.argv.slice(2);
+let apiKey = process.env.SCALEBOX_API_KEY || process.env.SBX_API_KEY;
+let apiUrl = process.env.SCALEBOX_API_URL;
+for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--api-key' && args[i + 1]) {
+        apiKey = args[i + 1];
+        i++;
+    }
+    else if (args[i] === '--api-url' && args[i + 1]) {
+        apiUrl = args[i + 1];
+        i++;
+    }
+}
+if (!apiKey) {
+    console.error('Error: API key is required. Set SCALEBOX_API_KEY or use --api-key YOUR_API_KEY');
+    process.exit(1);
+}
+process.env.SCALEBOX_API_KEY = apiKey;
+if (apiUrl) {
+    process.env.SCALEBOX_API_URL = apiUrl;
+}
+import('./server.js')
+    .then(({ runServer }) => runServer())
+    .catch((err) => {
+    console.error('Fatal error:', err);
+    process.exit(1);
+});
+export {};

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Scalebox MCP Server – programmatic entry.
+ * For npx, use bin scalebox-mcp (cli.js), which parses --api-key.
+ */
+export { runServer } from './server.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+/**
+ * Scalebox MCP Server – programmatic entry.
+ * For npx, use bin scalebox-mcp (cli.js), which parses --api-key.
+ */
+export { runServer } from './server.js';

package/dist/load-guide.d.ts

@@ -0,0 +1,3 @@
+export declare const GUIDE_IDS: readonly ["doc-index", "api", "js-sdk", "python-sdk"];
+export type GuideId = (typeof GUIDE_IDS)[number];
+export declare function loadGuide(id: GuideId): string;

package/dist/load-guide.js

@@ -0,0 +1,15 @@
+/**
+ * Load bundled Markdown guides from `packages/js/guides/` (copied from repo root `guides/` via sync-guides).
+ */
+import { existsSync, readFileSync } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+export const GUIDE_IDS = ['doc-index', 'api', 'js-sdk', 'python-sdk'];
+export function loadGuide(id) {
+    const dir = path.dirname(fileURLToPath(import.meta.url));
+    const file = path.join(dir, '..', 'guides', `${id}.md`);
+    if (!existsSync(file)) {
+        throw new Error(`Guide "${id}" not found at ${file}`);
+    }
+    return readFileSync(file, 'utf8');
+}

package/dist/server.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Scalebox MCP Server (stdio).
+ * Tools: create_sandbox, execute_code, list_files, read_file, write_file,
+ * install_packages, run_command, remove_file, make_dir, destroy_context, get_sandbox_info
+ */
+export declare function runServer(): Promise<void>;

package/dist/server.js

@@ -0,0 +1,331 @@
+/**
+ * Scalebox MCP Server (stdio).
+ * Tools: create_sandbox, execute_code, list_files, read_file, write_file,
+ * install_packages, run_command, remove_file, make_dir, destroy_context, get_sandbox_info
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CodeInterpreter } from '@scalebox/sdk';
+import { z } from 'zod';
+/** Max length per stdout/stderr stream to keep MCP responses from overwhelming clients. */
+const MAX_COMMAND_IO_LENGTH = 262144;
+const sandboxes = new Map();
+const contexts = new Map();
+function getApiKey() {
+    const key = process.env.SCALEBOX_API_KEY || process.env.SBX_API_KEY;
+    if (!key) {
+        throw new Error('API key required. Set SCALEBOX_API_KEY or use --api-key');
+    }
+    return key;
+}
+function getSandbox(contextId) {
+    const sbx = sandboxes.get(contextId);
+    if (!sbx)
+        throw new Error(`Context ${contextId} not found. Call create_sandbox first.`);
+    return sbx;
+}
+function getContext(contextId) {
+    return contexts.get(contextId);
+}
+function jsonContent(obj) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(obj, null, 2) }],
+    };
+}
+function errContent(msg, isError = true) {
+    return { content: [{ type: 'text', text: msg }], isError };
+}
+/** Resolve Sandbox via the public SDK API (files, commands, etc.); do not touch private Interpreter fields. */
+function getSandboxFor(interpreter) {
+    return interpreter.getSandbox();
+}
+/** Truncate long command output and record whether truncation occurred. */
+function clipCommandIo(text) {
+    if (text.length <= MAX_COMMAND_IO_LENGTH) {
+        return { text, truncated: false };
+    }
+    return {
+        text: `${text.slice(0, MAX_COMMAND_IO_LENGTH)}\n... [truncated, max ${MAX_COMMAND_IO_LENGTH} chars per stream]`,
+        truncated: true,
+    };
+}
+const server = new McpServer({ name: 'scalebox-mcp', version: '1.0.0' }, { capabilities: { tools: {} } });
+// Tool definitions with Zod input schemas (required by McpServer.registerTool)
+const TOOLS = [
+    {
+        name: 'create_sandbox',
+        description: 'Create a sandbox and code execution context for stateful runs',
+        inputSchema: z.object({
+            language: z.string().describe('Language: python, nodejs, r, typescript, java, bash'),
+            cwd: z.string().optional().describe('Working directory (default /home/user)'),
+        }),
+    },
+    {
+        name: 'execute_code',
+        description: 'Execute code in the sandbox',
+        inputSchema: z.object({
+            code: z.string().describe('Code to run'),
+            context_id: z.string().describe('Context ID (required)'),
+            language: z.string().optional().describe('Language (default python)'),
+        }),
+    },
+    {
+        name: 'list_files',
+        description: 'List files and directories at path',
+        inputSchema: z.object({
+            path: z.string().describe('Path to list'),
+            context_id: z.string().describe('Context ID (required)'),
+        }),
+    },
+    {
+        name: 'read_file',
+        description: 'Read file content from the sandbox',
+        inputSchema: z.object({
+            file_path: z.string().describe('File path'),
+            context_id: z.string().describe('Context ID (required)'),
+        }),
+    },
+    {
+        name: 'write_file',
+        description: 'Write file content to the sandbox',
+        inputSchema: z.object({
+            file_path: z.string().describe('File path'),
+            content: z.string().describe('File content'),
+            context_id: z.string().describe('Context ID (required)'),
+        }),
+    },
+    {
+        name: 'install_packages',
+        description: 'Install Python packages (pip)',
+        inputSchema: z.object({
+            packages: z.array(z.string()).describe('Package names to install'),
+            context_id: z.string().describe('Context ID (required)'),
+        }),
+    },
+    {
+        name: 'run_command',
+        description: 'Run a shell command in the sandbox',
+        inputSchema: z.object({
+            command: z.string().describe('Command to run'),
+            context_id: z.string().describe('Context ID (required)'),
+        }),
+    },
+    {
+        name: 'remove_file',
+        description: 'Remove file or directory in the sandbox',
+        inputSchema: z.object({
+            path: z.string().describe('Path to remove'),
+            context_id: z.string().describe('Context ID (required)'),
+        }),
+    },
+    {
+        name: 'make_dir',
+        description: 'Create directory in the sandbox',
+        inputSchema: z.object({
+            path: z.string().describe('Directory path to create'),
+            context_id: z.string().describe('Context ID (required)'),
+        }),
+    },
+    {
+        name: 'destroy_context',
+        description: 'Destroy a context and its sandbox',
+        inputSchema: z.object({
+            context_id: z.string().describe('Context ID to destroy'),
+        }),
+    },
+    {
+        name: 'get_sandbox_info',
+        description: 'List all contexts and sandboxes',
+        inputSchema: z.object({}),
+    },
+];
+async function handleTool(name, a) {
+    switch (name) {
+        case 'create_sandbox': {
+            const language = (a.language ? String(a.language) : 'python');
+            const cwd = String(a.cwd ?? '/home/user');
+            const apiKey = getApiKey();
+            const interpreter = await CodeInterpreter.create({
+                apiKey,
+                apiUrl: process.env.SCALEBOX_API_URL,
+            });
+            const context = await interpreter.createCodeContext({ language, cwd });
+            sandboxes.set(context.id, interpreter);
+            contexts.set(context.id, context);
+            return jsonContent({
+                success: true,
+                context_id: context.id,
+                language: context.language,
+                cwd: context.cwd,
+                sandbox_id: getSandboxFor(interpreter).sandboxId,
+            });
+        }
+        case 'execute_code': {
+            const code = String(a.code);
+            const contextId = String(a.context_id);
+            const language = (a.language ? String(a.language) : 'python');
+            const sbx = getSandbox(contextId);
+            const context = getContext(contextId);
+            if (!context)
+                return errContent(`Context ${contextId} not found`);
+            const execution = await sbx.runCode(code, { language, context });
+            const result = {
+                success: true,
+                language,
+                context_id: contextId,
+                stdout: execution.stdout ?? execution.logs?.stdout ?? '',
+                stderr: execution.stderr ?? execution.logs?.stderr ?? '',
+            };
+            if (execution.results?.length) {
+                result.results = execution.results.map((r) => ({
+                    text: r.text,
+                    data: r.data,
+                }));
+            }
+            return jsonContent(result);
+        }
+        case 'list_files': {
+            const path = String(a.path);
+            const contextId = String(a.context_id);
+            const sbx = getSandbox(contextId);
+            const sandbox = getSandboxFor(sbx);
+            const files = await sandbox.files.list(path);
+            const items = files.map((f) => ({
+                name: f.name,
+                type: f.type,
+                size: f.size ?? 0,
+            }));
+            return jsonContent({ success: true, path, total: items.length, items });
+        }
+        case 'read_file': {
+            const filePath = String(a.file_path);
+            const contextId = String(a.context_id);
+            const sbx = getSandbox(contextId);
+            const sandbox = getSandboxFor(sbx);
+            const content = await sandbox.files.read(filePath);
+            return jsonContent({ success: true, path: filePath, content });
+        }
+        case 'write_file': {
+            const filePath = String(a.file_path);
+            const content = String(a.content);
+            const contextId = String(a.context_id);
+            const sbx = getSandbox(contextId);
+            const sandbox = getSandboxFor(sbx);
+            await sandbox.files.write(filePath, content);
+            return jsonContent({ success: true, path: filePath, size: content.length });
+        }
+        case 'install_packages': {
+            const packages = Array.isArray(a.packages) ? a.packages : [];
+            const contextId = String(a.context_id);
+            const sbx = getSandbox(contextId);
+            const sandbox = getSandboxFor(sbx);
+            const cmd = `pip install ${packages.join(' ')} -q`;
+            const result = await sandbox.commands.run(cmd);
+            const stdoutClip = clipCommandIo(result.stdout ?? '');
+            const stderrClip = clipCommandIo(result.stderr ?? '');
+            return jsonContent({
+                success: result.exitCode === 0,
+                exit_code: result.exitCode,
+                packages,
+                stdout: stdoutClip.text,
+                stderr: stderrClip.text,
+                stdout_truncated: stdoutClip.truncated,
+                stderr_truncated: stderrClip.truncated,
+                ...(result.error ? { command_error: String(result.error.message ?? result.error) } : {}),
+            });
+        }
+        case 'run_command': {
+            const command = String(a.command);
+            const contextId = String(a.context_id);
+            const sbx = getSandbox(contextId);
+            const sandbox = getSandboxFor(sbx);
+            const result = await sandbox.commands.run(command);
+            const stdoutClip = clipCommandIo(result.stdout ?? '');
+            const stderrClip = clipCommandIo(result.stderr ?? '');
+            return jsonContent({
+                success: result.exitCode === 0,
+                command,
+                exit_code: result.exitCode,
+                stdout: stdoutClip.text,
+                stderr: stderrClip.text,
+                stdout_truncated: stdoutClip.truncated,
+                stderr_truncated: stderrClip.truncated,
+                ...(result.error ? { command_error: String(result.error.message ?? result.error) } : {}),
+            });
+        }
+        case 'remove_file': {
+            const path = String(a.path);
+            const contextId = String(a.context_id);
+            const sbx = getSandbox(contextId);
+            const sandbox = getSandboxFor(sbx);
+            await sandbox.files.remove(path);
+            return jsonContent({ success: true, message: `Removed: ${path}` });
+        }
+        case 'make_dir': {
+            const path = String(a.path);
+            const contextId = String(a.context_id);
+            const sbx = getSandbox(contextId);
+            const sandbox = getSandboxFor(sbx);
+            await sandbox.files.makeDir(path);
+            return jsonContent({ success: true, message: `Created directory: ${path}` });
+        }
+        case 'destroy_context': {
+            const contextId = String(a.context_id);
+            const context = contexts.get(contextId);
+            if (!context)
+                return errContent(`Context ${contextId} not found`);
+            const sbx = sandboxes.get(contextId);
+            if (sbx) {
+                await sbx.destroyContext(context);
+                sandboxes.delete(contextId);
+            }
+            contexts.delete(contextId);
+            return jsonContent({ success: true, message: `Context destroyed: ${contextId}` });
+        }
+        case 'get_sandbox_info': {
+            const contextList = [];
+            for (const [ctxId, ctx] of contexts) {
+                const sbx = sandboxes.get(ctxId);
+                let sandboxId = 'unknown';
+                if (sbx) {
+                    try {
+                        sandboxId = getSandboxFor(sbx).sandboxId ?? sandboxId;
+                    }
+                    catch {
+                        // ignore
+                    }
+                }
+                contextList.push({
+                    context_id: ctxId,
+                    sandbox_id: sandboxId,
+                    language: ctx.language ?? 'unknown',
+                    cwd: ctx.cwd ?? 'unknown',
+                });
+            }
+            return jsonContent({
+                strategy: 'Context ID is the single key for sandbox/context',
+                total_contexts: contexts.size,
+                total_sandboxes: sandboxes.size,
+                contexts: contextList,
+            });
+        }
+        default:
+            return errContent(`Unknown tool: ${name}`);
+    }
+}
+for (const t of TOOLS) {
+    server.registerTool(t.name, { description: t.description, inputSchema: t.inputSchema }, async (args) => {
+        try {
+            return await handleTool(t.name, args ?? {});
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return errContent(msg, true);
+        }
+    });
+}
+export async function runServer() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('Scalebox MCP Server running on stdio');
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@scalebox/mcp",
+  "version": "0.0.1",
+  "description": "Scalebox MCP Server - run via npx",
+  "homepage": "https://github.com/scalebox-dev/scalebox-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/scalebox-dev/scalebox-mcp/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/scalebox-dev/scalebox-mcp.git"
+  },
+  "license": "ISC",
+  "author": "",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "scalebox-mcp": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@scalebox/sdk": "^3.3.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist"
+  ]
+}