@neverprepared/mcp-phantom-diagrams 1.0.0

package/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  ci:
+    name: Build & Test
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type check
+        run: npm run typecheck
+
+      - name: Test
+        run: npm run test:unit
+        # Integration tests require Docker + running Kroki — skipped in CI.
+        # Run locally with: npm run test:integration
+
+      - name: Build
+        run: npm run build

package/.github/workflows/release-please.yml

@@ -0,0 +1,50 @@
+name: Release Please
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+  packages: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push'
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          release-type: node
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: release-please
+    if: |
+      always() &&
+      (needs.release-please.outputs.release_created == 'true' || github.event_name == 'workflow_dispatch')
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          registry-url: https://registry.npmjs.org/
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/CLAUDE.md

@@ -0,0 +1,49 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+npm install       # install dependencies
+npm run build     # compile TypeScript → dist/
+npm start         # run the MCP server (stdio transport)
+npm run dev       # watch mode — recompiles on change
+```
+
+No tests are configured yet. Verify manually via `npx @modelcontextprotocol/inspector node dist/index.js`.
+
+## Architecture
+
+This is a TypeScript MCP server (stdio transport) that wraps [Kroki](https://kroki.io/) — a unified diagram-rendering gateway. Kroki runs as a local Docker stack; the server auto-starts it on first tool call if it isn't already up.
+
+### File map
+
+| File | Role |
+|---|---|
+| `src/index.ts` | MCP server entry: registers tools, connects `StdioServerTransport` |
+| `src/docker.ts` | `ensureKrokiRunning()` — health-checks Kroki and runs `docker compose up -d` if needed |
+| `src/kroki.ts` | `convertDiagram()` HTTP client + `DIAGRAM_TYPES` static map |
+| `docker-compose.yml` | Kroki + companion containers; project name `kroki-shared` (shared across profiles) |
+
+### MCP tools exposed
+
+- **`convert_diagram`** — POST diagram source text to Kroki, return SVG string or base64 PNG/JPEG
+- **`list_diagram_types`** — return static map of supported types and their output formats
+
+### Container startup flow
+
+1. `GET localhost:8000/health` → already up, done
+2. Else: `docker compose -p kroki-shared -f <abs-path>/docker-compose.yml up -d`
+3. Poll health with exponential backoff (max 30 s)
+
+Port is configurable via `KROKI_URL` env var (default `http://localhost:8000`).
+
+### Output format handling
+
+- `svg` → returned as a `text` content block (plain SVG string)
+- `png` / `jpeg` → returned as an `image` content block (base64-encoded)
+
+### Zod version
+
+The project uses Zod v4 (bundled with `@modelcontextprotocol/sdk` 1.29+). Use `z.record(z.string(), z.string())` — Zod v4 requires both key and value type arguments.

package/README.md

@@ -0,0 +1,83 @@
+# mcp-phantom-diagrams
+
+An MCP server that converts diagram markup text into images using a locally-managed [Kroki](https://kroki.io/) Docker stack. Supports 28+ diagram types (PlantUML, Mermaid, Graphviz, and more) with SVG, PNG, and JPEG output. Starts the Kroki containers automatically on first use — no manual Docker setup required.
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `convert_diagram` | Render diagram markup to SVG, PNG, or JPEG |
+| `list_diagram_types` | List all supported diagram types and their available formats |
+| `get_kroki_status` | Check Kroki health, version, companion container status, and cache stats |
+
+### `convert_diagram` parameters
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `diagram_type` | string | — | Diagram language (e.g. `plantuml`, `mermaid`, `graphviz`) |
+| `source` | string | — | Diagram markup source text |
+| `output_format` | `svg` \| `png` \| `jpeg` | `svg` | Output format |
+| `output_path` | string | — | Write output to this path instead of returning inline content |
+| `options` | object | — | Diagram-type-specific options sent as `Kroki-Diagram-Options-*` headers |
+| `query_options` | object | — | Options passed as URL query parameters (e.g. `{ "theme": "dark" }`) |
+
+SVG is returned as a text block. PNG/JPEG are returned as base64 image blocks, or written to disk if `output_path` is set (recommended for large images to avoid token overhead).
+
+## Supported diagram types
+
+**Built-in** (no companion container required): `plantuml`, `graphviz`, `ditaa`, `svgbob`, `umlet`, `erd`, `nomnoml`, `structurizr`, `bytefield`, `c4plantuml`, `d2`, `dbml`, `pikchr`, `symbolator`, `vega`, `vegalite`, `wavedrom`
+
+**Companion containers** (started automatically): `mermaid`, `bpmn`, `excalidraw`, `blockdiag`, `seqdiag`, `actdiag`, `nwdiag`, `packetdiag`, `rackdiag`, `diagramsnet`
+
+## Requirements
+
+- Node.js 20+
+- Docker with Compose V2 (`docker compose` command)
+
+## Installation
+
+```bash
+npm install
+npm run build
+```
+
+## Claude Code configuration
+
+Add to your `~/.claude/claude.json` (or project-level `.claude/claude.json`):
+
+```json
+{
+  "mcpServers": {
+    "phantom-diagrams": {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp-phantom-diagrams/dist/index.js"]
+    }
+  }
+}
+```
+
+On first start, the server pulls and starts the Kroki Docker images automatically (shared across all Claude profiles via the `kroki-shared` compose project). Subsequent starts are instant if containers are already running.
+
+## Development
+
+```bash
+npm run dev          # watch mode — recompiles on change
+npm run test:unit    # unit tests (no Docker required)
+npm run test:integration  # round-trip tests (requires Docker)
+SKIP_INTEGRATION=1 npm test  # unit tests only, e.g. in CI
+```
+
+## Architecture
+
+```
+src/
+  index.ts    — MCP server, tool registration, startup warm-up
+  docker.ts   — container health-check and docker compose up (async, single-flight)
+  kroki.ts    — HTTP client for Kroki API, DIAGRAM_TYPES map
+  cache.ts    — SHA-256 keyed LRU cache (100 entries / 50 MB)
+docker-compose.yml  — kroki + companion containers (project: kroki-shared)
+```
+
+The server warms up Kroki before accepting connections so the first tool call is never delayed by container start time. If warm-up fails (Docker not running), it logs a warning and retries on the first tool call.
+
+Rendered results are cached in memory for the lifetime of the server process, keyed on `(diagram_type, source, output_format, options, query_options)`.

package/dist/cache.d.ts

@@ -0,0 +1,14 @@
+import type { ConvertResult } from "./kroki.js";
+declare class DiagramCache {
+    private readonly store;
+    private totalBytes;
+    cacheKey(diagramType: string, source: string, outputFormat: string, options?: Record<string, string>, queryOptions?: Record<string, string>): string;
+    get(key: string): ConvertResult | undefined;
+    set(key: string, result: ConvertResult): void;
+    stats(): {
+        entries: number;
+        bytes: number;
+    };
+}
+export declare const diagramCache: DiagramCache;
+export {};

package/dist/cache.js

@@ -0,0 +1,44 @@
+import { createHash } from "crypto";
+const MAX_ENTRIES = 100;
+const MAX_BYTES = 50 * 1024 * 1024; // 50 MB
+function resultBytes(result) {
+    return result.format === "svg"
+        ? Buffer.byteLength(result.data, "utf8")
+        : result.data.byteLength;
+}
+class DiagramCache {
+    // Map preserves insertion order; delete+reinsert moves entry to "most recent" end.
+    store = new Map();
+    totalBytes = 0;
+    cacheKey(diagramType, source, outputFormat, options, queryOptions) {
+        return createHash("sha256")
+            .update(JSON.stringify([diagramType, source, outputFormat, options ?? {}, queryOptions ?? {}]))
+            .digest("hex");
+    }
+    get(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return undefined;
+        this.store.delete(key);
+        this.store.set(key, entry);
+        return entry.result;
+    }
+    set(key, result) {
+        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() {
+        return { entries: this.store.size, bytes: this.totalBytes };
+    }
+}
+export const diagramCache = new DiagramCache();
+//# sourceMappingURL=cache.js.map

package/dist/docker.d.ts

@@ -0,0 +1,2 @@
+export declare const KROKI_URL: string;
+export declare function ensureKrokiRunning(): Promise<void>;

package/dist/docker.js

@@ -0,0 +1,81 @@
+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() {
+    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();
+        return body["status"] === "pass";
+    }
+    catch {
+        return false;
+    }
+}
+function startContainers() {
+    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) => { stderr += chunk.toString(); });
+        proc.on("error", (err) => {
+            clearTimeout(timer);
+            const isNotFound = err.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() {
+    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 = null;
+export async function ensureKrokiRunning() {
+    if (await isHealthy())
+        return;
+    if (!startingPromise) {
+        startingPromise = startContainers()
+            .then(() => waitForHealth())
+            .finally(() => { startingPromise = null; });
+    }
+    return startingPromise;
+}
+//# sourceMappingURL=docker.js.map

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,169 @@
+#!/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 } 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);
+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];
+    if (!typeInfo.formats.includes(output_format)) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    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, source, output_format, 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, "utf8")
+            : result.data.byteLength;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Written to ${absPath} (${(bytes / 1024).toFixed(1)} KB)`,
+                },
+            ],
+        };
+    }
+    if (result.format === "svg") {
+        return { content: [{ type: "text", text: result.data }] };
+    }
+    return {
+        content: [
+            {
+                type: "image",
+                data: result.data.toString("base64"),
+                mimeType: `image/${result.format}`,
+            },
+        ],
+    };
+});
+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", 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 = 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", 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) => {
+    console.error(`[phantom-diagrams] Kroki warm-up failed: ${err.message}. Will retry on first tool call.`);
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);
+//# sourceMappingURL=index.js.map

package/dist/kroki.d.ts

@@ -0,0 +1,124 @@
+export type OutputFormat = "svg" | "png" | "jpeg";
+export interface DiagramTypeInfo {
+    formats: OutputFormat[];
+    requiresCompanion: boolean;
+}
+export declare const DIAGRAM_TYPES: {
+    plantuml: {
+        formats: OutputFormat[];
+        requiresCompanion: false;
+    };
+    graphviz: {
+        formats: OutputFormat[];
+        requiresCompanion: false;
+    };
+    ditaa: {
+        formats: OutputFormat[];
+        requiresCompanion: false;
+    };
+    svgbob: {
+        formats: OutputFormat[];
+        requiresCompanion: false;
+    };
+    umlet: {
+        formats: OutputFormat[];
+        requiresCompanion: false;
+    };
+    erd: {
+        formats: OutputFormat[];
+        requiresCompanion: false;
+    };
+    nomnoml: {
+        formats: OutputFormat[];
+        requiresCompanion: false;
+    };
+    structurizr: {
+        formats: OutputFormat[];
+        requiresCompanion: false;
+    };
+    bytefield: {
+        formats: OutputFormat[];
+        requiresCompanion: false;
+    };
+    c4plantuml: {
+        formats: OutputFormat[];
+        requiresCompanion: false;
+    };
+    d2: {
+        formats: OutputFormat[];
+        requiresCompanion: false;
+    };
+    dbml: {
+        formats: OutputFormat[];
+        requiresCompanion: false;
+    };
+    pikchr: {
+        formats: OutputFormat[];
+        requiresCompanion: false;
+    };
+    symbolator: {
+        formats: OutputFormat[];
+        requiresCompanion: false;
+    };
+    vega: {
+        formats: OutputFormat[];
+        requiresCompanion: false;
+    };
+    vegalite: {
+        formats: OutputFormat[];
+        requiresCompanion: false;
+    };
+    wavedrom: {
+        formats: OutputFormat[];
+        requiresCompanion: false;
+    };
+    mermaid: {
+        formats: OutputFormat[];
+        requiresCompanion: true;
+    };
+    bpmn: {
+        formats: OutputFormat[];
+        requiresCompanion: true;
+    };
+    excalidraw: {
+        formats: OutputFormat[];
+        requiresCompanion: true;
+    };
+    blockdiag: {
+        formats: OutputFormat[];
+        requiresCompanion: true;
+    };
+    seqdiag: {
+        formats: OutputFormat[];
+        requiresCompanion: true;
+    };
+    actdiag: {
+        formats: OutputFormat[];
+        requiresCompanion: true;
+    };
+    nwdiag: {
+        formats: OutputFormat[];
+        requiresCompanion: true;
+    };
+    packetdiag: {
+        formats: OutputFormat[];
+        requiresCompanion: true;
+    };
+    rackdiag: {
+        formats: OutputFormat[];
+        requiresCompanion: true;
+    };
+    diagramsnet: {
+        formats: OutputFormat[];
+        requiresCompanion: true;
+    };
+};
+export type DiagramType = keyof typeof DIAGRAM_TYPES;
+export type ConvertResult = {
+    format: "svg";
+    data: string;
+} | {
+    format: "png" | "jpeg";
+    data: Buffer;
+};
+export declare function convertDiagram(diagramType: DiagramType, source: string, outputFormat: OutputFormat, options?: Record<string, string>, queryOptions?: Record<string, string>): Promise<ConvertResult>;