parallelsandbox-mcp 0.1.0

package/README.md

@@ -0,0 +1,43 @@
+# parallelsandbox-mcp
+
+stdio adapter for the ParallelSandbox MCP server. It exposes the same tools as `https://mcp.parallelsandbox.com/mcp`
+(`sandbox_*`, `logs_*`), forwarding every call with your API key, and implements `sandbox_sync` locally so an agent
+can upload its working directory into a box without committing.
+
+## Use
+
+```bash
+PARALLELSANDBOX_API_KEY=psk_... npx parallelsandbox-mcp
+```
+
+Claude Code:
+
+```bash
+claude mcp add parallelsandbox -e PARALLELSANDBOX_API_KEY=psk_... -- npx -y parallelsandbox-mcp
+```
+
+Any other MCP client: run the command above as a stdio server.
+
+If you never need `sandbox_sync`, you can skip this package and connect directly:
+
+```bash
+claude mcp add --transport http parallelsandbox https://mcp.parallelsandbox.com/mcp --header "Authorization: Bearer psk_..."
+```
+
+## Environment
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `PARALLELSANDBOX_API_KEY` | required | API key from the app |
+| `PARALLELSANDBOX_MCP_URL` | `https://mcp.parallelsandbox.com/mcp` | MCP endpoint (dev: `https://mcp.dev.parallelsandbox.com/mcp`) |
+| `PARALLELSANDBOX_API_URL` | `https://api.parallelsandbox.com` | REST base used by `sandbox_sync` |
+
+## sandbox_sync
+
+`{"id": "<box id>", "localPath": ".", "dest": "repo"}` tars `localPath` (relative to the agent's working directory),
+excluding `node_modules`, `.git`, `dist`, `build`, `coverage`, `.venv` and similar, and uploads it to `/work/<dest>` on the box.
+
+## Timeouts
+
+`sandbox_takeover` blocks until a person hands the box back, up to 30 minutes; the adapter waits 31 minutes for it and
+65 minutes for other calls (a foreground `sandbox_exec` runs at most 60 minutes).

package/index.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// parallelsandbox-mcp: stdio in, ParallelSandbox Streamable HTTP out.
+// Every tool call is forwarded to https://mcp.parallelsandbox.com/mcp with the API key, except sandbox_sync,
+// which tars the local directory here and uploads it through POST /v1/boxes/{id}/sync.
+
+import { spawnSync } from "node:child_process";
+import { existsSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+
+const API_KEY = process.env.PARALLELSANDBOX_API_KEY || "";
+const MCP_URL = process.env.PARALLELSANDBOX_MCP_URL || "https://mcp.parallelsandbox.com/mcp";
+const API_URL = (process.env.PARALLELSANDBOX_API_URL || "https://api.parallelsandbox.com").replace(/\/+$/, "");
+const TAKEOVER_TIMEOUT_MS = 31 * 60 * 1000;
+const DEFAULT_TIMEOUT_MS = 65 * 60 * 1000;
+const SYNC_EXCLUDES = ["node_modules", ".git", "dist", "dist-web", "build", ".cache", "coverage", ".venv", "venv", "__pycache__", "target", ".next", ".turbo"];
+
+const log = (...args) => console.error("[parallelsandbox-mcp]", ...args);
+
+if (!API_KEY) {
+  log("PARALLELSANDBOX_API_KEY is required (create a key in the app at https://app.parallelsandbox.com)");
+  process.exit(2);
+}
+
+const remote = new Client({ name: "parallelsandbox-mcp", version: "0.1.0" });
+const transport = new StreamableHTTPClientTransport(new URL(MCP_URL), {
+  requestInit: { headers: { Authorization: `Bearer ${API_KEY}` } },
+});
+
+async function connectRemote() {
+  await remote.connect(transport);
+  log("connected to", MCP_URL);
+}
+
+function textResult(text, isError = false) {
+  return { content: [{ type: "text", text }], isError };
+}
+
+// sandbox_sync runs here: tar the local directory and upload it to the box through control.
+async function sync(args) {
+  const { id, localPath, dest } = args || {};
+  if (!id || !localPath || !dest) {
+    return textResult("sandbox_sync needs id, localPath and dest", true);
+  }
+  const src = resolve(process.cwd(), localPath);
+  if (!existsSync(src) || !statSync(src).isDirectory()) {
+    return textResult(`local directory not found: ${src}`, true);
+  }
+  const tar = spawnSync("tar", ["-czf", "-", "-C", src, ...SYNC_EXCLUDES.map((e) => `--exclude=${e}`), "."], { maxBuffer: 2 * 1024 * 1024 * 1024 });
+  if (tar.status !== 0) {
+    return textResult(`tar failed: ${tar.stderr?.toString() || tar.status}`, true);
+  }
+  const res = await fetch(`${API_URL}/v1/boxes/${encodeURIComponent(id)}/sync?dest=${encodeURIComponent(dest)}`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/gzip" },
+    body: tar.stdout,
+  });
+  const body = await res.text();
+  if (!res.ok) {
+    let message = body;
+    try {
+      message = JSON.parse(body).error || body;
+    } catch {}
+    return textResult(`sync failed (HTTP ${res.status}): ${message}`, true);
+  }
+  const mb = (tar.stdout.length / 1024 / 1024).toFixed(1);
+  return textResult(JSON.stringify({ ok: true, dest, uploadedMB: Number(mb), excluded: SYNC_EXCLUDES }, null, 2));
+}
+
+const server = new Server({ name: "parallelsandbox", version: "0.1.0" }, { capabilities: { tools: {} } });
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  const { tools } = await remote.listTools();
+  return { tools };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const { name, arguments: args } = req.params;
+  if (name === "sandbox_sync") {
+    return sync(args);
+  }
+  const timeout = name === "sandbox_takeover" ? TAKEOVER_TIMEOUT_MS : DEFAULT_TIMEOUT_MS;
+  return remote.callTool({ name, arguments: args || {} }, undefined, { timeout, resetTimeoutOnProgress: true });
+});
+
+await connectRemote();
+await server.connect(new StdioServerTransport());

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "parallelsandbox-mcp",
+  "version": "0.1.0",
+  "description": "stdio adapter for the ParallelSandbox MCP server: runs locally so sandbox_sync can upload your working directory",
+  "type": "module",
+  "bin": {
+    "parallelsandbox-mcp": "index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/parallel-sandbox/parallelsandbox_control_server",
+    "directory": "packages/parallelsandbox-mcp"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.19.1"
+  }
+}