paraplex-mcp 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pixel Point
+
+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

@@ -1,3 +1,58 @@
-# Temporary Holding Version
+# paraplex-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Connect Claude Code — or any MCP client — to the [Paraplex](https://paraplex.ai)
+tab you have open. Paraplex is a 3D motion design studio in the browser, with an
+AI assistant that edits real layers and keyframes. With this server, an agent in
+your terminal can build and change scenes in your tab with the same tools the
+assistant uses, look at frames as it goes, and export.
+
+```bash
+claude mcp add paraplex -- npx -y paraplex-mcp
+```
+
+Then ask Claude Code for a piece — "a 10-second launch video with three glass
+cards and our logo" — and it will tell you how to connect:
+
+1. Open Paraplex at <https://app.paraplex.ai>.
+2. **Menu › Connect an agent**, and enter the port and the six-digit code Claude
+   Code gives you.
+
+A banner shows in your tab while an agent is connected; disconnect it there any
+time.
+
+## What it can do
+
+| Tool | What it does |
+| --- | --- |
+| `connection` | Whether a tab is attached; if not, the port and code to give you |
+| `scene` | The open scene: canvas, duration, time, every layer |
+| `list_tools`, `run_tool` | The assistant's verbs (`build_scene`, `add_text`, `set_keyframes`, `add_camera_move`…) and running one |
+| `list_templates`, `apply_template`, `new_project` | Start from a template or a blank file |
+| `set_time`, `frame`, `frames`, `export_png` | Look at the piece at any time, as its export draws it |
+| `scene_facts` | Where every layer lands in the frame, type sizes on the frame, the camera |
+| `export_video` | Export the video to a file on this computer (`./paraplex-exports`, or `PARAPLEX_OUT_DIR`) |
+| `import_hyperframes` | Bring in a HyperFrames project from a folder or .zip on this computer: one code layer, its sound on the timeline |
+| `save_project` | Save the scene as a project in your browser |
+
+Every edit lands in your tab as one undo step, so you can step back through
+anything the agent did.
+
+## Privacy and safety
+
+- The server listens on this computer only (port 47821; pass another as
+  `npx paraplex-mcp 48000`).
+- Only a Paraplex page can connect, and only with the one-time code.
+- Nothing is sent anywhere else: the scene stays in your tab, and exports are
+  written where you ran the server.
+- AI used inside Paraplex is metered by your Paraplex plan as usual; the agent's
+  own model is your Claude Code's.
+
+## Browsers
+
+Chrome, Edge or Arc (other browsers may not let a website reach your own
+computer). If your browser asks to let app.paraplex.ai connect to devices on
+your local network, allow it: that is this server.
+
+## License
+
+MIT © Paraplex Digital, LLC

package/bin.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { createMcpHandler, serveMcpOverStdio } from "./lib/mcp.mjs";
+import { attachedTabTools, attachParaplexTab, PARAPLEX_ATTACH_PORT } from "./lib/paraplex-tab.mjs";
+
+/**
+ * paraplex-mcp: the Paraplex MCP server in attach mode, for anyone.
+ *
+ *   claude mcp add paraplex -- npx -y paraplex-mcp
+ *
+ * It opens no editor of its own: it waits on this computer for the Paraplex
+ * tab you have open to connect (in Paraplex: Menu → Connect an agent, with
+ * the port and the one-time code it gives), then sends its calls there —
+ * every edit lands in your tab as one undo step. Only a Paraplex page may
+ * connect, only with the code. Nothing is sent anywhere else.
+ *
+ *   npx paraplex-mcp [port]          # another port than 47821
+ *   PARAPLEX_OUT_DIR=…               # where export_video writes (./paraplex-exports)
+ */
+
+const here = dirname(fileURLToPath(import.meta.url));
+const { version } = JSON.parse(readFileSync(join(here, "package.json"), "utf8"));
+// stdout is the MCP channel: everything said to the person goes to stderr.
+const log = (text) => process.stderr.write(`[paraplex] ${text}\n`);
+const portArg = process.argv.slice(2).find((arg) => /^\d+$/.test(arg)) ?? process.env.PARAPLEX_PORT;
+const port = portArg !== undefined ? Number(portArg) : PARAPLEX_ATTACH_PORT;
+const outDir = process.env.PARAPLEX_OUT_DIR ?? join(process.cwd(), "paraplex-exports");
+
+let tab;
+
+try {
+  tab = await attachParaplexTab({ log, port });
+} catch (error) {
+  log(`Could not listen on port ${port}: ${error?.message ?? error}. Pass another: npx paraplex-mcp <port>`);
+  process.exit(1);
+}
+
+const settled = serveMcpOverStdio(createMcpHandler({ name: "paraplex", tools: attachedTabTools(tab, { outDir }), version }));
+
+process.stdin.on("end", async () => {
+  await settled();
+  await tab.close();
+  process.exit(0);
+});

package/lib/mcp.mjs

@@ -0,0 +1,115 @@
+/**
+ * The Model Context Protocol, the part a tool server needs (roadmap v10
+ * wave 1): JSON-RPC 2.0 over newline-delimited stdio — `initialize`,
+ * `tools/list`, `tools/call`, `ping`. Pure: the handler takes the tools
+ * and returns responses, so a test can drive it without a browser.
+ */
+
+export const MCP_PROTOCOL_VERSION = "2024-11-05";
+
+export function createMcpHandler({ name, tools, version }) {
+  const byName = new Map(tools.map((tool) => [tool.name, tool]));
+
+  return async function handle(message) {
+    const { id, method, params } = message;
+    const reply = (result) => ({ id, jsonrpc: "2.0", result });
+    const fail = (code, text) => ({ error: { code, message: text }, id, jsonrpc: "2.0" });
+
+    if (method === "initialize") {
+      return reply({ capabilities: { tools: {} }, protocolVersion: MCP_PROTOCOL_VERSION, serverInfo: { name, version } });
+    }
+
+    if (method === "notifications/initialized" || method?.startsWith("notifications/")) {
+      return null;
+    }
+
+    if (method === "ping") {
+      return reply({});
+    }
+
+    if (method === "tools/list") {
+      return reply({ tools: tools.map(({ description, inputSchema, name: toolName }) => ({ description, inputSchema: inputSchema ?? { properties: {}, type: "object" }, name: toolName })) });
+    }
+
+    if (method === "tools/call") {
+      const tool = byName.get(params?.name);
+
+      if (!tool) {
+        return fail(-32602, `Unknown tool: ${params?.name}`);
+      }
+
+      try {
+        const content = await tool.run(params.arguments ?? {});
+
+        // A tool answers with content blocks (each with a `type`) or with
+        // any value, which is shown as text — an array of templates is data,
+        // not a block list.
+        const isBlocks = Array.isArray(content) && content.length > 0 && content.every((block) => block && typeof block === "object" && typeof block.type === "string");
+
+        return reply({ content: isBlocks ? content : [{ text: typeof content === "string" ? content : JSON.stringify(content, null, 2), type: "text" }] });
+      } catch (error) {
+        return reply({ content: [{ text: `Error: ${error?.message ?? String(error)}`, type: "text" }], isError: true });
+      }
+    }
+
+    if (id === undefined) {
+      return null;
+    }
+
+    return fail(-32601, `Method not found: ${method}`);
+  };
+}
+
+/** Runs a handler over stdin/stdout, one JSON message per line. */
+export function serveMcpOverStdio(handle, { input = process.stdin, output = process.stdout } = {}) {
+  let buffer = "";
+  const inFlight = new Set();
+
+  input.setEncoding("utf8");
+  input.on("data", (chunk) => {
+    buffer += chunk;
+
+    let newline = buffer.indexOf("\n");
+
+    while (newline >= 0) {
+      const line = buffer.slice(0, newline).trim();
+
+      buffer = buffer.slice(newline + 1);
+      newline = buffer.indexOf("\n");
+
+      if (!line) {
+        continue;
+      }
+
+      let message;
+
+      try {
+        message = JSON.parse(line);
+      } catch {
+        output.write(`${JSON.stringify({ error: { code: -32700, message: "Parse error" }, id: null, jsonrpc: "2.0" })}\n`);
+        continue;
+      }
+
+      const pending = handle(message).then((response) => {
+        if (response) {
+          output.write(`${JSON.stringify(response)}\n`);
+        }
+      });
+
+      inFlight.add(pending);
+      void pending.finally(() => inFlight.delete(pending));
+    }
+  });
+
+  /** Resolves once every call received so far has answered — for a clean exit when stdin closes. */
+  return () => Promise.allSettled([...inFlight]);
+}
+
+/** Image content for a tool result, from a PNG buffer or data URL. */
+export function imageContent(pngOrDataUrl, text) {
+  const data = Buffer.isBuffer(pngOrDataUrl) ? pngOrDataUrl.toString("base64") : String(pngOrDataUrl).replace(/^data:[^,]+,/, "");
+  const mimeType = Buffer.isBuffer(pngOrDataUrl) ? "image/png" : (/^data:([^;]+)/.exec(String(pngOrDataUrl))?.[1] ?? "image/png");
+  const content = [{ data, mimeType, type: "image" }];
+
+  return text ? [{ text, type: "text" }, ...content] : content;
+}

package/lib/paraplex-tab.mjs

@@ -0,0 +1,365 @@
+import { randomInt } from "node:crypto";
+import { mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+
+import { imageContent } from "./mcp.mjs";
+import { serveWebSocket } from "./ws-server.mjs";
+
+/**
+ * The agent bridge attached to the person's own tab (roadmap v11, wave 5):
+ * where `npm run agent` opens a headless editor of its own, `npm run agent
+ * -- attach` waits for the Paraplex tab the person has open to connect —
+ * Menu → Connect an agent, with the port and the one-time code printed
+ * here — and sends its calls there. Only a page from Paraplex's origins
+ * may connect, only with the code, and only the named calls the tab's
+ * connector answers exist (agent-connector.ts); no code is sent into the
+ * tab.
+ */
+
+export const PARAPLEX_ATTACH_PORT = 47821;
+
+/** What a project folder may send the tab: past this, its media will not fit a layer anyway. */
+const PROJECT_MAX_BYTES = 96 * 1024 * 1024;
+const PROJECT_MAX_FILES = 4000;
+const PROJECT_SKIPPED = new Set([".git", ".DS_Store", "__MACOSX", "node_modules"]);
+
+/**
+ * A HyperFrames project for the tab (roadmap v20 WB.2): a folder's files as
+ * path → base64 (system and dependency folders left out), or a zip's bytes
+ * as base64 — the tab makes it one code layer.
+ */
+export function readParaplexProject(path) {
+  const root = resolve(path);
+  const stat = statSync(root);
+
+  if (stat.isFile()) {
+    if (!/\.zip$/i.test(root)) {
+      throw new Error(`${path} is a file: give the project's folder, or a .zip of it.`);
+    }
+
+    if (stat.size > PROJECT_MAX_BYTES) {
+      throw new Error(`${path} is ${Math.round(stat.size / 1024 / 1024)} MB, more than a project can bring.`);
+    }
+
+    return { name: basename(root).replace(/\.zip$/i, ""), zip: readFileSync(root).toString("base64") };
+  }
+
+  const files = {};
+  let bytes = 0;
+  let count = 0;
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (PROJECT_SKIPPED.has(entry.name)) {
+        continue;
+      }
+
+      const full = join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        walk(full);
+      } else if (entry.isFile()) {
+        count += 1;
+        bytes += statSync(full).size;
+
+        if (count > PROJECT_MAX_FILES || bytes > PROJECT_MAX_BYTES) {
+          throw new Error(`${path} holds more than a project can bring (${PROJECT_MAX_FILES} files, ${PROJECT_MAX_BYTES / 1024 / 1024} MB). Leave renders and other large files out.`);
+        }
+
+        files[relative(root, full).split("\\").join("/")] = readFileSync(full).toString("base64");
+      }
+    }
+  };
+
+  walk(root);
+
+  return { files, name: basename(root) };
+}
+
+/** Paraplex's own origins, and a local dev server's; PARAPLEX_ORIGIN adds one. */
+export function paraplexOriginAllowed(origin) {
+  const extra = process.env.PARAPLEX_ORIGIN;
+
+  return (
+    (typeof extra === "string" && extra.length > 0 && origin === extra) ||
+    /^https:\/\/(www\.|app\.)?paraplex\.ai$/.test(origin) ||
+    /^https:\/\/([a-z0-9-]+--)?paraplex[a-z0-9-]*\.netlify\.app$/.test(origin) ||
+    /^http:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/.test(origin)
+  );
+}
+
+/**
+ * Starts the local endpoint and returns `call(method, params)`: sent to the
+ * attached tab, answered by it; waits (up to a few minutes) for a tab when
+ * none is attached yet.
+ */
+export async function attachParaplexTab({ allowOrigin = paraplexOriginAllowed, code = String(randomInt(100000, 1000000)), log = () => {}, port = PARAPLEX_ATTACH_PORT } = {}) {
+  let tab = null;
+  let next = 1;
+  const pending = new Map();
+  let waiters = [];
+
+  const server = await serveWebSocket({
+    allowOrigin,
+    onConnection: (peer) => {
+      peer.onMessage = (text) => {
+        let data;
+
+        try {
+          data = JSON.parse(text);
+        } catch {
+          return;
+        }
+
+        if (data.type === "hello") {
+          if (String(data.code ?? "") !== code) {
+            peer.send(JSON.stringify({ reason: "That code does not match the one the agent printed.", type: "refused" }));
+            peer.close();
+            return;
+          }
+
+          // A second tab takes over from the first.
+          if (tab && tab !== peer) {
+            tab.close();
+          }
+
+          tab = peer;
+          peer.send(JSON.stringify({ type: "welcome" }));
+          log("A Paraplex tab is attached.");
+
+          for (const wake of waiters) {
+            wake();
+          }
+
+          waiters = [];
+        } else if (data.type === "result" && pending.has(data.id)) {
+          const { reject, resolve } = pending.get(data.id);
+
+          pending.delete(data.id);
+
+          if (data.ok) {
+            resolve(data.value);
+          } else {
+            reject(new Error(data.error ?? "The tab could not do that."));
+          }
+        }
+      };
+      peer.onClose = () => {
+        if (tab === peer) {
+          tab = null;
+
+          for (const { reject } of pending.values()) {
+            reject(new Error("The tab disconnected."));
+          }
+
+          pending.clear();
+          log("The tab disconnected.");
+        }
+      };
+    },
+    port,
+  });
+  const address = server.address();
+  const listening = typeof address === "object" && address ? address.port : port;
+
+  log(`Waiting for a Paraplex tab: in Paraplex, Menu → Connect an agent, port ${listening}, code ${code}.`);
+
+  const call = async (method, params = {}) => {
+    if (!tab) {
+      await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`No Paraplex tab is attached. In Paraplex: Menu → Connect an agent, port ${listening}, code ${code}.`)), 180_000);
+
+        waiters.push(() => {
+          clearTimeout(timer);
+          resolve();
+        });
+      });
+    }
+
+    const id = next++;
+
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        if (pending.delete(id)) {
+          reject(new Error("The tab did not answer in time."));
+        }
+      }, 600_000);
+
+      pending.set(id, {
+        reject: (error) => {
+          clearTimeout(timer);
+          reject(error);
+        },
+        resolve: (value) => {
+          clearTimeout(timer);
+          resolve(value);
+        },
+      });
+      tab.send(JSON.stringify({ id, method, params, type: "call" }));
+    });
+  };
+
+  return {
+    attached: () => tab !== null,
+    call,
+    close: () => new Promise((resolve) => {
+      tab?.close();
+      server.close(() => resolve());
+    }),
+    code,
+    port: listening,
+  };
+}
+
+/** The MCP tools over an attached tab: the headless server's, as far as named calls reach. */
+export function attachedTabTools(tab, { outDir }) {
+  return [
+    {
+      // The person cannot see this server's log from Claude Code: the agent
+      // asks for the port and code here and tells them.
+      description:
+        "Whether a Paraplex tab is attached, and if not, what to tell the person: in Paraplex, Menu → Connect an agent, then this port and code. Call it first; say the code to the person exactly.",
+      name: "connection",
+      run: () =>
+        tab.attached()
+          ? { attached: true, port: tab.port }
+          : {
+              attached: false,
+              code: tab.code,
+              port: tab.port,
+              tell: `Open Paraplex in your browser, then Menu → Connect an agent, and enter port ${tab.port} and code ${tab.code}.`,
+            },
+    },
+    {
+      description: "The built-in templates: id, label and categories (the first is its section on the home page, e.g. app-promo, brand-promo, starter, website-hero-visuals, titles-text, infographics).",
+      name: "list_templates",
+      run: () => tab.call("templates"),
+    },
+    {
+      description: "A blank 1920×1080 project in the attached tab (the scene being left is saved as the editor saves it).",
+      name: "new_project",
+      run: async () => {
+        await tab.call("newProject");
+
+        return "A new project.";
+      },
+    },
+    {
+      description: "Apply a built-in template by id, as the gallery does.",
+      inputSchema: { properties: { id: { type: "string" } }, required: ["id"], type: "object" },
+      name: "apply_template",
+      run: async ({ id }) => {
+        await tab.call("applyTemplate", { id });
+
+        return tab.call("scene");
+      },
+    },
+    {
+      description: "The open scene: canvas, duration, current time, and every layer with its kind, name, clip and parent.",
+      name: "scene",
+      run: () => tab.call("scene"),
+    },
+    {
+      description: "Move the playhead to a time in seconds.",
+      inputSchema: { properties: { seconds: { type: "number" } }, required: ["seconds"], type: "object" },
+      name: "set_time",
+      run: async ({ seconds }) => `At ${await tab.call("setTime", { seconds })}s.`,
+    },
+    {
+      description: "A picture of the frame at a time (or the current one), through the export path — the way to look at what you made.",
+      inputSchema: { properties: { seconds: { type: "number" } }, type: "object" },
+      name: "frame",
+      run: async ({ seconds }) => {
+        const dataUrl = await tab.call("exportPng", seconds === undefined ? {} : { seconds });
+
+        return dataUrl ? imageContent(dataUrl, seconds === undefined ? "The frame now." : `The frame at ${seconds}s.`) : "No editor.";
+      },
+    },
+    {
+      description: "The frame at several times (default: four across the piece), one picture each.",
+      inputSchema: { properties: { times: { items: { type: "number" }, type: "array" } }, type: "object" },
+      name: "frames",
+      run: async ({ times }) => {
+        const scene = await tab.call("scene");
+        const moments = times?.length ? times : Array.from({ length: 4 }, (_, index) => Number((((scene?.durationSeconds ?? 8) * (index + 0.5)) / 4).toFixed(2)));
+        const content = [];
+
+        for (const seconds of moments) {
+          const dataUrl = await tab.call("exportPng", { seconds });
+
+          if (dataUrl) {
+            content.push(...imageContent(dataUrl, `${seconds}s`));
+          }
+        }
+
+        return content.length > 0 ? content : "No editor.";
+      },
+    },
+    {
+      description: "The assistant's tools — every verb that edits the scene — with their input schemas. Run one with run_tool.",
+      name: "list_tools",
+      run: () => tab.call("tools"),
+    },
+    {
+      description: "Run one of the assistant's tools in the attached tab (see list_tools), e.g. build_scene, add_text, set_property, add_camera_move — each call one undo step there.",
+      inputSchema: { properties: { input: { type: "object" }, name: { type: "string" } }, required: ["name"], type: "object" },
+      name: "run_tool",
+      run: ({ input, name }) => tab.call("runTool", { input: input ?? {}, name }),
+    },
+    {
+      description: "The scene at the current time through the export path (what a PNG export produces), as an image.",
+      name: "export_png",
+      run: async () => {
+        const dataUrl = await tab.call("exportPng");
+
+        return dataUrl ? imageContent(dataUrl, "The export.") : "No editor.";
+      },
+    },
+    {
+      description: "Export the scene as a video, written to a file in the export folder (or at `path`); answers with where it went.",
+      inputSchema: { properties: { path: { type: "string" } }, type: "object" },
+      name: "export_video",
+      run: async ({ path }) => {
+        const result = await tab.call("exportVideo");
+
+        if (!result) {
+          return "No editor.";
+        }
+
+        const target = path ?? join(outDir, result.fileName);
+
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, Buffer.from(String(result.dataUrl).replace(/^data:[^,]+,/, ""), "base64"));
+
+        return `Written: ${target}`;
+      },
+    },
+    {
+      description:
+        "Import a HyperFrames project (HeyGen's HTML-to-video format) into the attached tab: `path` is its folder (index.html at the top) or a .zip of it. The whole project becomes one code layer — nested data-composition-src files, pictures, videos, fonts and stylesheets embedded, HyperFrames' runtime driven by the playhead — and each <audio> clip a sound layer at its start. Then look at it with frames, and finish it by hand or with run_tool.",
+      inputSchema: { properties: { name: { type: "string" }, path: { type: "string" } }, required: ["path"], type: "object" },
+      name: "import_hyperframes",
+      run: async ({ name, path }) => {
+        const project = readParaplexProject(path);
+        const result = await tab.call("importHyperFrames", { ...project, ...(name ? { name } : {}) });
+
+        if (!result?.ok) {
+          throw new Error(result?.message ?? "The tab did not import it.");
+        }
+
+        return { message: result.message, missing: result.missing ?? [], scene: await tab.call("scene") };
+      },
+    },
+    {
+      description: "Save the open scene as a project of that browser's, by name.",
+      inputSchema: { properties: { name: { type: "string" } }, required: ["name"], type: "object" },
+      name: "save_project",
+      run: async ({ name }) => `Saved as project ${await tab.call("saveProject", { name })}.`,
+    },
+    {
+      description: "The review's facts at a time: where every layer lands on the frame (NDC boxes, ±1 is the frame's edge), each text's size on the frame in px and its fill, the camera.",
+      inputSchema: { properties: { seconds: { type: "number" } }, required: ["seconds"], type: "object" },
+      name: "scene_facts",
+      run: ({ seconds }) => tab.call("sceneFacts", { seconds }),
+    },
+  ];
+}

package/lib/ws-server.mjs

@@ -0,0 +1,181 @@
+import { createHash } from "node:crypto";
+import { createServer } from "node:http";
+
+/**
+ * A small WebSocket server (RFC 6455) over Node's own http and crypto, for
+ * the agent bridge's attach mode (roadmap v11, wave 5): one text message
+ * at a time each way, the client's frames masked as browsers send them,
+ * fragments joined, pings answered, a close closed. No extension, no
+ * binary messages — the bridge speaks JSON. Listens on 127.0.0.1 only, and
+ * refuses a handshake whose Origin the caller does not allow.
+ */
+
+const GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
+/** The largest message taken: a 4K export as a data URL fits with room. */
+const MAX_MESSAGE_BYTES = 64 * 1024 * 1024;
+
+function frame(opcode, payload) {
+  const length = payload.length;
+  const head = length < 126 ? Buffer.alloc(2) : length < 65536 ? Buffer.alloc(4) : Buffer.alloc(10);
+
+  head[0] = 0x80 | opcode;
+
+  if (length < 126) {
+    head[1] = length;
+  } else if (length < 65536) {
+    head[1] = 126;
+    head.writeUInt16BE(length, 2);
+  } else {
+    head[1] = 127;
+    head.writeBigUInt64BE(BigInt(length), 2);
+  }
+
+  return Buffer.concat([head, payload]);
+}
+
+/** One connection: `send(text)`, `close()`, and `onMessage` / `onClose` to set. */
+function connection(socket) {
+  let buffer = Buffer.alloc(0);
+  let fragments = [];
+  let closed = false;
+  const peer = {
+    close() {
+      if (!closed) {
+        closed = true;
+        socket.end(frame(0x8, Buffer.alloc(0)));
+      }
+    },
+    onClose: () => {},
+    onMessage: () => {},
+    send(text) {
+      if (!closed) {
+        socket.write(frame(0x1, Buffer.from(text, "utf8")));
+      }
+    },
+  };
+
+  socket.on("data", (chunk) => {
+    buffer = Buffer.concat([buffer, chunk]);
+
+    for (;;) {
+      if (buffer.length < 2) {
+        return;
+      }
+
+      const fin = (buffer[0] & 0x80) !== 0;
+      const opcode = buffer[0] & 0x0f;
+      const masked = (buffer[1] & 0x80) !== 0;
+      let length = buffer[1] & 0x7f;
+      let offset = 2;
+
+      if (length === 126) {
+        if (buffer.length < 4) {
+          return;
+        }
+
+        length = buffer.readUInt16BE(2);
+        offset = 4;
+      } else if (length === 127) {
+        if (buffer.length < 10) {
+          return;
+        }
+
+        length = Number(buffer.readBigUInt64BE(2));
+        offset = 10;
+      }
+
+      if (length > MAX_MESSAGE_BYTES) {
+        peer.close();
+        socket.destroy();
+        return;
+      }
+
+      const maskOffset = offset;
+
+      if (masked) {
+        offset += 4;
+      }
+
+      if (buffer.length < offset + length) {
+        return;
+      }
+
+      const payload = Buffer.from(buffer.subarray(offset, offset + length));
+
+      if (masked) {
+        for (let index = 0; index < payload.length; index += 1) {
+          payload[index] ^= buffer[maskOffset + (index % 4)];
+        }
+      }
+
+      buffer = buffer.subarray(offset + length);
+
+      if (opcode === 0x8) {
+        peer.close();
+        return;
+      }
+
+      if (opcode === 0x9) {
+        socket.write(frame(0xa, payload));
+        continue;
+      }
+
+      if (opcode === 0xa) {
+        continue;
+      }
+
+      // Text, or a continuation of it; binary is not spoken here.
+      if (opcode === 0x1 || opcode === 0x0) {
+        fragments.push(payload);
+
+        if (fin) {
+          const text = Buffer.concat(fragments).toString("utf8");
+
+          fragments = [];
+          peer.onMessage(text);
+        }
+      }
+    }
+  });
+  socket.on("close", () => {
+    closed = true;
+    peer.onClose();
+  });
+  socket.on("error", () => {
+    closed = true;
+  });
+
+  return peer;
+}
+
+/**
+ * Listens on 127.0.0.1:`port`; each accepted connection is handed to
+ * `onConnection(peer, request)`. A handshake whose Origin `allowOrigin`
+ * refuses gets a 403 and no socket.
+ */
+export function serveWebSocket({ allowOrigin, onConnection, port }) {
+  const server = createServer((_request, response) => {
+    response.writeHead(426, { "content-type": "text/plain" });
+    response.end("A WebSocket endpoint.");
+  });
+
+  server.on("upgrade", (request, socket) => {
+    const key = request.headers["sec-websocket-key"];
+    const origin = request.headers.origin ?? "";
+
+    if (typeof key !== "string" || (request.headers.upgrade ?? "").toLowerCase() !== "websocket" || !allowOrigin(origin)) {
+      socket.end("HTTP/1.1 403 Forbidden\r\n\r\n");
+      return;
+    }
+
+    const accept = createHash("sha1").update(key + GUID).digest("base64");
+
+    socket.write(["HTTP/1.1 101 Switching Protocols", "Upgrade: websocket", "Connection: Upgrade", `Sec-WebSocket-Accept: ${accept}`, "", ""].join("\r\n"));
+    onConnection(connection(socket), request);
+  });
+
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, "127.0.0.1", () => resolve(server));
+  });
+}

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "paraplex-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "mcpName": "io.github.Paraplex-AI/paraplex-mcp",
+  "description": "Connect Claude Code (or any MCP client) to the Paraplex tab you have open: build and edit 3D motion design scenes with the assistant's tools, look at frames, export.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "claude-code",
+    "paraplex",
+    "motion design",
+    "3d",
+    "animation"
+  ],
+  "homepage": "https://paraplex.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Paraplex-AI/paraplex-mcp.git"
+  },
+  "license": "MIT",
+  "author": "Paraplex Digital, LLC <info@paraplex.ai>",
+  "type": "module",
+  "bin": {
+    "paraplex-mcp": "bin.mjs"
+  },
+  "files": [
+    "bin.mjs",
+    "lib/",
+    "skills/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "prepack": "node ../../scripts/build-mcp-package.mjs"
+  }
+}

package/skills/paraplex/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: paraplex
+description: Make or change a motion piece in the person's own open Paraplex tab from Claude Code — attach through the Paraplex MCP server (attach mode), build with the assistant's verbs (build_scene for a whole piece), look at frames as you go, and export. Use when the person asks for a video, a promo, a title sequence, a UI animation or any Paraplex scene to be made or edited from the terminal.
+---
+
+# Paraplex from Claude Code
+
+Paraplex is a browser editor for motion design: 3D panels, type, particles,
+formations, generators, code layers, a keyframe timeline, and exports. The
+Paraplex MCP server in **attach mode** drives the tab the person already has
+open — their scene, their undo — rather than an editor of its own.
+
+## Connect
+
+1. The server is registered once (it waits on this computer for the
+   person's tab; nothing is installed in the browser):
+   `claude mcp add paraplex -- npx -y paraplex-mcp`
+   (Working in the Paraplex repo itself, `npm run agent --silent -- attach`
+   is the same server.)
+2. Call `connection`. Until a tab is attached it gives a port and a
+   one-time code: tell the person, word for word, to open Paraplex and go to
+   **Menu → Connect an agent**, then enter that port and code. A banner in
+   their tab shows while you are connected; they can disconnect any time.
+3. Call `scene` to see what is there before changing anything.
+
+Everything you run lands in their tab, each verb one undo step for them. Say
+what you changed after each step; never clear their scene without asking.
+
+## Build
+
+- `list_tools` gives every verb with its schema; `run_tool` runs one.
+- A whole piece in one call: `run_tool` with `build_scene` — each layer the
+  fields of its add verb plus `props`, `keys` (`[seconds, value, easing]`,
+  the easing arriving at the key), `clip`, `children` and `then` (any other
+  verb, `$id` naming another layer). Read its `warnings`: what could not be
+  built is skipped and said.
+- Small changes: the verbs themselves (`set_property`, `set_keyframes`,
+  `add_camera_move`, `set_text_animation`, `set_layout` …), addressed by the
+  layer names the spec gave.
+- Procedural geometry: `add_generator` (a starter or your own module);
+  many cards or dots in one shape: `add_formation` + `key_formation`; live
+  HTML or a React component: `write_code_layer`.
+- A HyperFrames project you wrote (or the person has): `import_hyperframes`
+  with its folder or .zip. The whole project becomes one code layer —
+  nested compositions, media and HyperFrames' runtime driven by the
+  playhead — and each `<audio>` clip a sound layer at its start. Then build
+  around it: Paraplex layers over or behind it, camera moves, effects.
+- A Remotion composition: `write_code_layer` with the one file (component
+  and `<Composition>` together). Its `remotion` import is Paraplex's own
+  version on the layer's clock — `useCurrentFrame`, `Sequence`, `Series`,
+  `interpolate`, `spring`, `@remotion/google-fonts` — and `<Composition>`
+  sets the layer's size and length. `<Audio>` is silent: add sound with
+  the audio verbs; `staticFile` has no folder: use web addresses.
+
+## Look, then fix
+
+After every section, look: `frames` (one picture per time), `frame` at a
+moment, `scene_facts` (where each layer lands on the frame, type sizes, the
+camera). Check frame fit (nothing the piece is about half out of frame at a
+hold), type (a caption ≥ 14 px on the frame, contrast ≥ 3:1), motion (one
+ease per move, holds long enough to read) — fix what you see, then look
+again. Work section by section for anything longer than a few seconds: plan
+the sections, block a storyboard with `build_scene`, show the person the
+frames, and build once they agree.
+
+## Deliver
+
+`export_png` returns a still; `export_video` writes the file (in
+`./paraplex-exports`, where the server was started) and says where.
+`save_project` saves the scene in their browser by name.