pendulum-mcp-dispatcher 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 IAFEnvoy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,132 @@
+# Pendulum MCP Dispatcher
+
+Pendulum MCP dispatcher layer — a transparent proxy between AI clients and the Minecraft MCP server.
+
+## What is Pendulum MCP?
+
+Pendulum is a Minecraft mod that exposes in-game actions as tools via an MCP (Minecraft Code Protocol) server. It allows AI agents to interact with the Minecraft world by calling these tools.
+
+Currently, Pendulum support both Data Mode and Visual Mode tools. Data Mode provides JavaScript APIs for direct control (like `Playwright.js`), while Visual Mode allows agents to interact with the game through screenshots and simulated input.
+
+For more details, see the [Pendulum GitHub repository](https://github.com/IAFEnvoy/Pendulum), you can also get compiled jars from [CurseForge](https://www.curseforge.com/minecraft/mc-mods/pendulum) and [Modrinth](https://modrinth.com/mod/pendulum). Also you can refer to [Documentation](https://docs.iafenvoy.com/docs/mod/pendulum) for the complete tool list and usage instructions.
+
+## Why a Dispatcher Layer
+
+Pendulum's MCP server runs inside the Minecraft game (TCP port 25566). When the game is not running, AI clients (such as VS Code Copilot, Claude Desktop) cannot discover the tool list, causing **context errors**.
+
+This dispatcher layer solves the problem:
+
+- **Static tool descriptions**: Built-in complete definitions for 22 tools, so AI clients can see all tools even when the game is not running
+- **Health check**: Verifies backend connectivity before every call; returns a clear error message when unreachable
+- **Transparent forwarding**: Once the backend is ready, all requests are forwarded as-is with zero performance loss
+
+## Installation
+
+```bash
+npm install -g pendulum-mcp-dispatcher
+```
+
+Or use `npx` to run it on-the-fly without installing:
+
+```bash
+npx pendulum-mcp-dispatcher
+```
+
+## Usage
+
+```bash
+# Default connection to localhost:25566
+pendulum-mcp-dispatcher
+
+# Or via npx
+npx pendulum-mcp-dispatcher
+
+# Custom backend address
+PENDULUM_HOST=192.168.1.100 PENDULUM_PORT=25566 pendulum-mcp-dispatcher
+```
+
+## Configuring AI Clients
+
+### VS Code Copilot
+
+In `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "pendulum": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "pendulum-mcp-dispatcher"],
+      "env": {
+        "PENDULUM_HOST": "localhost",
+        "PENDULUM_PORT": "25566"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+In `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "pendulum": {
+      "command": "npx",
+      "args": ["-y", "pendulum-mcp-dispatcher"],
+      "env": {
+        "PENDULUM_HOST": "localhost",
+        "PENDULUM_PORT": "25566"
+      }
+    }
+  }
+}
+```
+
+## Workflow
+
+```
+AI Client (Copilot/Claude)
+       │
+       │ stdio (MCP protocol)
+       ▼
+┌──────────────────────────┐
+│  Pendulum Dispatcher      │  ← You are here
+│  - Static tool list       │
+│  - Health check           │
+│  - Request forwarding     │
+└────────┬─────────────────┘
+         │
+         │ TCP (JSON-RPC 2.0)
+         ▼
+┌──────────────────────────┐
+│  Minecraft + Pendulum     │
+│  (localhost:25566)        │
+└──────────────────────────┘
+```
+
+## Error Handling
+
+When Minecraft is not running, the AI client will receive:
+
+```
+Pendulum MCP server is not reachable (127.0.0.1:25566).
+
+Reason: Connection timed out — Minecraft may not be running
+
+Please ensure:
+1. Minecraft is running
+2. The Pendulum mod is installed
+3. MCP server is started: /pendulum mcp start
+
+Then retry your request.
+```
+
+## Notes
+
+- **No automatic game launch**: You need to manually start Minecraft and run `/pendulum mcp start`, you can also make it run on game launch by configuring.
+- **Independent connection per request**: Uses short-lived connections to avoid state issues with persistent TCP connections
+- **120s timeout**: The `script/eval` timeout matches the backend

package/index.js

@@ -0,0 +1,279 @@
+#!/usr/bin/env node
+
+/**
+ * Pendulum MCP Dispatcher
+ * 
+ * A transparent forwarding layer between AI clients and the Pendulum MCP TCP server.
+ * 
+ * Key features:
+ * - Exposes an MCP stdio server to AI clients (VS Code Copilot, Claude Desktop, etc.)
+ * - Forwards all requests to the Pendulum MCP TCP server (localhost:25566 by default)
+ * - Health-checks the backend; returns meaningful errors when Minecraft is not running
+ * - Provides static tool definitions so AI clients always see the full tool list
+ * - Does NOT auto-start Minecraft — the user must start the game + MCP server manually
+ */
+
+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 net from "net";
+import { TOOL_DEFINITIONS } from "./tools.js";
+
+// ═══════════════════════════════════════════════
+// Configuration
+// ═══════════════════════════════════════════════
+
+const BACKEND_HOST = process.env.PENDULUM_HOST || "127.0.0.1";
+const BACKEND_PORT = parseInt(process.env.PENDULUM_PORT || "25566", 10);
+const HEALTH_TIMEOUT_MS = 3000;   // How long to wait for backend health check
+const REQUEST_TIMEOUT_MS = 130000; // 120s eval timeout + 10s buffer
+
+// ═══════════════════════════════════════════════
+// Backend health check
+// ═══════════════════════════════════════════════
+
+/**
+ * Test if the Pendulum MCP TCP server is reachable.
+ * We send a minimal JSON-RPC request (tools/list) to verify full connectivity.
+ */
+function checkBackendHealth() {
+  return new Promise((resolve) => {
+    const socket = new net.Socket();
+    let buffer = "";
+    let resolved = false;
+
+    const finish = (ok, reason) => {
+      if (resolved) return;
+      resolved = true;
+      socket.destroy();
+      resolve({ ok, reason });
+    };
+
+    socket.setTimeout(HEALTH_TIMEOUT_MS);
+    socket.connect(BACKEND_PORT, BACKEND_HOST, () => {
+      // Send a minimal tools/list request to verify the full JSON-RPC pipeline
+      const req = JSON.stringify({
+        jsonrpc: "2.0",
+        id: "health",
+        method: "tools/list",
+        params: {},
+      });
+      socket.write(req + "\n");
+    });
+
+    socket.on("data", (data) => {
+      buffer += data.toString("utf-8");
+      try {
+        JSON.parse(buffer.trim());
+        finish(true, null);
+      } catch (_) {
+        // Partial response, wait for more data
+      }
+    });
+
+    socket.on("timeout", () => finish(false, "Connection timed out — Minecraft may not be running"));
+    socket.on("error", (err) => finish(false, err.message));
+    socket.on("close", () => finish(false, "Connection closed by backend"));
+  });
+}
+
+/**
+ * Execute a raw JSON-RPC call against the Pendulum MCP TCP server.
+ * Opens a fresh connection for each request (simple, thread-safe).
+ */
+function callBackend(method, params) {
+  return new Promise((resolve, reject) => {
+    const socket = new net.Socket();
+    let buffer = "";
+    let resolved = false;
+
+    const id = "disp-" + Date.now() + "-" + Math.floor(Math.random() * 10000);
+    const request = JSON.stringify({
+      jsonrpc: "2.0",
+      id,
+      method,
+      params: params || {},
+    });
+
+    socket.setTimeout(REQUEST_TIMEOUT_MS);
+
+    socket.connect(BACKEND_PORT, BACKEND_HOST, () => {
+      socket.write(request + "\n");
+    });
+
+    socket.on("data", (data) => {
+      buffer += data.toString("utf-8");
+      try {
+        // Pendulum MCP TCP sends one JSON object per line
+        const lines = buffer.split("\n");
+        for (const line of lines) {
+          if (!line.trim()) continue;
+          const msg = JSON.parse(line);
+          if (msg.id === id || msg.method === "notifications/message") {
+            if (msg.result !== undefined) {
+              resolved = true;
+              socket.destroy();
+              resolve(msg.result);
+              return;
+            }
+            if (msg.error) {
+              resolved = true;
+              socket.destroy();
+              reject(new Error(msg.error.message || JSON.stringify(msg.error)));
+              return;
+            }
+          }
+        }
+      } catch (_) {
+        // Partial JSON, keep buffering
+      }
+    });
+
+    socket.on("error", (err) => {
+      if (resolved) return;
+      resolved = true;
+      reject(err);
+    });
+
+    socket.on("timeout", () => {
+      if (resolved) return;
+      resolved = true;
+      socket.destroy();
+      reject(new Error("Request timed out (120s+) — the script may be too long. Use script/evalAsync for long scripts."));
+    });
+
+    socket.on("close", () => {
+      if (resolved) return;
+      resolved = true;
+      reject(new Error("Backend closed the connection unexpectedly — may have crashed"));
+    });
+  });
+}
+
+// ═══════════════════════════════════════════════
+// MCP Server (stdio transport → AI client)
+// ═══════════════════════════════════════════════
+
+async function main() {
+  const server = new Server(
+    {
+      name: "pendulum-dispatcher",
+      version: "1.0.0",
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    }
+  );
+
+  // ── tools/list: always return static definitions ──
+  // This ensures the AI client always sees the full tool list even when
+  // Minecraft is not running, preventing context errors.
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    let health = "unknown";
+    try {
+      const result = await checkBackendHealth();
+      health = result.ok ? "connected" : result.reason;
+    } catch (_) {
+      health = "check failed";
+    }
+
+    // Append health status to the first tool's description as a hint
+    const tools = TOOL_DEFINITIONS.map((t, i) => {
+      if (i === 0 && health !== "connected") {
+        return {
+          ...t,
+          description: `[Backend: ${health}] ${t.description}`,
+        };
+      }
+      return t;
+    });
+
+    return { tools };
+  });
+
+  // ── tools/call: forward to backend ──
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const toolName = request.params.name;
+    const args = request.params.arguments || {};
+
+    // 1) Health check
+    const health = await checkBackendHealth();
+    if (!health.ok) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Pendulum MCP server is not reachable (${BACKEND_HOST}:${BACKEND_PORT}).\n\n` +
+              `Reason: ${health.reason}\n\n` +
+              `Please ensure:\n` +
+              `1. Minecraft is running\n` +
+              `2. The Pendulum mod is installed\n` +
+              `3. MCP server is started: /pendulum mcp start\n\n` +
+              `Then retry your request.`,
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    // 2) Forward the request to the real Pendulum MCP server
+    try {
+      const result = await callBackend("tools/call", {
+        name: toolName,
+        arguments: args,
+      });
+
+      // Unwrap the result — Pendulum returns { content: [...] }
+      if (result && result.content) {
+        return { content: result.content };
+      }
+
+      // Some responses may be a plain string
+      if (typeof result === "string") {
+        return {
+          content: [{ type: "text", text: result }],
+        };
+      }
+
+      return {
+        content: [{ type: "text", text: JSON.stringify(result) }],
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Pendulum MCP error: ${err.message}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  });
+
+  // ── Start the server ──
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  console.error("[pendulum-dispatcher] Listening on stdio");
+  console.error(`[pendulum-dispatcher] Backend: ${BACKEND_HOST}:${BACKEND_PORT}`);
+
+  // Initial health check
+  const health = await checkBackendHealth();
+  if (health.ok) {
+    console.error("[pendulum-dispatcher] ✓ Backend is reachable");
+  } else {
+    console.error(`[pendulum-dispatcher] ⚠ Backend not reachable: ${health.reason}`);
+    console.error("[pendulum-dispatcher]   Start Minecraft + /pendulum mcp start, then retry");
+  }
+}
+
+main().catch((err) => {
+  console.error("[pendulum-dispatcher] Fatal error:", err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "pendulum-mcp-dispatcher",
+  "version": "1.0.0",
+  "description": "MCP forwarding layer for Pendulum — proxies requests to Minecraft MCP server",
+  "type": "module",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "tools.js"
+  ],
+  "scripts": {
+    "start": "node index.js"
+  },
+  "keywords": [
+    "mcp",
+    "pendulum",
+    "minecraft",
+    "model-context-protocol",
+    "dispatcher",
+    "proxy"
+  ],
+  "author": "IAFEnvoy",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IAFEnvoy/pendulum-mcp-dispatcher.git"
+  },
+  "bugs": {
+    "url": "https://github.com/IAFEnvoy/pendulum-mcp-dispatcher/issues"
+  },
+  "homepage": "https://github.com/IAFEnvoy/pendulum-mcp-dispatcher#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  }
+}

package/tools.js

@@ -0,0 +1,275 @@
+/**
+ * Pendulum MCP Tool Definitions
+ * 
+ * Copied from the Pendulum mod's MCP server to ensure AI clients always
+ * see the full tool list even when the backend is unavailable.
+ * 
+ * Structure: { name, description, inputSchema: { type, properties, required } }
+ */
+
+export const TOOL_DEFINITIONS = [
+  // ═══════════════════════════════════════════
+  // Script Engine (script/*)
+  // ═══════════════════════════════════════════
+  {
+    name: "script/eval",
+    description: "Execute JavaScript code in Minecraft. Key globals: mc/minecraft/game. API: mc.player.* (movement, rotation, interaction, state), mc.world.* (blocks, entities, environment), mc.inv.* (inventory, container), mc.gui.* (screen click, type, enumerate widgets). All functions are synchronous. BARITONE: if installed, prefer br.* (br.goto, br.mine, br.follow, br.stop, br.isActive, br.command).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        code: { type: "string", description: "JS code. E.g.: mc.player.forward(20); for(let b of mc.world.findBlocks('diamond_ore',16)) mc.player.breakBlockAt(b.x,b.y,b.z); JSON.stringify(mc.inv.getAllItems()); mc.world.rayTrace(5). If baritone: br.goto(100,64,200); br.mine('diamond_ore',64);" }
+      },
+      required: ["code"]
+    }
+  },
+  {
+    name: "script/evalAsync",
+    description: "Execute JavaScript asynchronously — returns immediately. Use 'script/status' to check completion. For scripts longer than 120s.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        code: { type: "string", description: "JS code to execute asynchronously." }
+      },
+      required: ["code"]
+    }
+  },
+  {
+    name: "script/status",
+    description: "Check if a script is currently running.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        _: { type: "string", description: "No parameters required" }
+      }
+    }
+  },
+  {
+    name: "script/abort",
+    description: "Abort the currently running script.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        _: { type: "string", description: "No parameters required" }
+      }
+    }
+  },
+
+  // ═══════════════════════════════════════════
+  // Pendulum Core
+  // ═══════════════════════════════════════════
+  {
+    name: "health",
+    description: "Health check: reports screenshot capability, keyboard injection, Baritone availability, and script state.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        _: { type: "string", description: "No parameters required" }
+      }
+    }
+  },
+
+  // ═══════════════════════════════════════════
+  // GUI (gui/*)
+  // ═══════════════════════════════════════════
+  {
+    name: "gui/screenshot",
+    description: "Capture a screenshot with coordinate grid overlay. Returns base64 PNG. Use optional 'path' to also save to disk.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "File path to save. Omit for base64 return only." }
+      }
+    }
+  },
+  {
+    name: "gui/enumerateWidgets",
+    description: "Recursively enumerate ALL GUI widgets including nested children. Returns [{type, text?, x, y, width, height, active?, focused?, children?}, ...].",
+    inputSchema: {
+      type: "object",
+      properties: {
+        _: { type: "string", description: "No parameters required" }
+      }
+    }
+  },
+  {
+    name: "gui/guiElements",
+    description: "Get flat list of non-slot GUI elements (buttons, labels). Returns [{type, x, y, width, height, text?}].",
+    inputSchema: {
+      type: "object",
+      properties: {
+        _: { type: "string", description: "No parameters required" }
+      }
+    }
+  },
+  {
+    name: "gui/clickButton",
+    description: "Find a button/widget by text substring or type name and click its center. Searches recursively. Returns widget info.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: { type: "string", description: "Text to match (substring, case-insensitive) or widget type name." }
+      },
+      required: ["target"]
+    }
+  },
+
+  // ═══════════════════════════════════════════
+  // Simulate Input (simulate/*)
+  // ═══════════════════════════════════════════
+  {
+    name: "simulate/click",
+    description: "Click at screen coordinates. Use after 'gui/screenshot' to target UI elements. Screenshot includes a coordinate grid.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        x: { type: "integer", description: "X coordinate in screen pixels." },
+        y: { type: "integer", description: "Y coordinate in screen pixels." },
+        button: { type: "string", description: "Mouse button: 'left' (default), 'right', or 'middle'." }
+      },
+      required: ["x", "y"]
+    }
+  },
+  {
+    name: "simulate/pressKey",
+    description: "Press a keyboard key. Supports: W, Enter, ESC, SPACE, F3, A, etc. Can hold for N seconds.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        key: { type: "string", description: "Key name, e.g. 'W', 'Enter', 'ESC', 'SPACE', 'F3'." },
+        holdSeconds: { type: "number", description: "Duration to hold in seconds. Default 0 (press and release)." }
+      },
+      required: ["key"]
+    }
+  },
+  {
+    name: "simulate/typeText",
+    description: "Type text into the focused text field character by character.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        text: { type: "string", description: "Text to type." },
+        pressEnter: { type: "boolean", description: "Press Enter after typing. Default false." }
+      },
+      required: ["text"]
+    }
+  },
+  {
+    name: "simulate/pasteText",
+    description: "Type text quickly (same as typeText, for large blocks).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        text: { type: "string", description: "Text to paste." },
+        pressEnter: { type: "boolean", description: "Press Enter after. Default false." }
+      },
+      required: ["text"]
+    }
+  },
+  {
+    name: "simulate/scroll",
+    description: "Scroll mouse wheel. Positive = up, negative = down.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        clicks: { type: "integer", description: "Number of scroll clicks." }
+      },
+      required: ["clicks"]
+    }
+  },
+  {
+    name: "simulate/hotkey",
+    description: "Press a key combination. E.g. 'ctrl,s' or 'shift,f3'.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        keys: { type: "string", description: "Comma-separated key names." }
+      },
+      required: ["keys"]
+    }
+  },
+  {
+    name: "simulate/mouseDrag",
+    description: "Drag mouse from one point to another.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        xStart: { type: "integer", description: "Start X." },
+        yStart: { type: "integer", description: "Start Y." },
+        xEnd: { type: "integer", description: "End X." },
+        yEnd: { type: "integer", description: "End Y." },
+        button: { type: "string", description: "Mouse button: 'left' (default), 'right', or 'middle'." }
+      },
+      required: ["xStart", "yStart", "xEnd", "yEnd"]
+    }
+  },
+  {
+    name: "simulate/callScreenMethod",
+    description: "DANGEROUS — Call an arbitrary no-arg method on the current GUI screen via reflection. All exceptions caught.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        method: { type: "string", description: "Method name to call on the screen object." }
+      },
+      required: ["method"]
+    }
+  },
+  {
+    name: "simulate/selectListItem",
+    description: "Select an item from a dropdown/list widget by text substring (case-insensitive).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        text: { type: "string", description: "Text substring to match." }
+      },
+      required: ["text"]
+    }
+  },
+
+  // ═══════════════════════════════════════════
+  // Utility
+  // ═══════════════════════════════════════════
+  {
+    name: "wait",
+    description: "Wait for N seconds. Useful for sequencing actions.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        seconds: { type: "number", description: "Seconds to wait. Default 1.0." }
+      }
+    }
+  },
+
+  // ═══════════════════════════════════════════
+  // Video (video/*)
+  // ═══════════════════════════════════════════
+  {
+    name: "video/start",
+    description: "EXPERIMENTAL — Start ~10fps video capture. Reads GPU every 6 frames — expensive. Prefer 'gui/screenshot' for single shots.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        _: { type: "string", description: "No parameters required" }
+      }
+    }
+  },
+  {
+    name: "video/stop",
+    description: "Stop video frame capture.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        _: { type: "string", description: "No parameters required" }
+      }
+    }
+  },
+  {
+    name: "video/frame",
+    description: "Get latest cached video frame as base64 PNG. Error if no recent frame (< 5s).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        _: { type: "string", description: "No parameters required" }
+      }
+    }
+  }
+];