paraplex-mcp 0.2.1 → 0.3.0

package/README.md

@@ -30,9 +30,16 @@ time.
 | `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`) |
+| `export` | Export to a file on this computer (`./paraplex-exports`, or `PARAPLEX_OUT_DIR`) with any of the Export section's options for that export only: image or video, format, scale, frame rate, part of the timeline, no background, one artboard or all, App Store / Keynote / PowerPoint / Google Slides presets. Large files stream in pieces, so there is no size ceiling |
+| `render_variants` | A render per row of data (rows or CSV), each column filling the layer of its name |
+| `export_video` | The video at the scene's own settings (kept from 0.2) |
+| `import_file` | Send a file from this computer into the scene, as a drop takes it: a picture or video, sound, a 3D model, Lottie, Figma frames, an SVG, a font |
 | `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 |
+| `undo`, `redo` | Step back or forward, as ⌘Z does |
+| `review_sheet`, `review_artboards` | Frames across the piece as one sheet, with what runs past the frame, small or low-contrast type, and motion hitches; or the piece on 9:16, 4:5, 1:1 and 16:9 |
+| `list_projects`, `open_project`, `save_project` | Your projects in this browser and your account; open one, or save the scene as one |
+| `list_design_systems`, `apply_design_system` | Paraplex's design systems and yours; apply one in a single undo step |
+| `list_skills`, `load_skill`, `read_skill_file`, `write_skill` | The assistant's skills: read them, or write one into your library |
 
 Every edit lands in your tab as one undo step, so you can step back through
 anything the agent did.
@@ -42,8 +49,9 @@ anything the agent did.
 - 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.
+- Nothing is sent anywhere else: the scene stays in your tab, exports are
+  written where you ran the server, and a file you send in goes only to your
+  tab. An agent reaches only what you are signed in to in that tab.
 - AI used inside Paraplex is metered by your Paraplex plan as usual; the agent's
   own model is your Claude Code's.
 

package/lib/paraplex-tab.mjs

@@ -1,6 +1,6 @@
-import { randomInt } from "node:crypto";
-import { mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { basename, dirname, join, relative, resolve } from "node:path";
+import { randomInt, randomUUID } from "node:crypto";
+import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, renameSync, statSync, writeSync } from "node:fs";
+import { basename, dirname, extname, join, relative, resolve } from "node:path";
 
 import { imageContent } from "./mcp.mjs";
 import { serveWebSocket } from "./ws-server.mjs";
@@ -18,6 +18,35 @@ import { serveWebSocket } from "./ws-server.mjs";
 
 export const PARAPLEX_ATTACH_PORT = 47821;
 
+/** A piece of a file each way (roadmap v22 W5): 768 KB, about 1 MB as base64. */
+export const PARAPLEX_CHUNK_BYTES = 768 * 1024;
+
+/** A path in `dir` for `fileName` that is not taken: "name.mp4", then "name-2.mp4". */
+export function paraplexFreePath(dir, fileName) {
+  const safe = basename(String(fileName || "paraplex-export")).replace(/[\\/:*?"<>|]+/g, "-");
+  const extension = extname(safe);
+  const stem = safe.slice(0, safe.length - extension.length);
+  let candidate = join(dir, safe);
+
+  for (let index = 2; existsSync(candidate); index += 1) {
+    candidate = join(dir, `${stem}-${index}${extension}`);
+  }
+
+  return candidate;
+}
+
+/** What a file's extension says it is, for the tab's import. */
+export function paraplexMimeType(path) {
+  const types = {
+    ".aac": "audio/aac", ".avif": "image/avif", ".csv": "text/csv", ".flac": "audio/flac", ".gif": "image/gif", ".glb": "model/gltf-binary", ".gltf": "model/gltf+json",
+    ".jpeg": "image/jpeg", ".jpg": "image/jpeg", ".json": "application/json", ".lottie": "application/zip", ".m4a": "audio/mp4", ".mov": "video/quicktime", ".mp3": "audio/mpeg",
+    ".mp4": "video/mp4", ".ogg": "audio/ogg", ".otf": "font/otf", ".png": "image/png", ".ply": "application/octet-stream", ".splat": "application/octet-stream", ".spz": "application/octet-stream",
+    ".svg": "image/svg+xml", ".ttf": "font/ttf", ".wav": "audio/wav", ".webm": "video/webm", ".webp": "image/webp", ".woff": "font/woff", ".woff2": "font/woff2",
+  };
+
+  return types[extname(path).toLowerCase()] ?? "application/octet-stream";
+}
+
 /** 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;
@@ -131,13 +160,40 @@ export async function attachParaplexTab({ allowOrigin = paraplexOriginAllowed, c
           }
 
           waiters = [];
+        } else if (data.type === "file" && pending.has(data.id)) {
+          // A file the call sends back, in pieces: written as they come.
+          const entry = pending.get(data.id);
+          const dir = entry.into ?? join(process.cwd(), "paraplex-exports");
+
+          mkdirSync(dir, { recursive: true });
+
+          const path = paraplexFreePath(dir, data.fileName);
+
+          entry.files.set(data.file, { bytes: 0, fd: openSync(path, "w"), path });
+        } else if (data.type === "chunk" && pending.has(data.id)) {
+          const file = pending.get(data.id).files.get(data.file);
+
+          if (file && typeof data.data === "string") {
+            file.bytes += writeSync(file.fd, Buffer.from(data.data, "base64"));
+          }
         } else if (data.type === "result" && pending.has(data.id)) {
-          const { reject, resolve } = pending.get(data.id);
+          const { files, reject, resolve } = pending.get(data.id);
 
           pending.delete(data.id);
 
+          for (const file of files.values()) {
+            closeSync(file.fd);
+          }
+
           if (data.ok) {
-            resolve(data.value);
+            // A streamed file's number in the answer becomes where it was written.
+            const value = data.value;
+
+            if (value && Array.isArray(value.files) && files.size > 0) {
+              resolve({ ...value, files: value.files.map((entry) => (files.has(entry.file) ? { ...entry, bytes: files.get(entry.file).bytes, path: files.get(entry.file).path } : entry)) });
+            } else {
+              resolve(value);
+            }
           } else {
             reject(new Error(data.error ?? "The tab could not do that."));
           }
@@ -147,7 +203,11 @@ export async function attachParaplexTab({ allowOrigin = paraplexOriginAllowed, c
         if (tab === peer) {
           tab = null;
 
-          for (const { reject } of pending.values()) {
+          for (const { files, reject } of pending.values()) {
+            for (const file of files.values()) {
+              closeSync(file.fd);
+            }
+
             reject(new Error("The tab disconnected."));
           }
 
@@ -163,7 +223,7 @@ export async function attachParaplexTab({ allowOrigin = paraplexOriginAllowed, c
 
   log(`Waiting for a Paraplex tab: in Paraplex, Menu → Connect an agent, port ${listening}, code ${code}.`);
 
-  const call = async (method, params = {}) => {
+  const waitForTab = async () => {
     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);
@@ -174,6 +234,43 @@ export async function attachParaplexTab({ allowOrigin = paraplexOriginAllowed, c
         });
       });
     }
+  };
+
+  /**
+   * Sends a local file to the tab in pieces, ahead of the call that uses
+   * it; resolves with its upload id.
+   */
+  const upload = async (path) => {
+    await waitForTab();
+
+    const uploadId = randomUUID();
+    const mimeType = paraplexMimeType(path);
+    const fd = openSync(path, "r");
+    const buffer = Buffer.alloc(PARAPLEX_CHUNK_BYTES);
+
+    try {
+      for (;;) {
+        const read = readSync(fd, buffer, 0, buffer.length, null);
+
+        if (read <= 0) {
+          break;
+        }
+
+        tab.send(JSON.stringify({ data: buffer.subarray(0, read).toString("base64"), mimeType, type: "upload", upload: uploadId }));
+      }
+    } finally {
+      closeSync(fd);
+    }
+
+    // An empty file still arrives, as nothing.
+    tab.send(JSON.stringify({ mimeType, type: "upload", upload: uploadId }));
+
+    return uploadId;
+  };
+
+  /** A call to the tab; `into` is where files it streams back are written. */
+  const call = async (method, params = {}, { into } = {}) => {
+    await waitForTab();
 
     const id = next++;
 
@@ -185,6 +282,8 @@ export async function attachParaplexTab({ allowOrigin = paraplexOriginAllowed, c
       }, 600_000);
 
       pending.set(id, {
+        files: new Map(),
+        into,
         reject: (error) => {
           clearTimeout(timer);
           reject(error);
@@ -201,6 +300,7 @@ export async function attachParaplexTab({ allowOrigin = paraplexOriginAllowed, c
   return {
     attached: () => tab !== null,
     call,
+    upload,
     close: () => new Promise((resolve) => {
       tab?.close();
       server.close(() => resolve());
@@ -210,6 +310,28 @@ export async function attachParaplexTab({ allowOrigin = paraplexOriginAllowed, c
   };
 }
 
+/**
+ * An export through the tab, its files streamed into `path` (a folder, or
+ * a file name when one file comes back) or the export folder; answers with
+ * each file, where it went and its size.
+ */
+export async function exportToDisk(tab, options, { outDir, path }) {
+  const asFile = typeof path === "string" && extname(path) !== "" && !(existsSync(path) && statSync(path).isDirectory());
+  const into = path ? (asFile ? dirname(resolve(path)) : resolve(path)) : outDir;
+  const result = await tab.call("exportFiles", options, { into });
+  const files = Array.isArray(result?.files) ? result.files : [];
+
+  if (asFile && files.length === 1 && files[0].path && resolve(path) !== files[0].path) {
+    renameSync(files[0].path, resolve(path));
+    files[0].path = resolve(path);
+  }
+
+  return {
+    files: files.map(({ bytes, fileName, notice, path: written }) => ({ bytes, fileName, ...(notice ? { notice } : {}), path: written })),
+    written: files.map((file) => file.path).join(", "),
+  };
+}
+
 /** The MCP tools over an attached tab: the headless server's, as far as named calls reach. */
 export function attachedTabTools(tab, { outDir }) {
   return [
@@ -315,23 +437,53 @@ export function attachedTabTools(tab, { outDir }) {
       },
     },
     {
-      description: "Export the scene as a video, written to a file in the export folder (or at `path`); answers with where it went.",
+      description:
+        "Export with any of the Export section's options, the files written on this computer as the tab renders them (no size limit): an image (png, jpg) at `seconds`, or a video (mp4, webm, gif, png-sequence) over `inSeconds`–`outSeconds`; `scale` 0.5–4, `fps`, `background: false` for transparency (PNG, WebM, PNG sequence); `artboard` an artboard's id or label, or \"all\" for one file each; `deliver` a destination's preset (app-store with `device` iphone/ipad/mac, keynote, powerpoint, google-slides). Only what you pass changes, and only for this export: the person's settings stay. `path` is a folder, or a file name for a single file (default ./paraplex-exports). A Free account gets the reason a Pro export is refused.",
+      inputSchema: {
+        properties: {
+          artboard: { type: "string" },
+          background: { type: "boolean" },
+          deliver: { enum: ["app-store", "keynote", "powerpoint", "google-slides"], type: "string" },
+          device: { enum: ["iphone", "ipad", "mac"], type: "string" },
+          format: { enum: ["png", "jpg", "mp4", "webm", "gif", "png-sequence"], type: "string" },
+          fps: { type: "number" },
+          inSeconds: { type: "number" },
+          kind: { enum: ["image", "video"], type: "string" },
+          outSeconds: { type: "number" },
+          path: { type: "string" },
+          scale: { type: "number" },
+          seconds: { type: "number" },
+        },
+        type: "object",
+      },
+      name: "export",
+      run: async ({ path, ...options }) => exportToDisk(tab, options, { outDir, path }),
+    },
+    {
+      description:
+        "Render a variant per row, as Variants does: `rows` (objects) or `csv` (a header row, then a row per variant). Each column fills the layer named like it — its text, a counter's end value, a fill color, or a picture by its file name in the scene's media library — or the layer `bindings` maps it to (column → layer id or name). `nameColumn` names each file. Takes every option `export` takes (an image by default; kind video for a clip per row). Without rows, the sheet already set in Variants. Answers with the files and any column that bound to nothing.",
+      inputSchema: {
+        properties: {
+          bindings: { additionalProperties: { type: "string" }, type: "object" },
+          csv: { type: "string" },
+          format: { enum: ["png", "jpg", "mp4", "webm", "gif", "png-sequence"], type: "string" },
+          kind: { enum: ["image", "video"], type: "string" },
+          nameColumn: { type: "string" },
+          options: { description: "Any other export option: scale, fps, seconds, inSeconds, outSeconds, background, artboard.", type: "object" },
+          path: { type: "string" },
+          rows: { items: { type: "object" }, type: "array" },
+        },
+        type: "object",
+      },
+      name: "render_variants",
+      run: async ({ bindings, csv, format, kind, nameColumn, options, path, rows }) =>
+        exportToDisk(tab, { ...(options ?? {}), ...(format ? { format } : {}), ...(kind ? { kind } : {}), variants: { ...(bindings ? { bindings } : {}), ...(csv !== undefined ? { csv } : {}), ...(nameColumn ? { nameColumn } : {}), ...(rows ? { rows } : {}) } }, { outDir, path: path ?? join(outDir, "variants") }),
+    },
+    {
+      description: "Export the scene as a video with its own settings, written to a file in the export folder (or at `path`); answers with where it went. The `export` tool takes every option.",
       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}`;
-      },
+      run: async ({ path }) => exportToDisk(tab, { kind: "video" }, { outDir, path }),
     },
     {
       description:
@@ -349,6 +501,114 @@ export function attachedTabTools(tab, { outDir }) {
         return { message: result.message, missing: result.missing ?? [], scene: await tab.call("scene") };
       },
     },
+    {
+      description:
+        "Bring a file from this computer into the open scene, as dropping it on the canvas does: a picture or video becomes a layer (or fills the layer `target`, by id — a card, a phone screen, a component's slot), sound a clip at the playhead, a GLB/glTF/splat a model, a .lottie or Lottie .json an animation, an SVG a vector, a TTF/OTF/WOFF a font of the scene's. Answers with what happened and the layers it added.",
+      inputSchema: { properties: { path: { type: "string" }, target: { type: "string" } }, required: ["path"], type: "object" },
+      name: "import_file",
+      run: async ({ path, target }) => {
+        const full = resolve(path);
+
+        if (!existsSync(full) || !statSync(full).isFile()) {
+          throw new Error(`No file at ${full}.`);
+        }
+
+        const upload = await tab.upload(full);
+
+        return tab.call("importFile", { name: basename(full), upload, ...(target ? { target } : {}) });
+      },
+    },
+    {
+      description: "Undo the last `steps` edits in the tab (default 1), as ⌘Z does — a run_tool call is one step. Answers with how many it took and whether more remain.",
+      inputSchema: { properties: { steps: { type: "number" } }, type: "object" },
+      name: "undo",
+      run: ({ steps }) => tab.call("undo", { steps: steps ?? 1 }),
+    },
+    {
+      description: "Redo `steps` undone edits (default 1), as ⇧⌘Z does.",
+      inputSchema: { properties: { steps: { type: "number" } }, type: "object" },
+      name: "redo",
+      run: ({ steps }) => tab.call("redo", { steps: steps ?? 1 }),
+    },
+    {
+      description:
+        "A review sheet of the open scene, the way to judge a piece before calling it done: frames across it (default eight; or `times`) as one picture, and the flags — layers past the frame (more than 0.05 of the frame), text under 14 px on the frame, text under 3:1 contrast against what is behind it, motion hitches (a speed that jumps or a path that turns a corner mid-move). Fix what is flagged unless it is a deliberate choice you can name.",
+      inputSchema: { properties: { times: { items: { type: "number" }, type: "array" }, width: { type: "number" } }, type: "object" },
+      name: "review_sheet",
+      run: async ({ times, width }) => {
+        const review = await tab.call("review", { ...(times ? { times } : {}), ...(width ? { width } : {}) });
+
+        if (!review) {
+          return "No editor.";
+        }
+
+        const { sheet, ...facts } = review;
+
+        return [...imageContent(sheet, "The frames, left to right, top to bottom."), { text: JSON.stringify(facts, null, 2), type: "text" }];
+      },
+    },
+    {
+      description:
+        "The piece on every review artboard (9:16, 4:5, 1:1, 16:9) as Responsive lays it out, at `times`: what each artboard did, what its frame cuts, the smallest type and type at the edge, with all the frames as one picture.",
+      inputSchema: { properties: { times: { items: { type: "number" }, type: "array" } }, type: "object" },
+      name: "review_artboards",
+      run: async ({ times }) => {
+        const scene = await tab.call("scene");
+        const moments = times?.length ? times : [0.25, 0.5, 0.9].map((share) => Number(((scene?.durationSeconds ?? 8) * share).toFixed(2)));
+        const review = await tab.call("reviewArtboards", { times: moments });
+
+        if (!review) {
+          return "No editor.";
+        }
+
+        return [...imageContent(review.sheet, "Each artboard at each time."), { text: JSON.stringify(review.reviews, null, 2), type: "text" }];
+      },
+    },
+    {
+      description: "The person's projects, newest first: those in this browser and, when the tab is signed in, those kept in their account (in the cloud), each with its id, name, when it changed, and which one is open.",
+      name: "list_projects",
+      run: () => tab.call("projects"),
+    },
+    {
+      description: "Open one of the person's projects by id (list_projects), as the editor opens it: the scene being left is saved first; a project kept only in the account is fetched. Answers with its name and its scene.",
+      inputSchema: { properties: { id: { type: "string" } }, required: ["id"], type: "object" },
+      name: "open_project",
+      run: ({ id }) => tab.call("openProject", { id }),
+    },
+    {
+      description: "Design systems the person can apply: Paraplex's and their own (made, imported or installed), each with what it holds (colors, text styles, materials, looks, fonts), and the one the scene follows now.",
+      name: "list_design_systems",
+      run: () => tab.call("designSystems"),
+    },
+    {
+      description: "Apply a design system by id or name, as Use in project does: its colors, text styles, materials, looks and fonts merged into the scene, which then follows it. One undo step. Then build with its tokens (run_tool get_brand reads them).",
+      inputSchema: { properties: { id: { type: "string" } }, required: ["id"], type: "object" },
+      name: "apply_design_system",
+      run: ({ id }) => tab.call("applyDesignSystem", { id }),
+    },
+    {
+      description: "The person's skills and Paraplex's (Agent Skills: instructions and reference files), each with its description and whether it is on. Read one with load_skill when a task matches it.",
+      name: "list_skills",
+      run: () => tab.call("skills"),
+    },
+    {
+      description: "A skill's instructions (its SKILL.md body) and the files inside it, by name. Read it before doing the work it describes.",
+      inputSchema: { properties: { name: { type: "string" } }, required: ["name"], type: "object" },
+      name: "load_skill",
+      run: async ({ name }) => (await tab.call("loadSkill", { name })).content,
+    },
+    {
+      description: "One file inside a skill — a reference, a template, a checklist — by the path load_skill listed.",
+      inputSchema: { properties: { name: { type: "string" }, path: { type: "string" } }, required: ["name", "path"], type: "object" },
+      name: "read_skill_file",
+      run: async ({ name, path }) => (await tab.call("readSkillFile", { name, path })).content,
+    },
+    {
+      description: "Write a skill's SKILL.md into the person's library: the whole file, frontmatter (name, description) then instructions. Rewrites the named skill's SKILL.md and keeps its reference files, or creates it. Paraplex's own skills are not rewritten.",
+      inputSchema: { properties: { markdown: { type: "string" }, name: { type: "string" } }, required: ["name", "markdown"], type: "object" },
+      name: "write_skill",
+      run: ({ markdown, name }) => tab.call("writeSkill", { markdown, name }),
+    },
     {
       description: "Save the open scene as a project of that browser's, by name.",
       inputSchema: { properties: { name: { type: "string" } }, required: ["name"], type: "object" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paraplex-mcp",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "mcpName": "ai.paraplex/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": [

package/skills/paraplex/SKILL.md

@@ -56,15 +56,35 @@ what you changed after each step; never clear their scene without asking.
 
 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
+camera). `review_sheet` does the checking for you: the frames as one sheet
+and the flags — anything past the frame, type under 14 px, contrast under
+3:1, motion hitches; `review_artboards` shows the piece on 9:16, 4:5, 1:1
+and 16:9. Check frame fit (nothing the piece is about half out of frame at
+a hold), type, motion (one ease per move, holds long enough to read) — fix
+what you see, then look again. `undo` takes back a step that went wrong.
+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.
 
+## Their library
+
+- Files from this computer: `import_file` with a path (a picture, video,
+  sound, model, Lottie, Figma frames, SVG or font), optionally onto a
+  layer by id. Read the layers it says it added.
+- Their projects: `list_projects`, `open_project` (ask before leaving a
+  scene they are working on), `save_project`.
+- A brand: `list_design_systems`, `apply_design_system` by name.
+- The assistant's skills: `list_skills`, `load_skill` before a kind of
+  piece a skill covers; `write_skill` saves one to their library.
+
 ## 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.
+`export` writes the file (in `./paraplex-exports`, where the server was
+started) and says where; pass only the options the person asked for —
+`kind`, `format` (png, jpg, mp4, webm, gif, png-sequence), `scale`, `fps`,
+`inSeconds`/`outSeconds`, `background: false` for transparency, `artboard`
+(a name, or `all`), `deliver` (app-store, keynote, powerpoint,
+google-slides). Their own Export settings stay as they were; a Pro-only
+export on Free comes back with the reason, as the Export button gives it.
+`render_variants` makes a file per row of data. `export_png` returns a
+still to look at.