infiniteboard-mcp 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,16 @@
-# Temporary Holding Version
+# infiniteboard-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.
+Lets AI assistants (Claude Code, Claude Desktop, Cursor, VS Code, or any MCP client) read and draw on your open Infiniteboard whiteboard.
+
+1. Open the board and click **AI** in the top bar. The board starts waiting for your assistant.
+2. Add this MCP server to your assistant. The dialog shows the exact steps for each app. The command is:
+
+   ```bash
+   npx -y infiniteboard-mcp
+   ```
+
+3. Ask away: *"Sketch a user-signup flowchart on my board"*.
+
+The server runs on your machine. The board tab connects to it over `ws://127.0.0.1:3917` only while its AI switch is on.
+
+Options: `--port <n>` (open the board with `?mcp=<n>` to match) and `--allow-origin <url>` for a hosted board other than localhost. Requires Node.js 18+.

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "infiniteboard-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Let AI assistants (Claude, Cursor, VS Code, any MCP client) draw on your open Infiniteboard whiteboard",
+  "type": "module",
+  "bin": {
+    "infiniteboard-mcp": "server.mjs"
+  },
+  "scripts": {
+    "start": "node server.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "ws": "8.22.0",
+    "zod": "4.6.7"
+  },
+  "files": [
+    "server.mjs",
+    "tools.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "whiteboard",
+    "claude",
+    "ai"
+  ],
+  "license": "Apache-2.0",
+  "author": "Isaiah Isayev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/isaiahoo/infiniteboard.git",
+    "directory": "mcp"
+  },
+  "homepage": "https://github.com/isaiahoo/infiniteboard/tree/main/mcp",
+  "bugs": {
+    "url": "https://github.com/isaiahoo/infiniteboard/issues"
+  }
+}

package/server.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+// MCP server for the whiteboard. AI assistants talk to it over stdio; it relays each tool call
+// to the open whiteboard tab, which connects to a loopback WebSocket once the user enables
+// "Let a local AI assistant edit this board" in the menu.
+//
+// Options (flags or env):
+//   --port <n>            | WHITEBOARD_BRIDGE_PORT      WebSocket port (default 3917; the page uses ?mcp=<port> to match)
+//   --allow-origin <url>  | WHITEBOARD_ALLOWED_ORIGINS  extra page origins allowed to connect (repeatable / comma-separated);
+//                                                       localhost and 127.0.0.1 are always allowed
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { WebSocketServer } from "ws";
+import { INSTRUCTIONS, registerBoardTools } from "./tools.mjs";
+
+const argv = process.argv.slice(2);
+const flag = (name) => argv.flatMap((a, i) => (a === name && argv[i + 1] ? [argv[i + 1]] : a.startsWith(`${name}=`) ? [a.slice(name.length + 1)] : []));
+const PORT = Number(flag("--port")[0] ?? process.env.WHITEBOARD_BRIDGE_PORT) || 3917;
+const EXTRA_ORIGINS = [...flag("--allow-origin"), ...(process.env.WHITEBOARD_ALLOWED_ORIGINS ?? "").split(",")]
+  .map((s) => s.trim().replace(/\/$/, ""))
+  .filter(Boolean);
+const log = (...args) => console.error("[whiteboard-mcp]", ...args); // stdout is reserved for MCP
+
+function originAllowed(origin) {
+  if (!origin) return false;
+  try {
+    const u = new URL(origin);
+    if (["localhost", "127.0.0.1", "[::1]"].includes(u.hostname)) return true;
+  } catch {
+    return false;
+  }
+  return EXTRA_ORIGINS.includes(origin);
+}
+
+// ---------- bridge to the board tab ----------
+
+let board = null;
+let bridgeError = null;
+let seq = 0;
+const pending = new Map();
+
+const wss = new WebSocketServer({
+  host: "127.0.0.1",
+  port: PORT,
+  maxPayload: 32 * 1024 * 1024,
+  verifyClient: ({ origin }) => {
+    const ok = originAllowed(origin);
+    if (!ok) log(`rejected connection from origin ${origin ?? "(none)"}; start the server with --allow-origin ${origin} to allow it`);
+    return ok;
+  },
+});
+wss.on("listening", () => log(`waiting for the whiteboard on ws://127.0.0.1:${PORT}`));
+wss.on("error", (e) => {
+  bridgeError = e.code === "EADDRINUSE" ? `Port ${PORT} is already in use (is another whiteboard MCP server running?)` : String(e.message ?? e);
+  log(bridgeError);
+});
+wss.on("connection", (ws) => {
+  // Newest tab wins; code 4000 tells the old tab to stop reconnecting instead of fighting for the slot.
+  if (board && board !== ws) board.close(4000, "Another board tab connected");
+  board = ws;
+  log("board connected");
+  ws.on("message", (data) => {
+    let msg;
+    try {
+      msg = JSON.parse(String(data));
+    } catch {
+      return;
+    }
+    if (msg.type === "hello") return log(`board: "${msg.title}"`);
+    const p = pending.get(msg.id);
+    if (!p) return;
+    pending.delete(msg.id);
+    clearTimeout(p.timer);
+    if (msg.error) p.reject(new Error(msg.error));
+    else p.resolve(msg.result);
+  });
+  ws.on("close", () => {
+    if (board === ws) board = null;
+    log("board disconnected");
+  });
+});
+
+function call(method, params = {}) {
+  if (bridgeError) return Promise.reject(new Error(bridgeError));
+  if (!board || board.readyState !== board.OPEN) {
+    return Promise.reject(new Error(
+      "No whiteboard is connected. Ask the user to open the whiteboard and click the AI button in its top bar.",
+    ));
+  }
+  const id = ++seq;
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      pending.delete(id);
+      reject(new Error(`The board did not answer "${method}" within 20s`));
+    }, 20000);
+    pending.set(id, { resolve, reject, timer });
+    board.send(JSON.stringify({ id, method, params }));
+  });
+}
+
+// ---------- MCP server ----------
+
+const server = new McpServer({ name: "infiniteboard", version: "0.2.0" }, { instructions: INSTRUCTIONS });
+registerBoardTools(server, call);
+await server.connect(new StdioServerTransport());
+log("MCP server ready on stdio");
+
+const shutdown = () => {
+  wss.close();
+  process.exit(0);
+};
+process.stdin.on("close", shutdown);
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);

package/tools.mjs

@@ -0,0 +1,138 @@
+// Board tools shared by the local stdio server (server.mjs) and the hosted endpoint (api/mcp.js).
+// `call(method, params)` delivers one command to the open board tab and resolves with its result.
+import { z } from "zod";
+
+export const INSTRUCTIONS = [
+  "Tools for reading and editing the user's open whiteboard (an infinite canvas).",
+  "Coordinates are world units: 1 unit = 1 px at 100% zoom, x grows right, y grows down. Elements have x/y (top-left) and w/h.",
+  "Typical sizes: sticky 180×180, shape 160×110, frame 800×500, text 20px font. Leave ~40–80 units between items.",
+  "Start with get_board to see what exists; omit x/y when creating to place items in free space to the right of existing content.",
+  "Connectors attach to elements via from/to (ids, or refs defined earlier in the same create_elements call) and follow them when they move.",
+  "Each create/update/delete call is one undo step for the user. Use get_screenshot to check the visual result.",
+].join(" ");
+
+const asText = (value) => ({ content: [{ type: "text", text: JSON.stringify(value, null, 1) }] });
+const asError = (e) => ({ isError: true, content: [{ type: "text", text: e instanceof Error ? e.message : String(e) }] });
+const relayVia = (call) => (method) => async (params) => {
+  try {
+    return asText(await call(method, params));
+  } catch (e) {
+    return asError(e);
+  }
+};
+
+/**
+ * @param {import("@modelcontextprotocol/sdk/server/mcp.js").McpServer} server
+ * @param {(method: string, params?: object) => Promise<any>} call
+ */
+export function registerBoardTools(server, call) {
+  const relay = relayVia(call);
+  const color = z.string().describe("Hex colour (#rrggbb) or a name: yellow, orange, pink, purple, blue, green, lime, gray, white, black, red, darkblue, darkgreen");
+  const point = z.tuple([z.number(), z.number()]);
+  const common = {
+    x: z.number().optional().describe("Left edge (world units). Omit x and y to auto-place in free space"),
+    y: z.number().optional().describe("Top edge (world units)"),
+    w: z.number().positive().optional(),
+    h: z.number().positive().optional(),
+    text: z.string().optional().describe("Text for sticky, shape and text elements (plain text, \\n for new lines)"),
+    title: z.string().optional().describe("Frame title"),
+    color: color.optional().describe("Sticky/frame: background. Text/shape: text colour. Connector/stroke: line colour"),
+    fill: z.string().optional().describe('Shape fill colour, or "none"'),
+    stroke: color.optional().describe("Shape border colour"),
+    kind: z.enum(["rect", "roundrect", "ellipse", "diamond", "triangle"]).optional().describe("Shape kind (default rect)"),
+    fontSize: z.number().positive().optional(),
+    align: z.enum(["left", "center", "right"]).optional(),
+    bold: z.boolean().optional(),
+    angle: z.number().optional().describe("Rotation in degrees, clockwise"),
+    from: z.string().optional().describe("Connector start: element id or ref"),
+    to: z.string().optional().describe("Connector end: element id or ref"),
+    fromPoint: point.optional().describe("Connector start as [x, y] when not attached"),
+    toPoint: point.optional().describe("Connector end as [x, y] when not attached"),
+    route: z.enum(["straight", "elbow", "curved"]).optional(),
+    label: z.string().optional().describe("Connector label"),
+    endHead: z.enum(["none", "open", "filled"]).optional(),
+    startHead: z.enum(["none", "open", "filled"]).optional(),
+    dash: z.enum(["solid", "dashed", "dotted"]).optional(),
+  };
+
+  server.registerTool("get_board", {
+    title: "Read the board",
+    description: "Lists the board's elements (id, type, position, size, text, colours, frame membership, connector endpoints), the visible viewport, content bounds and current selection.",
+    inputSchema: {
+      type: z.enum(["sticky", "shape", "text", "frame", "connector", "stroke", "image"]).optional().describe("Only list this element type"),
+      limit: z.number().int().positive().max(5000).optional().describe("Maximum elements to return (default 500)"),
+    },
+    annotations: { readOnlyHint: true },
+  }, relay("get_board"));
+
+  server.registerTool("create_elements", {
+    title: "Create elements",
+    description:
+      "Creates sticky notes, shapes, text, frames, connectors and pen strokes in one undoable step. " +
+      "Give elements a `ref` to connect them in the same call, e.g. [{type:'sticky',ref:'a',text:'Idea'},{type:'sticky',ref:'b',text:'Plan'},{type:'connector',from:'a',to:'b'}]. " +
+      "Elements placed at least half inside a frame automatically belong to it. Returns the new ids.",
+    inputSchema: {
+      elements: z.array(z.object({
+        type: z.enum(["sticky", "shape", "text", "frame", "connector", "stroke"]),
+        ref: z.string().optional().describe("Your own key for referring to this element later in the same call"),
+        ...common,
+        points: z.array(point).optional().describe("Stroke points [[x, y], …] in world units"),
+        width: z.number().positive().optional().describe("Stroke width"),
+      })).min(1).max(500),
+    },
+  }, relay("create_elements"));
+
+  server.registerTool("update_elements", {
+    title: "Update elements",
+    description: "Moves, resizes, recolours, retexts or rewires existing elements (one undoable step). Only the fields you pass change. Set locked to stop the user moving an element.",
+    inputSchema: {
+      updates: z.array(z.object({ id: z.string(), ...common, locked: z.boolean().optional() })).min(1).max(1000),
+    },
+  }, relay("update_elements"));
+
+  server.registerTool("delete_elements", {
+    title: "Delete elements",
+    description: "Deletes elements by id (deleting a frame deletes its contents). Pass all: true to clear the board. One undoable step.",
+    inputSchema: {
+      ids: z.array(z.string()).optional(),
+      all: z.boolean().optional().describe("Delete everything on the board"),
+    },
+    annotations: { destructiveHint: true },
+  }, relay("delete_elements"));
+
+  server.registerTool("focus_view", {
+    title: "Move the view",
+    description: "Pans/zooms the user's view: fit the given element ids, centre on x/y (optionally at a zoom), set a zoom level, or with no arguments fit the whole board.",
+    inputSchema: {
+      ids: z.array(z.string()).optional(),
+      x: z.number().optional(),
+      y: z.number().optional(),
+      zoom: z.number().positive().max(8).optional().describe("1 = 100%"),
+    },
+  }, relay("focus_view"));
+
+  server.registerTool("select_elements", {
+    title: "Select elements",
+    description: "Highlights elements for the user by selecting them (empty list clears the selection).",
+    inputSchema: { ids: z.array(z.string()) },
+  }, relay("select"));
+
+  server.registerTool("undo", { title: "Undo", description: "Undoes the last change on the board (the user's or the assistant's).", inputSchema: {} }, relay("undo"));
+  server.registerTool("redo", { title: "Redo", description: "Redoes the last undone change.", inputSchema: {} }, relay("redo"));
+
+  server.registerTool("get_screenshot", {
+    title: "Screenshot the board",
+    description: "Returns a PNG of what the user currently sees. Use focus_view first to frame the area you want to check.",
+    inputSchema: { maxWidth: z.number().int().min(200).max(2400).optional().describe("Maximum image width in pixels (default 1280)") },
+    annotations: { readOnlyHint: true },
+  }, async (params) => {
+    try {
+      const { image } = await call("screenshot", params);
+      const m = /^data:(image\/\w+);base64,(.*)$/s.exec(image ?? "");
+      if (!m) throw new Error("The board returned no image");
+      return { content: [{ type: "image", mimeType: m[1], data: m[2] }] };
+    } catch (e) {
+      return asError(e);
+    }
+  });
+}