@todrawn/scribe-mcp 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,75 @@
-# Temporary Holding Version
+# Todrawn Scribe MCP server
 
-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.
+An [MCP](https://modelcontextprotocol.io) server that lets an AI agent turn code, text, a line drawing or a photo into a [Todrawn Scribe](https://todrawn.com/scribe) project, a video of a pen writing, drawing or painting it by hand.
+
+The agent gets back a link. Opening it loads the project into the Scribe studio, where you preview it and export the MP4. The whole project travels inside the link after `#`, so the server uploads nothing and needs no account or API key.
+
+## Install
+
+Claude Code:
+
+```bash
+claude mcp add todrawn-scribe -- npx -y @todrawn/scribe-mcp
+```
+
+OpenAI Codex CLI:
+
+```bash
+codex mcp add todrawn-scribe -- npx -y @todrawn/scribe-mcp
+```
+
+VS Code (GitHub Copilot):
+
+```bash
+code --add-mcp '{"name":"todrawn-scribe","command":"npx","args":["-y","@todrawn/scribe-mcp"]}'
+```
+
+Claude Desktop (Settings > Developer > Edit Config), Cursor (`~/.cursor/mcp.json`), Gemini CLI (`~/.gemini/settings.json`) and other clients that read an `mcpServers` block:
+
+```json
+{
+  "mcpServers": {
+    "todrawn-scribe": {
+      "command": "npx",
+      "args": ["-y", "@todrawn/scribe-mcp"]
+    }
+  }
+}
+```
+
+Any other MCP client runs the same stdio command: `npx -y @todrawn/scribe-mcp`. Needs Node.js 20 or newer.
+
+Then ask, for example: "Make a vertical Scribe video of the function I just wrote." or "Draw a lighthouse with Scribe." or "Paint ~/Pictures/dinner.jpg with Scribe."
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `scribe_create_video` | Takes `text` and optionally `language`, `aspect`, look and pacing settings and `locale`. Returns the studio link. |
+| `scribe_create_drawing` | Takes `paths` (SVG path data plus an optional ink colour each) and optionally `viewBox`, `aspect`, look settings and `locale`. Curves and arcs are flattened; the pen draws the paths in order. Returns the studio link. |
+| `scribe_paint_image` | Takes `imagePath` (a local PNG or JPEG) and optionally `aspect`, `detail` (low, medium, high), `pen`, `background`, `speedMultiplier` and `locale`. Paints the photo into up to ~2800 coloured strokes (an underpaint, then detail) and returns the studio link. |
+| `scribe_limits` | Lists input limits and what the Free and Premium plans allow. |
+
+## Privacy
+
+Photos are painted on your machine. The link holds only the pen strokes, after `#`, which browsers never send to a server, so neither the photo nor the painting is uploaded by this server.
+
+## Plans
+
+Previewing is free and needs no account. Exporting needs a free Todrawn account:
+
+- **Free:** 5 exports per UTC day; every video ends with a "Made with Todrawn Scribe" card.
+- **Premium:** unlimited exports; the card is optional.
+
+Input is capped at 1 MiB and 5000 lines. Clips are capped at 180 s, and longer text is drawn faster to fit.
+
+## Development
+
+```bash
+npm install
+npm test          # node --test, runs the TypeScript sources directly (Node 22.6+)
+npm run build     # emits dist/
+TODRAWN_SCRIBE_URL=http://localhost:3000 node dist/index.js   # links point at a local frontend
+```
+
+The constants in `src/constants.ts` mirror the studio. `frontend/src/lib/scribe/recipe-link-mcp.test.ts` fails if they drift, and checks that every link this server builds opens in the studio.

package/dist/constants.js

@@ -0,0 +1,36 @@
+/* Product facts the server validates against. Each one mirrors a constant in
+   frontend/src/lib/scribe; frontend/src/lib/scribe/recipe-link-mcp.test.ts
+   fails when they drift. Kept dependency-free so that test can import it. */
+/** Studio tokenizer languages (lib/scribe/tokenize.ts Language). */
+export const LANGUAGES = ["js", "ts", "py", "java", "clike", "sql", "html", "css", "bash", "go", "rust", "plain"];
+/** Output aspects (lib/scribe/presets.ts ASPECTS); "feed" is 4:5. */
+export const ASPECTS = ["landscape", "portrait", "square", "feed"];
+/** Site locales and their path prefixes (src/i18n/routing.ts LOCALE_PATH_PREFIXES). */
+export const LOCALE_PATH_PREFIXES = { en: "", pl: "/pl", de: "/de", fr: "/fr", es: "/es", "pt-BR": "/pt-br" };
+/** Input caps (lib/scribe/limits.ts). */
+export const MAX_INPUT_BYTES = 1024 * 1024;
+export const MAX_LINES = 5000;
+export const MAX_PLAYBACK_SECONDS = 180;
+export const FREE_EXPORTS_PER_DAY = 5;
+export const RESOLUTIONS = ["720p", "1080p"];
+export const FRAME_RATES = [24, 30];
+/** Link format (lib/scribe/recipe-link.ts). */
+export const RECIPE_LINK_VERSION = 1;
+export const MAX_RECIPE_LINK_CHARS = 120_000;
+/** Settings ranges a link may set (lib/scribe/settings.ts validateScribeSettings). */
+export const PENS = ["ballpoint", "marker", "fineliner", "pencil"];
+export const BACKGROUNDS = ["dark", "paper"];
+export const COLOR_MODES = ["syntax", "solid"];
+export const TIMINGS = ["reading", "pen"];
+export const LAYOUTS = ["auto", "scroll", "pages"];
+export const READING_WPS = { min: 1.5, max: 6, step: 0.5 };
+export const SPEED = { min: 0.5, max: 2 };
+/** Width/height of each artboard (lib/scribe/presets.ts paperForPreset). */
+export const ASPECT_RATIOS = { landscape: 16 / 9, portrait: 9 / 16, square: 1, feed: 4 / 5 };
+/** Named ink colours that adapt to the background (lib/scribe/annotations.ts ANNOTATION_COLOR_KEYS); #rrggbb also works. */
+export const DRAW_COLOR_KEYS = ["blue", "red", "green", "violet", "amber"];
+/** Draft caps (lib/scribe/recent-work.ts MAX_RECENT_TOTAL_POINTS / MAX_RECENT_STROKES). */
+export const MAX_DRAW_POINTS = 500_000;
+export const MAX_DRAW_STROKES = 50_000;
+/** Drawing link coordinates are integers in 0..DRAW_COORD_MAX across the artboard (lib/scribe/recipe-link.ts). */
+export const DRAW_COORD_MAX = 10_000;

package/dist/drawing.js

@@ -0,0 +1,124 @@
+import { deflateRawSync } from "node:zlib";
+import { ASPECT_RATIOS, ASPECTS, DRAW_COLOR_KEYS, DRAW_COORD_MAX, LOCALE_PATH_PREFIXES, MAX_DRAW_POINTS, MAX_DRAW_STROKES, MAX_RECIPE_LINK_CHARS, RECIPE_LINK_VERSION, } from "./constants.js";
+import { DEFAULT_BASE_URL, LinkError } from "./link.js";
+import { PathError, pathToPolylines } from "./svg-path.js";
+/** Share of the artboard left empty around a drawing framed by its own bounding box. */
+const AUTO_MARGIN = 0.08;
+function parseViewBox(value) {
+    const parts = value.trim().split(/[\s,]+/).map(Number);
+    if (parts.length !== 4 || parts.some((n) => !Number.isFinite(n)) || parts[2] <= 0 || parts[3] <= 0) {
+        throw new LinkError(`viewBox must be "minX minY width height" with a positive size, got "${value}".`);
+    }
+    const [x, y, w, h] = parts;
+    return { x, y, w, h };
+}
+function resolveColor(value) {
+    if (value === undefined)
+        return "blue";
+    const color = value.trim().toLowerCase();
+    if (DRAW_COLOR_KEYS.includes(color) || /^#[0-9a-f]{6}$/.test(color))
+        return color;
+    throw new LinkError(`Unknown colour "${value}". Use ${DRAW_COLOR_KEYS.join(", ")} or #rrggbb.`);
+}
+function boundingBox(lines) {
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    for (const line of lines) {
+        for (const [x, y] of line) {
+            minX = Math.min(minX, x);
+            minY = Math.min(minY, y);
+            maxX = Math.max(maxX, x);
+            maxY = Math.max(maxY, y);
+        }
+    }
+    return { x: minX, y: minY, w: Math.max(maxX - minX, 1e-9), h: Math.max(maxY - minY, 1e-9) };
+}
+/** The aspect whose artboard ratio is closest to the content's, on a log scale. */
+function closestAspect(ratio) {
+    let best = "square";
+    for (const aspect of ASPECTS) {
+        if (Math.abs(Math.log(ASPECT_RATIOS[aspect] / ratio)) < Math.abs(Math.log(ASPECT_RATIOS[best] / ratio)))
+            best = aspect;
+    }
+    return best;
+}
+/** Builds a /scribe#r= link for a drawing; throws LinkError with a message meant for the agent. */
+export function buildDrawingLink(input) {
+    if (input.paths.length === 0)
+        throw new LinkError("Pass at least one path to draw.");
+    const frame = input.viewBox === undefined ? null : parseViewBox(input.viewBox);
+    const flatten = (tolerance) => input.paths.map((path, index) => {
+        try {
+            return pathToPolylines(path.d, tolerance);
+        }
+        catch (error) {
+            if (error instanceof PathError)
+                throw new LinkError(`Path ${index + 1}: ${error.message}`);
+            throw error;
+        }
+    });
+    // a coarse pass sizes the drawing, then the real pass flattens with a
+    // tolerance relative to that size, so a 24-unit icon and a 2000-unit
+    // illustration come out equally smooth
+    const coarse = flatten(Number.POSITIVE_INFINITY).flat();
+    if (coarse.length === 0)
+        throw new LinkError("The paths contain nothing to draw (every subpath is a single point).");
+    const coarseBox = frame ?? boundingBox(coarse);
+    const lines = flatten(Math.max(coarseBox.w, coarseBox.h) / 300);
+    const content = frame ?? boundingBox(lines.flat());
+    const aspect = input.aspect ?? closestAspect(content.w / content.h);
+    const ratio = ASPECT_RATIOS[aspect];
+    // artboard units: width `ratio`, height 1
+    const margin = frame ? 0 : AUTO_MARGIN;
+    const scale = Math.min((ratio * (1 - 2 * margin)) / content.w, (1 - 2 * margin) / content.h);
+    const cx = content.x + content.w / 2;
+    const cy = content.y + content.h / 2;
+    const toCoord = (value) => Math.min(DRAW_COORD_MAX, Math.max(0, Math.round(value * DRAW_COORD_MAX)));
+    const strokes = [];
+    let points = 0;
+    input.paths.forEach((path, index) => {
+        const color = resolveColor(path.color);
+        for (const line of lines[index]) {
+            const pts = [];
+            for (const [x, y] of line) {
+                const u = toCoord((ratio / 2 + (x - cx) * scale) / ratio);
+                const v = toCoord(0.5 + (y - cy) * scale);
+                if (pts.length >= 2 && pts[pts.length - 2] === u && pts[pts.length - 1] === v)
+                    continue;
+                pts.push(u, v);
+            }
+            if (pts.length < 4)
+                continue;
+            strokes.push({ color, pts });
+            points += pts.length / 2;
+        }
+    });
+    if (strokes.length === 0)
+        throw new LinkError("The drawing is too small to see once fitted to the artboard.");
+    if (strokes.length > MAX_DRAW_STROKES || points > MAX_DRAW_POINTS) {
+        throw new LinkError(`The drawing has ${strokes.length} strokes and ${points} points; Scribe accepts ${MAX_DRAW_STROKES} and ${MAX_DRAW_POINTS}.`);
+    }
+    const link = encodeDrawLink({ aspect, strokes, settings: input.settings, locale: input.locale, baseUrl: input.baseUrl });
+    if (link === null) {
+        throw new LinkError(`This drawing is too detailed for a link (limit ${MAX_RECIPE_LINK_CHARS} encoded characters). Use fewer or simpler paths.`);
+    }
+    return { url: link, aspect, strokes: strokes.length, points };
+}
+/** Encodes a mode "draw" recipe link, or null when it would exceed the link cap. */
+export function encodeDrawLink(input) {
+    const settings = Object.fromEntries(Object.entries(input.settings ?? {}).filter(([, value]) => value !== undefined));
+    const payload = {
+        v: RECIPE_LINK_VERSION,
+        mode: "draw",
+        aspect: input.aspect,
+        strokes: input.strokes,
+        ...(Object.keys(settings).length > 0 ? { settings } : {}),
+    };
+    const encoded = deflateRawSync(Buffer.from(JSON.stringify(payload), "utf8"), { level: 9 }).toString("base64url");
+    if (encoded.length > (input.maxChars ?? MAX_RECIPE_LINK_CHARS))
+        return null;
+    const base = (input.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    return `${base}${LOCALE_PATH_PREFIXES[input.locale ?? "en"]}/scribe#r=${encoded}`;
+}

package/dist/image.js

@@ -0,0 +1,48 @@
+import { readFile } from "node:fs/promises";
+import jpeg from "jpeg-js";
+import { PNG } from "pngjs";
+import { LinkError } from "./link.js";
+/** Larger photos are refused rather than decoded into gigabytes of memory. */
+const MAX_MEGAPIXELS = 40;
+/** Decodes a local PNG or JPEG into planar RGB, compositing transparency over white paper. */
+export async function readImage(path) {
+    let buffer;
+    try {
+        buffer = await readFile(path);
+    }
+    catch {
+        throw new LinkError(`Could not read the image at "${path}". Pass an absolute path to a PNG or JPEG file.`);
+    }
+    let width, height, rgba;
+    try {
+        if (buffer.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) {
+            const png = PNG.sync.read(buffer);
+            ({ width, height } = png);
+            rgba = png.data;
+        }
+        else if (buffer[0] === 0xff && buffer[1] === 0xd8) {
+            const img = jpeg.decode(buffer, { useTArray: true, formatAsRGBA: true, maxResolutionInMP: MAX_MEGAPIXELS, maxMemoryUsageInMB: 1024 });
+            ({ width, height } = img);
+            rgba = img.data;
+        }
+        else {
+            throw new LinkError("Only PNG and JPEG images are supported. Convert the image (for example WebP or HEIC) to PNG or JPEG first.");
+        }
+    }
+    catch (error) {
+        if (error instanceof LinkError)
+            throw error;
+        throw new LinkError(`The image could not be decoded: ${error.message}`);
+    }
+    if (width * height > MAX_MEGAPIXELS * 1e6)
+        throw new LinkError(`The image is larger than ${MAX_MEGAPIXELS} megapixels; resize it first.`);
+    const n = width * height;
+    const r = new Float32Array(n), g = new Float32Array(n), b = new Float32Array(n);
+    for (let i = 0; i < n; i++) {
+        const a = rgba[i * 4 + 3] / 255;
+        r[i] = (rgba[i * 4] / 255) * a + (1 - a);
+        g[i] = (rgba[i * 4 + 1] / 255) * a + (1 - a);
+        b[i] = (rgba[i * 4 + 2] / 255) * a + (1 - a);
+    }
+    return { width, height, r, g, b };
+}

package/dist/index.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { DEFAULT_BASE_URL } from "./link.js";
+import { createScribeServer } from "./server.js";
+/** TODRAWN_SCRIBE_URL points links at another deployment, e.g. http://localhost:3000. */
+function baseUrlFromEnv() {
+    const raw = process.env.TODRAWN_SCRIBE_URL?.trim();
+    if (!raw)
+        return DEFAULT_BASE_URL;
+    const url = new URL(raw);
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        throw new Error(`TODRAWN_SCRIBE_URL must be an http(s) URL, got ${raw}`);
+    }
+    return url.origin;
+}
+const server = createScribeServer({ baseUrl: baseUrlFromEnv() });
+await server.connect(new StdioServerTransport());

package/dist/link.js

@@ -0,0 +1,88 @@
+import { deflateRawSync } from "node:zlib";
+import { LANGUAGES, LOCALE_PATH_PREFIXES, MAX_INPUT_BYTES, MAX_LINES, MAX_RECIPE_LINK_CHARS, RECIPE_LINK_VERSION, } from "./constants.js";
+export const DEFAULT_BASE_URL = "https://todrawn.com";
+/** Names agents tend to use for a language, mapped onto the studio's tokenizers. */
+const LANGUAGE_ALIASES = {
+    javascript: "js",
+    jsx: "js",
+    mjs: "js",
+    node: "js",
+    typescript: "ts",
+    tsx: "ts",
+    python: "py",
+    c: "clike",
+    "c++": "clike",
+    cpp: "clike",
+    "c#": "clike",
+    csharp: "clike",
+    cs: "clike",
+    kotlin: "clike",
+    kt: "clike",
+    swift: "clike",
+    php: "clike",
+    dart: "clike",
+    scala: "clike",
+    postgres: "sql",
+    postgresql: "sql",
+    mysql: "sql",
+    xml: "html",
+    svg: "html",
+    vue: "html",
+    scss: "css",
+    sass: "css",
+    less: "css",
+    sh: "bash",
+    shell: "bash",
+    zsh: "bash",
+    console: "bash",
+    golang: "go",
+    rs: "rust",
+    text: "plain",
+    txt: "plain",
+    markdown: "plain",
+    md: "plain",
+    prose: "plain",
+};
+export class LinkError extends Error {
+}
+export function resolveLanguage(value) {
+    if (value === undefined || value.trim() === "")
+        return "plain";
+    const key = value.trim().toLowerCase();
+    if (LANGUAGES.includes(key))
+        return key;
+    const alias = LANGUAGE_ALIASES[key];
+    if (alias)
+        return alias;
+    throw new LinkError(`Unknown language "${value}". Use one of: ${LANGUAGES.join(", ")} (or a common name such as typescript, python, c++, shell, markdown).`);
+}
+/** Builds a /scribe#r= link; throws LinkError with a message meant for the agent. */
+export function buildRecipeLink(input) {
+    // the studio draws tabs and CRLF as written; normalise line endings only
+    const text = input.text.replace(/\r\n?/g, "\n");
+    if (text.trim() === "")
+        throw new LinkError("The text is empty. Pass the code or text to draw.");
+    const bytes = Buffer.byteLength(text, "utf8");
+    if (bytes > MAX_INPUT_BYTES) {
+        throw new LinkError(`The text is ${bytes} bytes; Scribe accepts at most ${MAX_INPUT_BYTES} bytes (1 MiB).`);
+    }
+    const lines = text.split("\n").length;
+    if (lines > MAX_LINES)
+        throw new LinkError(`The text has ${lines} lines; Scribe draws at most ${MAX_LINES}.`);
+    const language = resolveLanguage(input.language);
+    const settings = Object.fromEntries(Object.entries(input.settings ?? {}).filter(([, value]) => value !== undefined));
+    const payload = {
+        v: RECIPE_LINK_VERSION,
+        text,
+        language,
+        ...(input.aspect ? { aspect: input.aspect } : {}),
+        ...(Object.keys(settings).length > 0 ? { settings } : {}),
+    };
+    const encoded = deflateRawSync(Buffer.from(JSON.stringify(payload), "utf8"), { level: 9 }).toString("base64url");
+    if (encoded.length > MAX_RECIPE_LINK_CHARS) {
+        throw new LinkError(`This text is too large for a link (${encoded.length} encoded characters, limit ${MAX_RECIPE_LINK_CHARS}). Shorten it: a readable clip is a few dozen lines.`);
+    }
+    const base = (input.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    const prefix = LOCALE_PATH_PREFIXES[input.locale ?? "en"];
+    return { url: `${base}${prefix}/scribe#r=${encoded}`, language, lines, bytes };
+}

package/dist/paint.js

@@ -0,0 +1,27 @@
+import { DRAW_COORD_MAX } from "./constants.js";
+import { encodeDrawLink } from "./drawing.js";
+import { LinkError } from "./link.js";
+import { paintImage } from "./painter.js";
+/** Paints an image and packs it into a /scribe#r= draw link, trimming the finest strokes if the link would be too long. */
+export function paintToLink(image, input = {}) {
+    const painting = paintImage(image, { aspect: input.aspect, pen: input.pen, detail: input.detail });
+    const q = (v, max) => Math.min(DRAW_COORD_MAX, Math.max(0, Math.round((v / max) * DRAW_COORD_MAX)));
+    const all = painting.strokes.map((s) => {
+        const pts = s.pts.flatMap(([x, y]) => [q(x, painting.width), q(y, painting.height)]);
+        // a stroke that collapsed onto one coordinate still needs two points
+        if (pts.length === 4 && pts[0] === pts[2] && pts[1] === pts[3])
+            pts[2] = Math.min(DRAW_COORD_MAX, pts[2] + 1);
+        return { color: s.color, pts };
+    });
+    const settings = { background: input.background ?? "paper", pen: input.pen ?? "fineliner", speedMultiplier: input.speedMultiplier };
+    let keep = all.length;
+    for (;;) {
+        const url = encodeDrawLink({ aspect: painting.aspect, strokes: all.slice(0, keep), settings, locale: input.locale, baseUrl: input.baseUrl, maxChars: input.maxChars });
+        if (url)
+            return { url, aspect: painting.aspect, strokes: keep, trimmed: all.length - keep, meanAbsDiff: painting.meanAbsDiff };
+        keep = Math.floor(keep * 0.93);
+        if (keep <= painting.underpaintStrokes) {
+            throw new LinkError("This image is too detailed to fit in a link even at its coarsest. Try detail \"low\" or a smaller artboard.");
+        }
+    }
+}