@neverprepared/mcp-phantom-diagrams 1.0.0

package/dist/kroki.js

@@ -0,0 +1,104 @@
+import { KROKI_URL } from "./docker.js";
+export const DIAGRAM_TYPES = {
+    // Built-in (no companion container required)
+    plantuml: { formats: ["svg", "png", "jpeg"], requiresCompanion: false },
+    graphviz: { formats: ["svg", "png", "jpeg"], requiresCompanion: false },
+    ditaa: { formats: ["svg", "png"], requiresCompanion: false },
+    svgbob: { formats: ["svg", "png"], requiresCompanion: false },
+    umlet: { formats: ["svg", "png"], requiresCompanion: false },
+    erd: { formats: ["svg", "png"], requiresCompanion: false },
+    nomnoml: { formats: ["svg", "png"], requiresCompanion: false },
+    structurizr: { formats: ["svg", "png"], requiresCompanion: false },
+    bytefield: { formats: ["svg", "png"], requiresCompanion: false },
+    c4plantuml: { formats: ["svg", "png"], requiresCompanion: false },
+    d2: { formats: ["svg"], requiresCompanion: false },
+    dbml: { formats: ["svg", "png"], requiresCompanion: false },
+    pikchr: { formats: ["svg"], requiresCompanion: false },
+    symbolator: { formats: ["svg", "png"], requiresCompanion: false },
+    vega: { formats: ["svg", "png"], requiresCompanion: false },
+    vegalite: { formats: ["svg", "png"], requiresCompanion: false },
+    wavedrom: { formats: ["svg", "png"], requiresCompanion: false },
+    // Companion containers required
+    mermaid: { formats: ["svg", "png"], requiresCompanion: true },
+    bpmn: { formats: ["svg"], requiresCompanion: true },
+    excalidraw: { formats: ["svg", "png"], requiresCompanion: true },
+    blockdiag: { formats: ["svg", "png"], requiresCompanion: true },
+    seqdiag: { formats: ["svg", "png"], requiresCompanion: true },
+    actdiag: { formats: ["svg", "png"], requiresCompanion: true },
+    nwdiag: { formats: ["svg", "png"], requiresCompanion: true },
+    packetdiag: { formats: ["svg", "png"], requiresCompanion: true },
+    rackdiag: { formats: ["svg", "png"], requiresCompanion: true },
+    diagramsnet: { formats: ["svg", "png"], requiresCompanion: true },
+};
+const MAX_SOURCE_BYTES = 256 * 1024; // 256 KB
+const MAX_RESPONSE_BYTES = 10 * 1024 * 1024; // 10 MB
+// Allowlist for Kroki-Diagram-Options-* header keys and values to prevent CRLF injection.
+const OPTION_KEY_RE = /^[A-Za-z0-9_-]{1,64}$/;
+const OPTION_VAL_RE = /^[\x20-\x7E]{0,1024}$/;
+export async function convertDiagram(diagramType, source, outputFormat, options, queryOptions) {
+    if (Buffer.byteLength(source, "utf8") > MAX_SOURCE_BYTES) {
+        throw new Error(`Diagram source exceeds ${MAX_SOURCE_BYTES / 1024} KB limit`);
+    }
+    const headers = {
+        "Content-Type": "text/plain",
+        Accept: outputFormat === "svg" ? "image/svg+xml" : `image/${outputFormat}`,
+    };
+    if (options) {
+        for (const [key, value] of Object.entries(options)) {
+            if (!OPTION_KEY_RE.test(key)) {
+                throw new Error(`Invalid option key: ${JSON.stringify(key)}`);
+            }
+            if (!OPTION_VAL_RE.test(value)) {
+                throw new Error(`Invalid option value for key ${JSON.stringify(key)}`);
+            }
+            headers[`Kroki-Diagram-Options-${key}`] = value;
+        }
+    }
+    const url = new URL(`${KROKI_URL}/${diagramType}/${outputFormat}`);
+    if (queryOptions) {
+        for (const [key, value] of Object.entries(queryOptions)) {
+            if (!OPTION_KEY_RE.test(key)) {
+                throw new Error(`Invalid query option key: ${JSON.stringify(key)}`);
+            }
+            if (!OPTION_VAL_RE.test(value)) {
+                throw new Error(`Invalid query option value for key ${JSON.stringify(key)}`);
+            }
+            url.searchParams.set(key, value);
+        }
+    }
+    const res = await fetch(url, {
+        method: "POST",
+        headers,
+        body: source,
+        signal: AbortSignal.timeout(30_000),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        const hint = res.status >= 400 && res.status < 500
+            ? `Diagram source rejected — likely a syntax error in the ${diagramType} source. `
+            : "Kroki server error. ";
+        throw new Error(`${hint}HTTP ${res.status}: ${body}`);
+    }
+    const contentType = res.headers.get("content-type") ?? "";
+    const expectedMime = outputFormat === "svg" ? "image/svg+xml" : `image/${outputFormat}`;
+    if (!contentType.includes(expectedMime)) {
+        throw new Error(`Unexpected content-type from Kroki: "${contentType}" (expected "${expectedMime}")`);
+    }
+    const contentLength = Number(res.headers.get("content-length"));
+    if (Number.isFinite(contentLength) && contentLength > MAX_RESPONSE_BYTES) {
+        throw new Error(`Kroki response too large: ${contentLength} bytes (limit ${MAX_RESPONSE_BYTES / 1024 / 1024} MB)`);
+    }
+    if (outputFormat === "svg") {
+        const text = await res.text();
+        if (Buffer.byteLength(text, "utf8") > MAX_RESPONSE_BYTES) {
+            throw new Error("Kroki SVG response exceeds size limit");
+        }
+        return { format: "svg", data: text };
+    }
+    const arrayBuffer = await res.arrayBuffer();
+    if (arrayBuffer.byteLength > MAX_RESPONSE_BYTES) {
+        throw new Error("Kroki image response exceeds size limit");
+    }
+    return { format: outputFormat, data: Buffer.from(arrayBuffer) };
+}
+//# sourceMappingURL=kroki.js.map

package/docker-compose.yml

@@ -0,0 +1,37 @@
+services:
+  kroki:
+    image: yuzutech/kroki
+    ports:
+      - "127.0.0.1:18000:8000"
+    environment:
+      - KROKI_MERMAID_HOST=mermaid
+      - KROKI_BPMN_HOST=bpmn
+      - KROKI_EXCALIDRAW_HOST=excalidraw
+      - KROKI_BLOCKDIAG_HOST=blockdiag
+      - KROKI_SEQDIAG_HOST=blockdiag
+      - KROKI_ACTDIAG_HOST=blockdiag
+      - KROKI_NWDIAG_HOST=blockdiag
+      - KROKI_PACKETDIAG_HOST=blockdiag
+      - KROKI_RACKDIAG_HOST=blockdiag
+      - KROKI_DIAGRAMSNET_HOST=diagramsnet
+    depends_on:
+      - mermaid
+      - bpmn
+      - excalidraw
+      - blockdiag
+      - diagramsnet
+
+  mermaid:
+    image: yuzutech/kroki-mermaid
+
+  bpmn:
+    image: yuzutech/kroki-bpmn
+
+  excalidraw:
+    image: yuzutech/kroki-excalidraw
+
+  blockdiag:
+    image: yuzutech/kroki-blockdiag
+
+  diagramsnet:
+    image: yuzutech/kroki-diagramsnet

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@neverprepared/mcp-phantom-diagrams",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "MCP server that converts diagram markup to images via a local Kroki instance",
+  "bin": {
+    "mcp-phantom-diagrams": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "postbuild": "chmod +x dist/index.js",
+    "prepare": "npm run build",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx/esm --test 'test/**/*.test.ts'",
+    "test:unit": "node --import tsx/esm --test 'test/unit.test.ts'",
+    "test:integration": "node --import tsx/esm --test 'test/integration.test.ts'"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/cache.ts

@@ -0,0 +1,65 @@
+import { createHash } from "crypto";
+import type { ConvertResult } from "./kroki.js";
+
+const MAX_ENTRIES = 100;
+const MAX_BYTES = 50 * 1024 * 1024; // 50 MB
+
+interface Entry {
+  result: ConvertResult;
+  bytes: number;
+}
+
+function resultBytes(result: ConvertResult): number {
+  return result.format === "svg"
+    ? Buffer.byteLength(result.data as string, "utf8")
+    : (result.data as Buffer).byteLength;
+}
+
+class DiagramCache {
+  // Map preserves insertion order; delete+reinsert moves entry to "most recent" end.
+  private readonly store = new Map<string, Entry>();
+  private totalBytes = 0;
+
+  cacheKey(
+    diagramType: string,
+    source: string,
+    outputFormat: string,
+    options?: Record<string, string>,
+    queryOptions?: Record<string, string>
+  ): string {
+    return createHash("sha256")
+      .update(JSON.stringify([diagramType, source, outputFormat, options ?? {}, queryOptions ?? {}]))
+      .digest("hex");
+  }
+
+  get(key: string): ConvertResult | undefined {
+    const entry = this.store.get(key);
+    if (!entry) return undefined;
+    this.store.delete(key);
+    this.store.set(key, entry);
+    return entry.result;
+  }
+
+  set(key: string, result: ConvertResult): void {
+    const bytes = resultBytes(result);
+
+    while (
+      this.store.size >= MAX_ENTRIES ||
+      (this.totalBytes + bytes > MAX_BYTES && this.store.size > 0)
+    ) {
+      const oldest = this.store.keys().next().value;
+      if (oldest === undefined) break;
+      this.totalBytes -= this.store.get(oldest)!.bytes;
+      this.store.delete(oldest);
+    }
+
+    this.store.set(key, { result, bytes });
+    this.totalBytes += bytes;
+  }
+
+  stats(): { entries: number; bytes: number } {
+    return { entries: this.store.size, bytes: this.totalBytes };
+  }
+}
+
+export const diagramCache = new DiagramCache();

package/src/docker.ts

@@ -0,0 +1,102 @@
+import { spawn } from "child_process";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+
+export const KROKI_URL = process.env.KROKI_URL ?? "http://localhost:18000";
+const COMPOSE_PROJECT = "kroki-shared";
+const COMPOSE_TIMEOUT_MS = 5 * 60_000; // 5 min — allows for image pulls on first run
+const HEALTH_TIMEOUT_MS = 30_000;
+const HEALTH_POLL_START_MS = 500;
+const HEALTH_POLL_MAX_MS = 2_000;
+
+// Resolved at module load so it's portable regardless of cwd.
+// spawnSync/spawn receive it as a single argv element — no shell, no injection risk.
+const composeFile = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "docker-compose.yml"
+);
+
+async function isHealthy(): Promise<boolean> {
+  try {
+    const res = await fetch(`${KROKI_URL}/health`, {
+      signal: AbortSignal.timeout(2_000),
+    });
+    if (!res.ok) return false;
+    // Kroki returns {"status":"pass"} — validate to avoid false positives
+    // from other services that happen to expose a /health endpoint.
+    const body = await res.json() as Record<string, unknown>;
+    return body["status"] === "pass";
+  } catch {
+    return false;
+  }
+}
+
+function startContainers(): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(
+      "docker",
+      ["compose", "-p", COMPOSE_PROJECT, "-f", composeFile, "up", "-d"],
+      { stdio: ["ignore", "pipe", "pipe"] }
+    );
+
+    const timer = setTimeout(() => {
+      proc.kill("SIGKILL");
+      reject(new Error(
+        `docker compose up timed out after ${COMPOSE_TIMEOUT_MS / 60_000} minutes. ` +
+        "Images may still be pulling — run 'docker compose -p kroki-shared pull' manually first."
+      ));
+    }, COMPOSE_TIMEOUT_MS);
+
+    let stderr = "";
+    proc.stderr?.on("data", (chunk: Buffer) => { stderr += chunk.toString(); });
+
+    proc.on("error", (err) => {
+      clearTimeout(timer);
+      const isNotFound = (err as NodeJS.ErrnoException).code === "ENOENT";
+      reject(new Error(
+        isNotFound
+          ? "docker not found on PATH — is Docker installed and running?"
+          : `Failed to invoke docker: ${err.message}`
+      ));
+    });
+
+    proc.on("close", (code) => {
+      clearTimeout(timer);
+      if (code !== 0) {
+        reject(new Error(`docker compose up failed (exit ${code}):\n${stderr}`));
+      } else {
+        resolve();
+      }
+    });
+  });
+}
+
+async function waitForHealth(): Promise<void> {
+  const deadline = Date.now() + HEALTH_TIMEOUT_MS;
+  let delay = HEALTH_POLL_START_MS;
+
+  while (Date.now() < deadline) {
+    if (await isHealthy()) return;
+    await new Promise((r) => setTimeout(r, delay));
+    delay = Math.min(delay * 2, HEALTH_POLL_MAX_MS);
+  }
+
+  throw new Error(
+    "Kroki did not become healthy within 30s — ensure Docker is running and port 18000 is free. " +
+    "On first run, images may still be pulling; wait a moment and try again."
+  );
+}
+
+// Single-flight latch: concurrent callers share one start attempt.
+let startingPromise: Promise<void> | null = null;
+
+export async function ensureKrokiRunning(): Promise<void> {
+  if (await isHealthy()) return;
+  if (!startingPromise) {
+    startingPromise = startContainers()
+      .then(() => waitForHealth())
+      .finally(() => { startingPromise = null; });
+  }
+  return startingPromise;
+}

package/src/index.ts

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+import { mkdir, writeFile } from "fs/promises";
+import { dirname, resolve } from "path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { ensureKrokiRunning, KROKI_URL } from "./docker.js";
+import { convertDiagram, DIAGRAM_TYPES, type DiagramType, type OutputFormat } from "./kroki.js";
+import { diagramCache } from "./cache.js";
+
+const server = new McpServer({
+  name: "phantom-diagrams",
+  version: "1.0.0",
+});
+
+const diagramTypeEnum = Object.keys(DIAGRAM_TYPES) as [DiagramType, ...DiagramType[]];
+
+server.registerTool(
+  "convert_diagram",
+  {
+    title: "Convert diagram source to image",
+    description:
+      "Render a diagram from source text using a local Kroki instance. " +
+      "SVG output is returned as a text block; PNG and JPEG as base64 image blocks — or written to disk if output_path is provided. " +
+      "Results are cached in memory; identical inputs return instantly. " +
+      "Call list_diagram_types first to see which types support which formats. " +
+      "If Kroki returns an HTTP 4xx error, the diagram source likely has a syntax error — fix it and retry.",
+    inputSchema: {
+      diagram_type: z
+        .enum(diagramTypeEnum)
+        .describe("Diagram language/type — e.g. plantuml, mermaid, graphviz. Call list_diagram_types to see all options."),
+      source: z
+        .string()
+        .min(1)
+        .max(256 * 1024)
+        .describe("Diagram markup source text"),
+      output_format: z
+        .enum(["svg", "png", "jpeg"])
+        .default("svg")
+        .describe("Output format. SVG is returned as text; PNG and JPEG as base64-encoded image blocks (or written to disk if output_path is set)."),
+      output_path: z
+        .string()
+        .optional()
+        .describe("Absolute or relative path to write the output file to. Parent directories are created automatically. When set, returns the path and file size instead of raw content — preferred for PNG/JPEG to avoid large base64 payloads."),
+      options: z
+        .record(z.string(), z.string())
+        .optional()
+        .describe("Diagram-type-specific rendering options sent as Kroki-Diagram-Options-* HTTP headers (see Kroki docs). Keys and values must be printable ASCII."),
+      query_options: z
+        .record(z.string(), z.string())
+        .optional()
+        .describe("Diagram-type-specific options passed as URL query parameters (e.g. { theme: 'dark' }). Keys and values must be printable ASCII."),
+    },
+    annotations: {
+      readOnlyHint: false, // can write files when output_path is set
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+  },
+  async ({ diagram_type, source, output_format, output_path, options, query_options }) => {
+    await ensureKrokiRunning();
+
+    const typeInfo = DIAGRAM_TYPES[diagram_type as DiagramType];
+    if (!typeInfo.formats.includes(output_format as OutputFormat)) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: "text" as const,
+            text: `${diagram_type} does not support ${output_format}. Supported formats: ${typeInfo.formats.join(", ")}`,
+          },
+        ],
+      };
+    }
+
+    const cacheKey = diagramCache.cacheKey(diagram_type, source, output_format, options, query_options);
+    let result = diagramCache.get(cacheKey);
+
+    if (!result) {
+      result = await convertDiagram(
+        diagram_type as DiagramType,
+        source,
+        output_format as OutputFormat,
+        options,
+        query_options
+      );
+      diagramCache.set(cacheKey, result);
+    }
+
+    if (output_path) {
+      const absPath = resolve(output_path);
+      await mkdir(dirname(absPath), { recursive: true });
+      const content = result.format === "svg" ? result.data : result.data;
+      await writeFile(absPath, content);
+      const bytes =
+        result.format === "svg"
+          ? Buffer.byteLength(result.data as string, "utf8")
+          : (result.data as Buffer).byteLength;
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Written to ${absPath} (${(bytes / 1024).toFixed(1)} KB)`,
+          },
+        ],
+      };
+    }
+
+    if (result.format === "svg") {
+      return { content: [{ type: "text" as const, text: result.data }] };
+    }
+
+    return {
+      content: [
+        {
+          type: "image" as const,
+          data: result.data.toString("base64"),
+          mimeType: `image/${result.format}` as "image/png" | "image/jpeg",
+        },
+      ],
+    };
+  }
+);
+
+server.registerTool(
+  "list_diagram_types",
+  {
+    title: "List supported diagram types",
+    description:
+      "Returns all diagram types Kroki supports along with their available output formats and whether they require a companion container. " +
+      "Call this before convert_diagram if you are unsure which type or format to use.",
+    inputSchema: {},
+    annotations: {
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+  },
+  async () => {
+    const rows = Object.entries(DIAGRAM_TYPES).map(([type, info]) => ({
+      type,
+      formats: info.formats,
+      requiresCompanion: info.requiresCompanion,
+    }));
+
+    return {
+      content: [{ type: "text" as const, text: JSON.stringify(rows, null, 2) }],
+    };
+  }
+);
+
+server.registerTool(
+  "get_kroki_status",
+  {
+    title: "Get Kroki server status",
+    description:
+      "Returns the health and version of the local Kroki instance, which diagram types require companion containers, and current render cache stats. " +
+      "Useful for diagnosing why a diagram type is failing or checking what is running.",
+    inputSchema: {},
+    annotations: {
+      readOnlyHint: true,
+      idempotentHint: false,
+      openWorldHint: false,
+    },
+  },
+  async () => {
+    let healthy = false;
+    let krokiInfo: unknown = null;
+
+    try {
+      const res = await fetch(`${KROKI_URL}/health`, { signal: AbortSignal.timeout(3_000) });
+      healthy = res.ok;
+      if (res.ok) {
+        krokiInfo = await res.json().catch(() => null);
+      }
+    } catch {
+      // healthy stays false
+    }
+
+    const companions = Object.entries(DIAGRAM_TYPES)
+      .filter(([, info]) => info.requiresCompanion)
+      .map(([type]) => type);
+
+    const status = {
+      kroki: {
+        url: KROKI_URL,
+        healthy,
+        ...(krokiInfo ? { info: krokiInfo } : {}),
+      },
+      companions,
+      cache: diagramCache.stats(),
+    };
+
+    return {
+      content: [{ type: "text" as const, text: JSON.stringify(status, null, 2) }],
+    };
+  }
+);
+
+// Warm up Kroki before accepting requests so the first tool call doesn't
+// absorb the container start latency (can be 30s+ on cold pull).
+await ensureKrokiRunning().catch((err: Error) => {
+  console.error(`[phantom-diagrams] Kroki warm-up failed: ${err.message}. Will retry on first tool call.`);
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/kroki.ts

@@ -0,0 +1,140 @@
+import { KROKI_URL } from "./docker.js";
+
+export type OutputFormat = "svg" | "png" | "jpeg";
+
+export interface DiagramTypeInfo {
+  formats: OutputFormat[];
+  requiresCompanion: boolean;
+}
+
+export const DIAGRAM_TYPES = {
+  // Built-in (no companion container required)
+  plantuml:     { formats: ["svg", "png", "jpeg"] as OutputFormat[], requiresCompanion: false },
+  graphviz:     { formats: ["svg", "png", "jpeg"] as OutputFormat[], requiresCompanion: false },
+  ditaa:        { formats: ["svg", "png"]          as OutputFormat[], requiresCompanion: false },
+  svgbob:       { formats: ["svg", "png"]          as OutputFormat[], requiresCompanion: false },
+  umlet:        { formats: ["svg", "png"]          as OutputFormat[], requiresCompanion: false },
+  erd:          { formats: ["svg", "png"]          as OutputFormat[], requiresCompanion: false },
+  nomnoml:      { formats: ["svg", "png"]          as OutputFormat[], requiresCompanion: false },
+  structurizr:  { formats: ["svg", "png"]          as OutputFormat[], requiresCompanion: false },
+  bytefield:    { formats: ["svg", "png"]          as OutputFormat[], requiresCompanion: false },
+  c4plantuml:   { formats: ["svg", "png"]          as OutputFormat[], requiresCompanion: false },
+  d2:           { formats: ["svg"]                 as OutputFormat[], requiresCompanion: false },
+  dbml:         { formats: ["svg", "png"]          as OutputFormat[], requiresCompanion: false },
+  pikchr:       { formats: ["svg"]                 as OutputFormat[], requiresCompanion: false },
+  symbolator:   { formats: ["svg", "png"]          as OutputFormat[], requiresCompanion: false },
+  vega:         { formats: ["svg", "png"]          as OutputFormat[], requiresCompanion: false },
+  vegalite:     { formats: ["svg", "png"]          as OutputFormat[], requiresCompanion: false },
+  wavedrom:     { formats: ["svg", "png"]          as OutputFormat[], requiresCompanion: false },
+
+  // Companion containers required
+  mermaid:      { formats: ["svg", "png"]          as OutputFormat[], requiresCompanion: true },
+  bpmn:         { formats: ["svg"]                 as OutputFormat[], requiresCompanion: true },
+  excalidraw:   { formats: ["svg", "png"]          as OutputFormat[], requiresCompanion: true },
+  blockdiag:    { formats: ["svg", "png"]          as OutputFormat[], requiresCompanion: true },
+  seqdiag:      { formats: ["svg", "png"]          as OutputFormat[], requiresCompanion: true },
+  actdiag:      { formats: ["svg", "png"]          as OutputFormat[], requiresCompanion: true },
+  nwdiag:       { formats: ["svg", "png"]          as OutputFormat[], requiresCompanion: true },
+  packetdiag:   { formats: ["svg", "png"]          as OutputFormat[], requiresCompanion: true },
+  rackdiag:     { formats: ["svg", "png"]          as OutputFormat[], requiresCompanion: true },
+  diagramsnet:  { formats: ["svg", "png"]          as OutputFormat[], requiresCompanion: true },
+} satisfies Record<string, DiagramTypeInfo>;
+
+export type DiagramType = keyof typeof DIAGRAM_TYPES;
+
+const MAX_SOURCE_BYTES = 256 * 1024;       // 256 KB
+const MAX_RESPONSE_BYTES = 10 * 1024 * 1024; // 10 MB
+
+// Allowlist for Kroki-Diagram-Options-* header keys and values to prevent CRLF injection.
+const OPTION_KEY_RE = /^[A-Za-z0-9_-]{1,64}$/;
+const OPTION_VAL_RE = /^[\x20-\x7E]{0,1024}$/;
+
+export type ConvertResult =
+  | { format: "svg"; data: string }
+  | { format: "png" | "jpeg"; data: Buffer };
+
+export async function convertDiagram(
+  diagramType: DiagramType,
+  source: string,
+  outputFormat: OutputFormat,
+  options?: Record<string, string>,
+  queryOptions?: Record<string, string>
+): Promise<ConvertResult> {
+  if (Buffer.byteLength(source, "utf8") > MAX_SOURCE_BYTES) {
+    throw new Error(`Diagram source exceeds ${MAX_SOURCE_BYTES / 1024} KB limit`);
+  }
+
+  const headers: Record<string, string> = {
+    "Content-Type": "text/plain",
+    Accept: outputFormat === "svg" ? "image/svg+xml" : `image/${outputFormat}`,
+  };
+
+  if (options) {
+    for (const [key, value] of Object.entries(options)) {
+      if (!OPTION_KEY_RE.test(key)) {
+        throw new Error(`Invalid option key: ${JSON.stringify(key)}`);
+      }
+      if (!OPTION_VAL_RE.test(value)) {
+        throw new Error(`Invalid option value for key ${JSON.stringify(key)}`);
+      }
+      headers[`Kroki-Diagram-Options-${key}`] = value;
+    }
+  }
+
+  const url = new URL(`${KROKI_URL}/${diagramType}/${outputFormat}`);
+  if (queryOptions) {
+    for (const [key, value] of Object.entries(queryOptions)) {
+      if (!OPTION_KEY_RE.test(key)) {
+        throw new Error(`Invalid query option key: ${JSON.stringify(key)}`);
+      }
+      if (!OPTION_VAL_RE.test(value)) {
+        throw new Error(`Invalid query option value for key ${JSON.stringify(key)}`);
+      }
+      url.searchParams.set(key, value);
+    }
+  }
+
+  const res = await fetch(url, {
+    method: "POST",
+    headers,
+    body: source,
+    signal: AbortSignal.timeout(30_000),
+  });
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    const hint = res.status >= 400 && res.status < 500
+      ? `Diagram source rejected — likely a syntax error in the ${diagramType} source. `
+      : "Kroki server error. ";
+    throw new Error(`${hint}HTTP ${res.status}: ${body}`);
+  }
+
+  const contentType = res.headers.get("content-type") ?? "";
+  const expectedMime = outputFormat === "svg" ? "image/svg+xml" : `image/${outputFormat}`;
+  if (!contentType.includes(expectedMime)) {
+    throw new Error(
+      `Unexpected content-type from Kroki: "${contentType}" (expected "${expectedMime}")`
+    );
+  }
+
+  const contentLength = Number(res.headers.get("content-length"));
+  if (Number.isFinite(contentLength) && contentLength > MAX_RESPONSE_BYTES) {
+    throw new Error(
+      `Kroki response too large: ${contentLength} bytes (limit ${MAX_RESPONSE_BYTES / 1024 / 1024} MB)`
+    );
+  }
+
+  if (outputFormat === "svg") {
+    const text = await res.text();
+    if (Buffer.byteLength(text, "utf8") > MAX_RESPONSE_BYTES) {
+      throw new Error("Kroki SVG response exceeds size limit");
+    }
+    return { format: "svg", data: text };
+  }
+
+  const arrayBuffer = await res.arrayBuffer();
+  if (arrayBuffer.byteLength > MAX_RESPONSE_BYTES) {
+    throw new Error("Kroki image response exceeds size limit");
+  }
+  return { format: outputFormat, data: Buffer.from(arrayBuffer) };
+}