@todrawn/scribe-mcp 0.0.0-stage → 0.1.0

package/dist/server.js

@@ -0,0 +1,260 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { ASPECTS, BACKGROUNDS, COLOR_MODES, FRAME_RATES, FREE_EXPORTS_PER_DAY, LANGUAGES, LAYOUTS, LOCALE_PATH_PREFIXES, MAX_INPUT_BYTES, MAX_LINES, MAX_PLAYBACK_SECONDS, DRAW_COLOR_KEYS, PENS, READING_WPS, RESOLUTIONS, SPEED, TIMINGS, } from "./constants.js";
+import { resolve } from "node:path";
+import { buildDrawingLink } from "./drawing.js";
+import { readImage } from "./image.js";
+import { paintToLink } from "./paint.js";
+import { buildRecipeLink, LinkError } from "./link.js";
+export const SERVER_VERSION = "0.1.0";
+const MAX_DRAWING_PATHS = 2000;
+const EXPORT_RULES = `Previewing is free and needs no account. Exporting the MP4 needs a free Todrawn account: ` +
+    `the Free plan allows ${FREE_EXPORTS_PER_DAY} exports per UTC day and ends each video with a "Made with Todrawn Scribe" card; ` +
+    `Premium has unlimited exports and makes the card optional.`;
+const LIMITS_TEXT = [
+    "Todrawn Scribe limits:",
+    `- Input: up to ${MAX_INPUT_BYTES} bytes (1 MiB) and ${MAX_LINES} lines of text or code.`,
+    `- Playback: clips are capped at ${MAX_PLAYBACK_SECONDS} s; longer documents are drawn faster to fit. A readable clip is a few dozen lines.`,
+    `- Output: ${RESOLUTIONS.join(" or ")}, ${FRAME_RATES.join(" or ")} fps, aspects ${ASPECTS.join(", ")} (feed = 4:5).`,
+    `- Languages with syntax colours: ${LANGUAGES.filter((l) => l !== "plain").join(", ")}; "plain" draws prose and supports a Markdown subset (headings, **bold**, lists, ==highlight==).`,
+    `- ${EXPORT_RULES}`,
+    `- Drawings: SVG path data, drawn as pen lines in path order (fills are ignored); inks ${DRAW_COLOR_KEYS.join(", ")} or #rrggbb.`,
+    "- Photos: PNG or JPEG, painted locally into up to ~2800 strokes; the image itself is never uploaded.",
+    "- This server only builds links; the video is rendered and exported in the person's browser.",
+].join("\n");
+const createVideoShape = {
+    text: z.string().min(1).describe("The code or text to draw, exactly as it should appear."),
+    language: z
+        .string()
+        .optional()
+        .describe(`Syntax colouring: ${LANGUAGES.join(", ")}. Common names (typescript, python, c++, shell, markdown) are accepted. Defaults to plain.`),
+    aspect: z
+        .enum(ASPECTS)
+        .optional()
+        .describe("landscape 16:9 (default), portrait 9:16 for Shorts/Reels/TikTok, square 1:1, feed 4:5."),
+    background: z.enum(BACKGROUNDS).optional().describe("dark board or light paper."),
+    pen: z.enum(PENS).optional(),
+    colorMode: z.enum(COLOR_MODES).optional().describe("syntax colours per token, or one solid ink colour."),
+    solidColor: z
+        .string()
+        .regex(/^#[0-9a-fA-F]{6}$/)
+        .optional()
+        .describe("Ink colour as #rrggbb when colorMode is solid."),
+    timing: z.enum(TIMINGS).optional().describe("reading: paced by words per second (default); pen: paced by pen travel."),
+    readingWps: z
+        .number()
+        .min(READING_WPS.min)
+        .max(READING_WPS.max)
+        .multipleOf(READING_WPS.step)
+        .optional()
+        .describe("Words per second when timing is reading."),
+    speedMultiplier: z.number().min(SPEED.min).max(SPEED.max).optional(),
+    markdown: z.boolean().optional().describe("Interpret Markdown in plain text (default true)."),
+    layout: z.enum(LAYOUTS).optional().describe("auto scrolls tall aspects and pages wide ones."),
+    resolution: z.enum(RESOLUTIONS).optional(),
+    fps: z.union([z.literal(24), z.literal(30)]).optional(),
+    locale: z
+        .enum(Object.keys(LOCALE_PATH_PREFIXES))
+        .optional()
+        .describe("Language of the Scribe interface the link opens. Defaults to en."),
+};
+const SETTING_KEYS = [
+    "background",
+    "pen",
+    "colorMode",
+    "solidColor",
+    "timing",
+    "readingWps",
+    "speedMultiplier",
+    "markdown",
+    "layout",
+    "resolution",
+    "fps",
+];
+const localeSchema = createVideoShape.locale;
+const createDrawingShape = {
+    paths: z
+        .array(z.object({
+        d: z.string().min(1).describe("SVG path data. Curves (C, Q, A) are fine; fills are ignored, every path is drawn as a pen line."),
+        color: z
+            .string()
+            .optional()
+            .describe(`Ink: ${DRAW_COLOR_KEYS.join(", ")} (adapt to the background) or #rrggbb. Defaults to blue.`),
+    }))
+        .min(1)
+        .max(MAX_DRAWING_PATHS)
+        .describe("Paths in the order a person would draw them; the pen follows that order. y grows downward, as in SVG."),
+    viewBox: z
+        .string()
+        .optional()
+        .describe('"minX minY width height" framing the drawing, as on an <svg>. Defaults to the paths\' bounding box with a margin.'),
+    aspect: z
+        .enum(ASPECTS)
+        .optional()
+        .describe("Artboard: landscape 16:9, portrait 9:16, square 1:1, feed 4:5. Defaults to the one closest to the drawing's shape."),
+    background: createVideoShape.background,
+    pen: createVideoShape.pen,
+    speedMultiplier: createVideoShape.speedMultiplier,
+    resolution: createVideoShape.resolution,
+    fps: createVideoShape.fps,
+    locale: localeSchema,
+};
+const paintImageShape = {
+    imagePath: z.string().min(1).describe("Path to a local PNG or JPEG file. Relative paths resolve against the server's working directory."),
+    aspect: z
+        .enum(ASPECTS)
+        .optional()
+        .describe("Artboard: landscape 16:9, portrait 9:16, square 1:1, feed 4:5. Defaults to the one closest to the image's shape."),
+    detail: z
+        .enum(["low", "medium", "high"])
+        .optional()
+        .describe("Stroke budget: low ~1200 strokes, medium ~2000 (default), high ~2800. More detail is more faithful and plays longer."),
+    pen: createVideoShape.pen.describe("Pen width shapes the painting: fineliner (default) is the finest, marker the boldest."),
+    background: createVideoShape.background,
+    speedMultiplier: createVideoShape.speedMultiplier,
+    locale: localeSchema,
+};
+export function createScribeServer(options = {}) {
+    const server = new McpServer({ name: "todrawn-scribe", version: SERVER_VERSION });
+    server.registerTool("scribe_create_video", {
+        title: "Create a Todrawn Scribe video",
+        description: "Turns code or text into a Todrawn Scribe project: a video of a pen writing it out by hand. " +
+            "Returns a link that opens the Scribe studio with the project loaded, where the person previews it and exports the MP4. " +
+            "Give the link to the person; do not try to download a video from it. " +
+            EXPORT_RULES,
+        inputSchema: createVideoShape,
+        annotations: { readOnlyHint: true, openWorldHint: false, idempotentHint: true },
+    }, async (args) => {
+        const settings = {};
+        for (const key of SETTING_KEYS) {
+            if (args[key] !== undefined)
+                settings[key] = args[key];
+        }
+        try {
+            const link = buildRecipeLink({
+                text: args.text,
+                language: args.language,
+                aspect: args.aspect,
+                settings,
+                locale: args.locale,
+                baseUrl: options.baseUrl,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `Open this link to preview and export the video in Todrawn Scribe:`,
+                            link.url,
+                            "",
+                            `Language: ${link.language}, ${link.lines} line${link.lines === 1 ? "" : "s"}. The whole project is inside the link after "#", so nothing was uploaded.`,
+                            `Clips are capped at ${MAX_PLAYBACK_SECONDS} s; longer text is drawn faster to fit.`,
+                            EXPORT_RULES,
+                        ].join("\n"),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            if (error instanceof LinkError) {
+                return { isError: true, content: [{ type: "text", text: error.message }] };
+            }
+            throw error;
+        }
+    });
+    server.registerTool("scribe_create_drawing", {
+        title: "Create a Todrawn Scribe drawing video",
+        description: "Turns a line drawing, given as SVG paths, into a Todrawn Scribe Draw project: a video of a pen drawing it stroke by stroke. " +
+            "Describe the subject as outlines and details, not filled shapes. " +
+            "Returns a link that opens the Scribe studio with the drawing loaded, where the person previews it and exports the MP4. " +
+            EXPORT_RULES,
+        inputSchema: createDrawingShape,
+        annotations: { readOnlyHint: true, openWorldHint: false, idempotentHint: true },
+    }, async (args) => {
+        try {
+            const link = buildDrawingLink({
+                paths: args.paths,
+                viewBox: args.viewBox,
+                aspect: args.aspect,
+                settings: {
+                    background: args.background,
+                    pen: args.pen,
+                    speedMultiplier: args.speedMultiplier,
+                    resolution: args.resolution,
+                    fps: args.fps,
+                },
+                locale: args.locale,
+                baseUrl: options.baseUrl,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            "Open this link to preview and export the drawing in Todrawn Scribe:",
+                            link.url,
+                            "",
+                            `Artboard: ${link.aspect}, ${link.strokes} stroke${link.strokes === 1 ? "" : "s"}, ${link.points} points. The whole drawing is inside the link after "#", so nothing was uploaded.`,
+                            EXPORT_RULES,
+                        ].join("\n"),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            if (error instanceof LinkError) {
+                return { isError: true, content: [{ type: "text", text: error.message }] };
+            }
+            throw error;
+        }
+    });
+    server.registerTool("scribe_paint_image", {
+        title: "Paint a photo with Todrawn Scribe",
+        description: "Paints a local photo or picture (PNG or JPEG) as a Todrawn Scribe drawing: an underpaint first, then thousands of coloured pen strokes, " +
+            "replayed by the pen as a video. The image is processed on this machine and never uploaded; the returned link carries only the strokes. " +
+            `Long paintings are capped at ${MAX_PLAYBACK_SECONDS} s of playback. ` +
+            EXPORT_RULES,
+        inputSchema: paintImageShape,
+        annotations: { readOnlyHint: true, openWorldHint: false, idempotentHint: true },
+    }, async (args) => {
+        try {
+            const image = await readImage(resolve(args.imagePath));
+            const link = paintToLink(image, {
+                aspect: args.aspect,
+                detail: args.detail,
+                pen: args.pen,
+                background: args.background,
+                speedMultiplier: args.speedMultiplier,
+                locale: args.locale,
+                baseUrl: options.baseUrl,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            "Open this link to watch the painting and export it in Todrawn Scribe:",
+                            link.url,
+                            "",
+                            `Artboard: ${link.aspect}, ${link.strokes} strokes${link.trimmed ? ` (${link.trimmed} finest strokes left out to fit the link)` : ""}. ` +
+                                "The photo was painted locally; only the strokes are in the link, after \"#\", so nothing was uploaded.",
+                            EXPORT_RULES,
+                        ].join("\n"),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            if (error instanceof LinkError) {
+                return { isError: true, content: [{ type: "text", text: error.message }] };
+            }
+            throw error;
+        }
+    });
+    server.registerTool("scribe_limits", {
+        title: "Todrawn Scribe limits",
+        description: "Lists what Todrawn Scribe accepts and what the Free and Premium plans allow, before building a video.",
+        annotations: { readOnlyHint: true, openWorldHint: false, idempotentHint: true },
+    }, async () => ({ content: [{ type: "text", text: LIMITS_TEXT }] }));
+    return server;
+}

package/dist/svg-path.js

@@ -0,0 +1,238 @@
+/* SVG path data -> polylines. Agents describe drawings most reliably as SVG
+   paths, while a Scribe drawing is a list of pen polylines, so every curve is
+   flattened here. Supports the full path grammar: M L H V C S Q T A Z, both
+   absolute and relative, implicit command repetition and packed arc flags. */
+export class PathError extends Error {
+}
+const COMMAND_ARITY = { M: 2, L: 2, H: 1, V: 1, C: 6, S: 4, Q: 4, T: 2, A: 7, Z: 0 };
+const NUMBER = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?/;
+function tokenize(d) {
+    const tokens = [];
+    let i = 0;
+    // arc flags may be packed ("a1 1 0 01-1 1"), so the tokenizer tracks the
+    // argument index inside the current arc to read 0/1 flags as single digits
+    let cmd = "";
+    let argIndex = 0;
+    while (i < d.length) {
+        const ch = d[i];
+        if (/[\s,]/.test(ch)) {
+            i++;
+            continue;
+        }
+        if (/[MLHVCSQTAZmlhvcsqtaz]/.test(ch)) {
+            tokens.push({ cmd: ch });
+            cmd = ch.toUpperCase();
+            argIndex = 0;
+            i++;
+            continue;
+        }
+        const arity = COMMAND_ARITY[cmd] ?? 0;
+        const slot = arity > 0 ? argIndex % arity : 0;
+        if (cmd === "A" && (slot === 3 || slot === 4) && (ch === "0" || ch === "1")) {
+            tokens.push({ num: ch === "1" ? 1 : 0 });
+            argIndex++;
+            i++;
+            continue;
+        }
+        const match = NUMBER.exec(d.slice(i));
+        if (!match)
+            throw new PathError(`Unexpected "${ch}" at position ${i} in path data.`);
+        tokens.push({ num: Number(match[0]) });
+        argIndex++;
+        i += match[0].length;
+    }
+    return tokens;
+}
+/** Number of straight segments for a curve of the given control-polygon length. */
+function steps(length, tolerance) {
+    return Math.min(256, Math.max(4, Math.ceil(length / tolerance)));
+}
+function dist(a, b) {
+    return Math.hypot(b[0] - a[0], b[1] - a[1]);
+}
+/** Endpoint-parameterised SVG arc (spec F.6.5) flattened to points after `from`. */
+function arcPoints(from, rxIn, ryIn, rotationDeg, largeArc, sweep, to, tolerance) {
+    let rx = Math.abs(rxIn);
+    let ry = Math.abs(ryIn);
+    if (rx === 0 || ry === 0 || (from[0] === to[0] && from[1] === to[1]))
+        return [to];
+    const phi = (rotationDeg * Math.PI) / 180;
+    const cos = Math.cos(phi);
+    const sin = Math.sin(phi);
+    const dx = (from[0] - to[0]) / 2;
+    const dy = (from[1] - to[1]) / 2;
+    const x1 = cos * dx + sin * dy;
+    const y1 = -sin * dx + cos * dy;
+    const lambda = (x1 * x1) / (rx * rx) + (y1 * y1) / (ry * ry);
+    if (lambda > 1) {
+        rx *= Math.sqrt(lambda);
+        ry *= Math.sqrt(lambda);
+    }
+    const num = rx * rx * ry * ry - rx * rx * y1 * y1 - ry * ry * x1 * x1;
+    const den = rx * rx * y1 * y1 + ry * ry * x1 * x1;
+    const coef = (largeArc === sweep ? -1 : 1) * Math.sqrt(Math.max(0, num / den));
+    const cx1 = (coef * rx * y1) / ry;
+    const cy1 = (-coef * ry * x1) / rx;
+    const cx = cos * cx1 - sin * cy1 + (from[0] + to[0]) / 2;
+    const cy = sin * cx1 + cos * cy1 + (from[1] + to[1]) / 2;
+    const angle = (ux, uy, vx, vy) => Math.atan2(ux * vy - uy * vx, ux * vx + uy * vy);
+    const theta1 = angle(1, 0, (x1 - cx1) / rx, (y1 - cy1) / ry);
+    let delta = angle((x1 - cx1) / rx, (y1 - cy1) / ry, (-x1 - cx1) / rx, (-y1 - cy1) / ry);
+    if (!sweep && delta > 0)
+        delta -= 2 * Math.PI;
+    if (sweep && delta < 0)
+        delta += 2 * Math.PI;
+    const n = steps(Math.abs(delta) * Math.max(rx, ry), tolerance);
+    const out = [];
+    for (let k = 1; k <= n; k++) {
+        const t = theta1 + (delta * k) / n;
+        const ex = rx * Math.cos(t);
+        const ey = ry * Math.sin(t);
+        out.push([cos * ex - sin * ey + cx, sin * ex + cos * ey + cy]);
+    }
+    out[out.length - 1] = to;
+    return out;
+}
+/**
+ * Parses path data into polylines, one per subpath. `tolerance` is the target
+ * length of one flattened curve segment, in the path's own units.
+ */
+export function pathToPolylines(d, tolerance) {
+    const tokens = tokenize(d);
+    const lines = [];
+    let line = [];
+    let cur = [0, 0];
+    let start = [0, 0];
+    let lastCubic = null;
+    let lastQuad = null;
+    let i = 0;
+    let cmd = "";
+    const take = (n) => {
+        const out = [];
+        for (let k = 0; k < n; k++) {
+            const token = tokens[i++];
+            if (!token || !("num" in token))
+                throw new PathError(`Command "${cmd}" is missing arguments.`);
+            out.push(token.num);
+        }
+        return out;
+    };
+    const flush = () => {
+        if (line.length > 1)
+            lines.push(line);
+        line = [];
+    };
+    const lineTo = (p) => {
+        if (line.length === 0)
+            line.push(cur);
+        line.push(p);
+        cur = p;
+    };
+    while (i < tokens.length) {
+        const token = tokens[i];
+        if ("cmd" in token) {
+            cmd = token.cmd;
+            i++;
+        }
+        else if (!cmd) {
+            throw new PathError("Path data must start with a command such as M.");
+        }
+        if (cmd.toUpperCase() === "Z") {
+            if (line.length > 0)
+                lineTo(start);
+            flush();
+            cur = start;
+            lastCubic = lastQuad = null;
+            continue;
+        }
+        const arity = COMMAND_ARITY[cmd.toUpperCase()];
+        if (arity === undefined)
+            throw new PathError(`Unknown command "${cmd}".`);
+        // a command letter followed by no numbers is an error, except Z handled above
+        if (i >= tokens.length || "cmd" in tokens[i])
+            throw new PathError(`Command "${cmd}" is missing arguments.`);
+        do {
+            // recomputed per repetition: extra pairs after M continue as L
+            const upper = cmd.toUpperCase();
+            const rel = cmd !== upper;
+            const at = (x, y) => (rel ? [cur[0] + x, cur[1] + y] : [x, y]);
+            const a = take(arity);
+            let nextCubic = null;
+            let nextQuad = null;
+            switch (upper) {
+                case "M": {
+                    flush();
+                    cur = at(a[0], a[1]);
+                    start = cur;
+                    // further pairs after M are implicit L
+                    cmd = rel ? "l" : "L";
+                    break;
+                }
+                case "L":
+                    lineTo(at(a[0], a[1]));
+                    break;
+                case "H":
+                    lineTo([rel ? cur[0] + a[0] : a[0], cur[1]]);
+                    break;
+                case "V":
+                    lineTo([cur[0], rel ? cur[1] + a[0] : a[0]]);
+                    break;
+                case "C":
+                case "S": {
+                    const p0 = cur;
+                    const p1 = upper === "C"
+                        ? at(a[0], a[1])
+                        : lastCubic
+                            ? [2 * p0[0] - lastCubic[0], 2 * p0[1] - lastCubic[1]]
+                            : p0;
+                    const p2 = upper === "C" ? at(a[2], a[3]) : at(a[0], a[1]);
+                    const p3 = upper === "C" ? at(a[4], a[5]) : at(a[2], a[3]);
+                    const n = steps(dist(p0, p1) + dist(p1, p2) + dist(p2, p3), tolerance);
+                    for (let k = 1; k <= n; k++) {
+                        const t = k / n;
+                        const u = 1 - t;
+                        lineTo([
+                            u * u * u * p0[0] + 3 * u * u * t * p1[0] + 3 * u * t * t * p2[0] + t * t * t * p3[0],
+                            u * u * u * p0[1] + 3 * u * u * t * p1[1] + 3 * u * t * t * p2[1] + t * t * t * p3[1],
+                        ]);
+                    }
+                    cur = p3;
+                    nextCubic = p2;
+                    break;
+                }
+                case "Q":
+                case "T": {
+                    const p0 = cur;
+                    const p1 = upper === "Q"
+                        ? at(a[0], a[1])
+                        : lastQuad
+                            ? [2 * p0[0] - lastQuad[0], 2 * p0[1] - lastQuad[1]]
+                            : p0;
+                    const p2 = upper === "Q" ? at(a[2], a[3]) : at(a[0], a[1]);
+                    const n = steps(dist(p0, p1) + dist(p1, p2), tolerance);
+                    for (let k = 1; k <= n; k++) {
+                        const t = k / n;
+                        const u = 1 - t;
+                        lineTo([
+                            u * u * p0[0] + 2 * u * t * p1[0] + t * t * p2[0],
+                            u * u * p0[1] + 2 * u * t * p1[1] + t * t * p2[1],
+                        ]);
+                    }
+                    cur = p2;
+                    nextQuad = p1;
+                    break;
+                }
+                case "A": {
+                    const to = at(a[5], a[6]);
+                    for (const p of arcPoints(cur, a[0], a[1], a[2], a[3] !== 0, a[4] !== 0, to, tolerance))
+                        lineTo(p);
+                    break;
+                }
+            }
+            lastCubic = nextCubic;
+            lastQuad = nextQuad;
+        } while (i < tokens.length && !("cmd" in tokens[i]));
+    }
+    flush();
+    return lines;
+}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@todrawn/scribe-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "MCP server for Todrawn Scribe: turn code or text into a handwriting video project your agent can hand you as a link.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "todrawn-scribe-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test \"src/**/*.test.ts\"",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "jpeg-js": "^0.4.4",
+    "pngjs": "^7.0.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "@types/pngjs": "^6.0.5",
+    "typescript": "^5"
+  },
+  "homepage": "https://todrawn.com/scribe",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Brbn-jpg/whiteboard.git",
+    "directory": "mcp/scribe-mcp"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "video",
+    "code-to-video",
+    "handwriting",
+    "todrawn",
+    "scribe"
+  ]
+}