babelpad-mcp 1.0.0

package/README.md

@@ -0,0 +1,114 @@
+# Babelpad MCP Server
+
+The Model Context Protocol (MCP) server for [babelpad.dev](https://babelpad.dev) enables AI assistants (such as Cursor, Windsurf, or Claude Desktop) to interact directly with the Babelpad execution engine. 
+
+With this server, your AI assistant can:
+1. **Generate coding exercises/fixes** and output a direct, clickable markdown link (e.g., `[Open in Babelpad](url)`) that opens the Babelpad editor pre-populated with code and multiple files.
+2. **Execute code** on your behalf in the Babelpad container sandbox using your API Key and return the output (`stdout`, `stderr`, execution time, and exit status).
+3. **Inspect supported environments** and file extensions.
+
+---
+
+## Installation & Setup
+
+You can run the MCP server directly using `node` or via `npx` (if built/published).
+
+### Prerequisite
+Ensure you install the dependencies inside the `mcp-server` directory:
+```bash
+cd mcp-server
+npm install
+```
+
+---
+
+## Client Integration Configurations
+
+Depending on where your editor/client runs, configure the server in your client's settings.
+
+### 1. Cursor / Windsurf (Windows Native Node)
+If you have Node.js installed on your Windows machine, add a new MCP server in your editor settings (e.g. **Settings -> Features -> MCP** in Cursor):
+
+* **Name**: `Babelpad`
+* **Type**: `command`
+* **Command**:
+  ```bash
+  node C:/path/to/babelpad/mcp-server/index.js
+  ```
+* **Environment Variables**:
+  * `BABELPAD_API_KEY`: `bpk_your_actual_api_key_here` (Get this from your [Babelpad Profile Developer settings](https://babelpad.dev/profile))
+
+---
+
+### 2. Cursor / Windsurf (Running inside WSL)
+If your editor connects to a WSL workspace, or you want to run the Node.js server inside the Ubuntu WSL environment, configure the command as:
+
+* **Name**: `Babelpad`
+* **Type**: `command`
+* **Command**:
+  ```bash
+  wsl sh -c "export BABELPAD_API_KEY=bpk_your_actual_api_key_here && node /home/parrot/babelpad/mcp-server/index.js"
+  ```
+
+---
+
+### 3. Claude Desktop (Windows)
+To register the server globally in your Claude Desktop client, edit your configuration file:
+* Path: `%APPDATA%\Claude\claude_desktop_config.json`
+
+Add the following config:
+
+```json
+{
+  "mcpServers": {
+    "babelpad": {
+      "command": "node",
+      "args": ["C:/path/to/babelpad/mcp-server/index.js"],
+      "env": {
+        "BABELPAD_API_KEY": "bpk_your_actual_api_key_here"
+      }
+    }
+  }
+}
+```
+
+If you prefer to run it inside WSL from your Windows Claude Desktop client:
+
+```json
+{
+  "mcpServers": {
+    "babelpad": {
+      "command": "wsl",
+      "args": [
+        "sh",
+        "-c",
+        "export BABELPAD_API_KEY=bpk_your_actual_api_key_here && node /home/parrot/babelpad/mcp-server/index.js"
+      ]
+    }
+  }
+}
+```
+
+---
+
+## Exposed Tools
+
+### 1. `create_editor_url`
+Generates a stateless, compressed `babelpad.dev/editor` URL preloaded with code/files.
+* **Arguments**:
+  - `language` (string, required): `python`, `javascript`, `rust`, `c`, or `go`.
+  - `code` (string, optional): Single-file program content.
+  - `files` (array, optional): List of `{ name, content }` objects for multi-file configurations.
+  - `interpreter` (boolean, optional): If `true`, opens in Esoteric Custom Interpreter mode.
+  - `title` (string, optional): A custom title for the script tab.
+
+### 2. `execute_code`
+Runs code immediately in the Babelpad container sandbox.
+* **Arguments**:
+  - `language` (string, required): Runtime language.
+  - `files` (array, required): Program file(s) to compile and run.
+  - `stdin` (string, optional): Program inputs.
+* **Requirement**: Requires `BABELPAD_API_KEY` configured in the server's environment.
+
+### 3. `get_supported_languages`
+Lists all supported languages, runtimes, versions, and entry file specifications.

package/index.js

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import LZString from "lz-string";
+
+// ── Constants & Helpers ──────────────────────────────────────────────────────
+const extMap = {
+  python: ".py",
+  javascript: ".js",
+  rust: ".rs",
+  c: ".c",
+  go: ".go"
+};
+
+function getFilenameForLanguage(lang) {
+  return "main" + (extMap[lang.toLowerCase()] || ".txt");
+}
+
+const SUPPORTED_LANGUAGES = [
+  { id: "python", name: "Python 3", extension: ".py" },
+  { id: "javascript", name: "JavaScript (Node.js)", extension: ".js" },
+  { id: "rust", name: "Rust", extension: ".rs" },
+  { id: "c", name: "C (GCC)", extension: ".c" },
+  { id: "go", name: "Go", extension: ".go" }
+];
+
+// Initialize Server
+const server = new Server(
+  {
+    name: "babelpad-mcp",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// Register Tool List Handler
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "create_editor_url",
+        description: "Generates a stateless, shareable Babelpad.dev URL pre-populated with code and files. The LLM can use this to present a clickable link (e.g. [Open Code in Babelpad](url)) to the user for exercises, templates, or fixes.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            language: {
+              type: "string",
+              description: "The programming language identifier (e.g. 'python', 'javascript', 'rust', 'c', 'go').",
+              enum: ["python", "javascript", "rust", "c", "go"]
+            },
+            code: {
+              type: "string",
+              description: "The code content for single-file scripts."
+            },
+            files: {
+              type: "array",
+              description: "An array of files for multi-file scripts. Each file must be an object with 'name' and 'content'.",
+              items: {
+                type: "object",
+                properties: {
+                  name: { type: "string", description: "The filename (e.g. 'helper.py')." },
+                  content: { type: "string", description: "The file code content." }
+                },
+                required: ["name", "content"]
+              }
+            },
+            interpreter: {
+              type: "boolean",
+              description: "Set to true to launch the editor in Esoteric Interpreter Mode."
+            },
+            title: {
+              type: "string",
+              description: "Optional custom title for the script when opened in the editor."
+            }
+          },
+          required: ["language"]
+        }
+      },
+      {
+        name: "execute_code",
+        description: "Runs code immediately in the secure Babelpad sandbox using the user's API Key and returns stdout, stderr, and exit status. Use this to verify that generated code works or run programs.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            language: {
+              type: "string",
+              description: "The programming language identifier.",
+              enum: ["python", "javascript", "rust", "c", "go"]
+            },
+            files: {
+              type: "array",
+              description: "An array of file objects to execute. There must be at least one file, and the entry point must match the standard entry point for the language (e.g., 'main.py' for Python).",
+              items: {
+                type: "object",
+                properties: {
+                  name: { type: "string" },
+                  content: { type: "string" }
+                },
+                required: ["name", "content"]
+              }
+            },
+            stdin: {
+              type: "string",
+              description: "Optional standard input to feed to the running program."
+            }
+          },
+          required: ["language", "files"]
+        }
+      },
+      {
+        name: "get_supported_languages",
+        description: "Lists all programming languages and runtimes currently supported by Babelpad.",
+        inputSchema: {
+          type: "object",
+          properties: {}
+        }
+      }
+    ]
+  };
+});
+
+// Register Tool Execution Handler
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    if (name === "create_editor_url") {
+      const { language, code, files, interpreter = false, title } = args;
+      const langLower = language.toLowerCase();
+      let compressedPayload = "";
+
+      if (files && Array.isArray(files) && files.length > 0) {
+        // Optimization: single file default naming
+        const defaultName = getFilenameForLanguage(langLower);
+        if (files.length === 1 && files[0].name.trim() === defaultName) {
+          compressedPayload = LZString.compressToEncodedURIComponent(files[0].content);
+        } else {
+          const compact = files.map(f => ({
+            n: f.name.trim(),
+            c: f.content
+          }));
+          compressedPayload = LZString.compressToEncodedURIComponent(JSON.stringify(compact));
+        }
+      } else if (typeof code === "string") {
+        compressedPayload = LZString.compressToEncodedURIComponent(code);
+      } else {
+        throw new Error("Either 'code' (string) or 'files' (array) must be provided.");
+      }
+
+      const urlObj = new URL(`https://babelpad.dev/editor/${encodeURIComponent(langLower)}`);
+      urlObj.searchParams.set("code", compressedPayload);
+      if (interpreter) urlObj.searchParams.set("interpreter", "true");
+      if (title && title.trim() !== "") urlObj.searchParams.set("title", title.trim());
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              success: true,
+              url: urlObj.toString(),
+              message: `URL generated successfully. You can display it in markdown as [Open Code in Babelpad](${urlObj.toString()})`
+            }, null, 2)
+          }
+        ]
+      };
+
+    } else if (name === "execute_code") {
+      const { language, files, stdin = "" } = args;
+      const apiKey = process.env.BABELPAD_API_KEY;
+
+      if (!apiKey) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: "Error: The BABELPAD_API_KEY environment variable is not set. The user must provide their API Key (generated in https://babelpad.dev/profile) to execute code."
+            }
+          ]
+        };
+      }
+
+      const response = await fetch("https://babelpad.dev/api/v1/run", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-API-Key": apiKey.trim()
+        },
+        body: JSON.stringify({
+          language,
+          files,
+          stdin
+        })
+      });
+
+      const data = await response.json();
+
+      if (!response.ok) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `API request failed with status ${response.status}: ${data.error || JSON.stringify(data)}`
+            }
+          ]
+        };
+      }
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(data, null, 2)
+          }
+        ]
+      };
+
+    } else if (name === "get_supported_languages") {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ languages: SUPPORTED_LANGUAGES }, null, 2)
+          }
+        ]
+      };
+    } else {
+      throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (error) {
+    return {
+      isError: true,
+      content: [
+        {
+          type: "text",
+          text: error instanceof Error ? error.message : String(error)
+        }
+      ]
+    };
+  }
+});
+
+// Run stdio transport
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("Babelpad MCP Server running on stdio");

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "babelpad-mcp",
+  "version": "1.0.0",
+  "description": "Model Context Protocol (MCP) server for babelpad.dev",
+  "main": "index.js",
+  "type": "module",
+  "bin": {
+    "babelpad-mcp": "./index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "lz-string": "^1.5.0"
+  }
+}