@geohar/pi-svg-mcp 0.0.0

package/instructions.txt

@@ -0,0 +1,56 @@
+# Diagrams & SVGs (svg-mcp)
+
+<!-- Canonical reach-for-svg-mcp directive. Copy into your global
+     $CLAUDE_CONFIG_DIR/CLAUDE.md, or let an svg-mcp plugin inject it each session
+     (the plugins symlink this file). It directs *approach*; the MCP tool
+     descriptions carry the mechanics. -->
+
+Three rules. Each fires on a **cue you can catch yourself in the middle of**, not on a
+topic you have to remember to think about. That's deliberate: you will not remember to
+"use the tools" — but you can notice yourself about to type a `<` .
+
+### 1. About to write `<svg`, or hand-edit XML inside one? That's the cue.
+
+Writing markup by hand is the wrong move **even when the shape looks trivial** — that's
+exactly when it feels justified, and it skips the only part that matters: seeing the
+result. At that exact moment:
+
+| your next move was | do this instead |
+|---|---|
+| write `<svg>`/`<path>`/`<rect>` markup for something new | `create_document`, then the `add_*` primitives — `boolean` for union/difference/intersection, plus gradients / filters / transforms |
+| hand-patch the markup of an SVG you have | `import_svg` → `find` / `describe_node` to locate → `edit_*` / `apply_*` / `delete_node` |
+| hand a result back after building it | `export_render` (or `render_document`) and **actually look at the image** first |
+
+Construct → render → see → iterate. **The loop is the product, not the XML.** One pass
+without rendering isn't a faster version of this — it's a different, worse thing.
+
+**Catch yourself:** if you're about to show or save SVG source you have never rendered,
+you are guessing at your own output. Render it, look, *then* hand it over.
+
+### 2. About to place boxes, arrows, bars, or rows by coordinate? Declare, don't draw.
+
+Hand-computing positions for structured content is the diagram version of hand-writing
+markup — it feels precise and produces drift, overlaps, and arrows through boxes. The
+cue is reaching for `add_rect` + `add_line` to represent *things and relationships*:
+
+| you're about to | do this instead |
+|---|---|
+| draw an architecture / flowchart / pipeline from rects and lines | `add_diagram_node(kind, label)` + `add_diagram_edge(source, target, kind)` + `add_diagram_container(members)`, then `layout_diagram` — zero coordinates |
+| hand-place bars, axes, tick labels (or shell out to matplotlib for a small figure) | `add_chart(kind, data)` — bar/line/donut/scatter/sparkline, scales and margins derived from the data |
+| lay out rows of text as a grid | `add_table(rows, header)` — column widths measured, numerics right-aligned |
+| pick colors and fonts shape by shape | `load_theme` first and say what things ARE (`role=`, `kind=`); the theme paints them. Read the guidance the load returns — it's the house style speaking |
+| annotate or key the result | `add_callout(target, text)` (points at ids, survives reflow), `add_legend()` (generated from what the document uses) |
+
+After moving, resizing, or deleting diagram nodes: **`reflow()`** — one call re-routes
+edges, re-anchors callouts, and re-fits containers. Layout is opt-in; it never reruns
+behind your back.
+
+### 3. More than a couple of tool calls? Start the preview and say so.
+
+Cue: you can tell the build will take more than two or three calls. Call `start_preview`
+**at the start**, not when you're done, and put the exact URL in your reply unprompted:
+"Live preview: <url> — it refreshes on every change."
+
+The reason is timing, not courtesy. Someone watching the drawing take shape can redirect
+you mid-build; the same person handed a finished image can only accept it or ask for the
+whole thing again. A preview URL shared at the end has none of that value.

package/mcp.json.example

@@ -0,0 +1,7 @@
+{
+  "mcpServers": {
+    "svg-mcp": {
+      "url": "http://127.0.0.1:7731/mcp"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+    "name": "@geohar/pi-svg-mcp",
+    "version": "0.0.0",
+    "description": "Pi extension: run the svg-mcp MCP server via sharedserver and inject the diagram-authoring directive. Pairs with pi-mcp-adapter, which makes svg-mcp's tools reachable from Pi.",
+    "type": "module",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "pi": {
+        "extensions": [
+            "./src/index.ts"
+        ]
+    },
+    "files": [
+        "src",
+        "dist",
+        "instructions.txt",
+        "mcp.json.example",
+        "README.md",
+        "LICENSE"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "clean": "rm -rf dist",
+        "typecheck": "tsc --noEmit",
+        "prepack": "node -e \"require('fs').copyFileSync('../../CLAUDE.md.example', './instructions.txt')\"",
+        "prepublishOnly": "npm run clean && npm run build"
+    },
+    "keywords": [
+        "pi",
+        "pi-extension",
+        "pi-mono",
+        "mcp",
+        "svg-mcp",
+        "svg",
+        "diagram",
+        "sharedserver",
+        "extension"
+    ],
+    "author": "George Harker <george@georgeharker.com>",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/georgeharker/svg-mcp.git",
+        "directory": "plugins/pi"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "devDependencies": {
+        "@types/node": "^22.0.0",
+        "typescript": "^5.6.0"
+    },
+    "engines": {
+        "node": ">=18.0.0"
+    }
+}

package/src/index.ts

@@ -0,0 +1,291 @@
+// Pi extension: run the `svg-mcp` MCP server via the `sharedserver` CLI and inject the
+// diagram-authoring directive into the system prompt.
+//
+// It is the Pi counterpart of svg-mcp's Claude Code and OpenCode plugins, and mirrors
+// their behaviour:
+//
+//   1. Stand-down switch — if a combiner already serves svg-mcp (global MCP_COMBINER, or
+//      the per-backend MCP_COMBINER_SERVES_SVG_MCP override, which wins), do NOT launch
+//      a standalone backend. The combiner owns svg-mcp's lifecycle. Only the launch is
+//      gated — the directive applies either way, since svg-mcp's tools are present via
+//      the combiner too.
+//   2. Process — on `session_start`, drive `sharedserver use … -- <svg-mcp serve argv>`
+//      so one warm svg-mcp is running and refcounted (shared across clients), paying its
+//      cold start (numpy + pillow) once. Released on `session_shutdown` when
+//      `reason === "quit"` (reload/resume/fork keep the process and re-attach).
+//   3. Directive — append the diagram-authoring text to the system prompt via
+//      `before_agent_start` (analogue of CC's additionalContext / OpenCode's
+//      system.transform).
+//
+// WHICH svg-mcp RUNS (mirrors the OpenCode plugin's resolveServeArgv):
+//   default            uvx svg-mcp@<version>      (published release, pinned)
+//   SVG_MCP_DEV=<dir>  uv run --project <dir>     (a dev checkout)
+//   SVG_MCP_DEV=1      uv run --project <repo>    (in-repo source, if resolvable)
+//
+// MCP registration itself (pointing pi-mcp-adapter at svg-mcp) is a single mcp.json
+// entry — see mcp.json.example and the README; static, and unnecessary when
+// combiner-served. The sharedserver resolution is ported from plugins/opencode.
+
+import { spawnSync } from "node:child_process"
+import { existsSync, readFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+import type {
+    AutocompleteItem,
+    ExtensionAPI,
+    ExtensionCommandContext,
+    ExtensionContext,
+    SessionShutdownEvent,
+} from "./pi.js"
+import { resolveSharedserver } from "./sharedserver-resolve.js"
+
+const DEFAULT_PORT = 7731
+const DEFAULT_NAME = "svg-mcp"
+const DEFAULT_GRACE = "1h"
+// Floor-only against sharedserver's latest release: svg-mcp consumes sharedserver rather
+// than shipping it. Kept equal to the sibling plugins' value.
+const SHAREDSERVER_MIN_VERSION = "0.6.7"
+// The svg-mcp PyPI release this extension runs by default (`uvx svg-mcp@<v>`). Decoupled
+// from this package's OWN version (matching the OpenCode plugin); override per-launch
+// with $SVG_MCP_VERSION. Keep it pointing at a real svg-mcp release.
+const SVG_MCP_TOOL_VERSION = "0.2.6"
+
+type LogFn = (level: "info" | "warn" | "error", message: string) => void
+
+// ── the diagram-authoring directive ────────────────────────────────
+// Appended to the system prompt so the agent reaches for svg-mcp's tools instead of
+// hand-writing SVG XML. Canonical source: CLAUDE.md.example at the repo root; a
+// release-time `prepack` copies it to this package's root as instructions.txt (see
+// package.json). A dev/unbuilt run without the copy falls back to empty and injects
+// nothing.
+const SVG_DIAGRAM_DIRECTIVE: string = (() => {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url))
+        return readFileSync(join(here, "..", "instructions.txt"), "utf8")
+    } catch {
+        return ""
+    }
+})()
+const DIRECTIVE_MARKER = SVG_DIAGRAM_DIRECTIVE.split("\n", 1)[0] ?? ""
+
+// ── env configuration ──────────────────────────────────────────────
+// svg-mcp's tool knobs use the shared SVG_MCP_* namespace (as its OpenCode plugin does),
+// so a user's SVG_MCP_PORT/VERSION/DEV apply across every client. Pi-extension-specific
+// toggles use PI_SVG_MCP_*.
+
+function env(name: string): string | undefined {
+    const v = process.env[name]
+    return v !== undefined && v !== "" ? v : undefined
+}
+
+// ── stand-down switch (mirrors the CC hook's combiner_serves) ──────
+
+function truthy(v: string | undefined): boolean {
+    if (v == null) return false
+    return !["", "0", "false", "no", "off"].includes(v.trim().toLowerCase())
+}
+
+/** Does a combiner serve `name`? The per-backend `MCP_COMBINER_SERVES_<NAME>` override
+ *  wins over the global `MCP_COMBINER` switch (presence, even empty, counts). Shared
+ *  cross-tool switches — NOT PI_-namespaced. */
+function combinerServes(name: string): boolean {
+    const key = "MCP_COMBINER_SERVES_" + name.toUpperCase().replace(/[-\s]/g, "_")
+    if (key in process.env) return truthy(process.env[key])
+    return truthy(process.env.MCP_COMBINER)
+}
+
+function onPath(cmd: string): boolean {
+    return spawnSync(cmd, ["--version"], { stdio: "ignore", env: process.env }).status === 0
+}
+
+/** Repo-root guess for `SVG_MCP_DEV=1` — three levels up from dist/index.js
+ *  (plugins/pi/dist → repo root), only if it holds svg-mcp source. */
+function inRepoSource(): string | undefined {
+    try {
+        const root = fileURLToPath(new URL("../../..", import.meta.url))
+        return existsSync(join(root, "pyproject.toml")) ? root : undefined
+    } catch {
+        return undefined
+    }
+}
+
+/** Resolve the argv that serves svg-mcp over streamable-http, or a `missing` runner. */
+function resolveServeArgv(port: string): { argv: string[]; missing?: string } {
+    const dev = env("SVG_MCP_DEV")
+    if (dev) {
+        if (!onPath("uv")) return { argv: [], missing: "uv" }
+        const project = dev !== "1" && existsSync(dev) ? dev : inRepoSource()
+        if (project) {
+            return {
+                argv: ["uv", "run", "--project", project, "svg-mcp", "--transport", "streamable-http", "--port", port],
+            }
+        }
+        // dev requested but no checkout given and no in-repo source — fall through.
+    }
+    if (!onPath("uvx")) return { argv: [], missing: "uvx" }
+    const ver = env("SVG_MCP_VERSION") ?? SVG_MCP_TOOL_VERSION
+    const spec = ver ? `svg-mcp@${ver}` : "svg-mcp"
+    return { argv: ["uvx", spec, "--transport", "streamable-http", "--port", port] }
+}
+
+// ── sharedserver lifecycle ─────────────────────────────────────────
+
+type Attachment = { binary: string; name: string }
+let attachment: Attachment | null = null
+let cleanupInstalled = false
+
+function installProcessCleanup() {
+    if (cleanupInstalled) return
+    cleanupInstalled = true
+    process.on("exit", () => detach())
+    for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"] as NodeJS.Signals[]) {
+        process.on(sig, () => {
+            detach()
+            process.kill(process.pid, sig)
+        })
+    }
+}
+
+function detach() {
+    if (!attachment) return
+    const { binary, name } = attachment
+    attachment = null
+    spawnSync(binary, ["unuse", name, "--pid", String(process.pid)], { stdio: "ignore", env: process.env })
+}
+
+// ── the extension ──────────────────────────────────────────────────
+
+export default function svgMcp(pi: ExtensionAPI): void {
+    const notify = env("PI_SVG_MCP_NOTIFY") !== "false"
+    const wantInstructions = env("PI_SVG_MCP_INSTRUCTIONS") !== "false"
+    const manage = env("PI_SVG_MCP_MANAGE") !== "false"
+    const name = env("PI_SVG_MCP_NAME") ?? DEFAULT_NAME
+    const served = combinerServes(name)
+
+    // ── directive: appended every turn (dup-guarded across turns) ──
+    pi.on("before_agent_start", (event) => {
+        if (!wantInstructions || !SVG_DIAGRAM_DIRECTIVE) return
+        if (DIRECTIVE_MARKER && event.systemPrompt.includes(DIRECTIVE_MARKER)) return
+        return { systemPrompt: `${event.systemPrompt}\n\n${SVG_DIAGRAM_DIRECTIVE}` }
+    })
+
+    // ── /svg-mcp command: inspect the extension (verb: system-prompt) ──
+    pi.registerCommand("svg-mcp", {
+        description: "svg-mcp extension — verb: system-prompt (show the injected directive)",
+        getArgumentCompletions: (prefix) => completeVerbs(prefix),
+        handler: (args, ctx) => {
+            const verb = args.trim()
+            if (verb === "" || verb === "system-prompt") {
+                showDirective(ctx, "svg-mcp", SVG_DIAGRAM_DIRECTIVE, wantInstructions)
+                return
+            }
+            ctx.ui?.notify?.(`svg-mcp: unknown verb "${verb}". Try: system-prompt`, "warn")
+        },
+    })
+
+    // Combiner-served or manage=false: nothing to launch. The directive still applies.
+    if (served || !manage) return
+
+    // ── process: launch on session_start, release on session_shutdown("quit") ──
+    pi.on("session_start", (_event, ctx) => {
+        if (attachment) return
+
+        const log = makeLog(ctx, notify)
+        const binary = resolveSharedserver(
+            {
+                label: "svg-mcp",
+                minVersion: SHAREDSERVER_MIN_VERSION,
+                installerUrl:
+                    "https://github.com/georgeharker/sharedserver/releases/latest/download/sharedserver-installer.sh",
+            },
+            env("SHAREDSERVER_BIN"),
+            process.env,
+            log,
+        )
+        if (!binary) {
+            log("error", "sharedserver binary not found; set $SHAREDSERVER_BIN, or PI_SVG_MCP_MANAGE=false")
+            return
+        }
+
+        const port = env("SVG_MCP_PORT") ?? String(DEFAULT_PORT)
+        const { argv, missing } = resolveServeArgv(port)
+        if (missing) {
+            log("error", `\`${missing}\` not on PATH; install uv (https://docs.astral.sh/uv/), or PI_SVG_MCP_MANAGE=false`)
+            return
+        }
+
+        const grace = env("PI_SVG_MCP_GRACE") ?? DEFAULT_GRACE
+        const useArgs = [
+            "use",
+            name,
+            "--pid",
+            String(process.pid),
+            "--grace-period",
+            grace,
+            "--metadata",
+            `pi-${process.pid}`,
+        ]
+        const logFile = env("PI_SVG_MCP_LOG")
+        if (logFile && logFile !== "none") useArgs.push("--log-file", logFile)
+        useArgs.push("--", ...argv)
+
+        installProcessCleanup()
+        const result = spawnSync(binary, useArgs, { stdio: "pipe", env: process.env })
+        if (result.error) {
+            log("error", `${name}: failed to spawn sharedserver (${result.error.message})`)
+            return
+        }
+        if (result.status !== 0) {
+            const stderr = result.stderr?.toString().trim()
+            log("error", `${name}: sharedserver use exited ${result.status}${stderr ? ` (${stderr})` : ""}`)
+            return
+        }
+
+        attachment = { binary, name }
+        log("info", `svg-mcp "${name}" attached on port ${port} (${argv.join(" ")})`)
+    })
+
+    pi.on("session_shutdown", (event: SessionShutdownEvent) => {
+        if (event.reason === "quit") detach()
+    })
+}
+
+// ── helpers ────────────────────────────────────────────────────────
+
+// The verbs the extension's slash command understands. `system-prompt` shows the
+// directive this extension injects — the show-command pattern from pi-custom-system-prompt,
+// since `before_agent_start` injections are per-turn and never appear in Pi's own
+// `/system-prompt` (which reports the base prompt only).
+const COMMAND_VERBS = ["system-prompt"]
+function completeVerbs(prefix: string): AutocompleteItem[] | null {
+    const p = prefix.trim()
+    const matches = COMMAND_VERBS.filter((v) => v.startsWith(p))
+    return matches.length ? matches.map((v) => ({ value: v, label: v })) : null
+}
+
+const SHOW_LIMIT = 1600
+function showDirective(ctx: ExtensionCommandContext, label: string, directive: string, enabled: boolean): void {
+    if (!directive) {
+        ctx.ui?.notify?.(`${label}: no directive bundled (instructions.txt missing)`, "warn")
+        return
+    }
+    const head = enabled
+        ? `${label} directive — injected into the system prompt on every turn (before_agent_start):`
+        : `${label} directive — injection is DISABLED this session; it would be:`
+    const body =
+        directive.length > SHOW_LIMIT
+            ? `${directive.slice(0, SHOW_LIMIT)}\n\n… (${directive.length} chars total)`
+            : directive
+    ctx.ui?.notify?.(`${head}\n\n${body}`, "info")
+}
+
+function makeLog(ctx: ExtensionContext, notify: boolean): LogFn {
+    return (level, message) => {
+        const line = `svg-mcp: ${message}`
+        if (notify && ctx.hasUI && ctx.ui?.notify) {
+            ctx.ui.notify(line, level === "error" ? "error" : level === "warn" ? "warn" : "info")
+        } else if (level === "error" || level === "warn") {
+            process.stderr.write(`${line}\n`)
+        }
+    }
+}

package/src/pi.ts

@@ -0,0 +1,70 @@
+// Narrow, local typing for the slice of Pi's extension API this plugin uses.
+//
+// Pi (badlogic/pi-mono, earendil-works/pi) ships its ExtensionAPI types with the
+// harness rather than as a standalone npm package we can depend on, so we declare
+// exactly the surface we touch — three lifecycle events, `registerCommand`, `exec`,
+// and `sendMessage`. Kept deliberately minimal: a wider mirror would rot against a
+// moving upstream. Signatures follow the published extension docs
+// (https://pi.dev/docs/latest/extensions).
+
+export type SessionStartReason = "startup" | "reload" | "new" | "resume" | "fork"
+export type SessionShutdownReason = "quit" | "reload" | "new" | "resume" | "fork"
+
+export type SessionStartEvent = { reason: SessionStartReason; previousSessionFile?: string }
+export type SessionShutdownEvent = { reason: SessionShutdownReason; targetSessionFile?: string }
+export type BeforeAgentStartEvent = { systemPrompt: string }
+export type BeforeAgentStartResult = { systemPrompt?: string } | void
+
+export type ExtensionContext = {
+    cwd: string
+    mode: "tui" | "rpc" | "json" | "print"
+    hasUI: boolean
+    signal?: AbortSignal
+    ui?: { notify?: (message: string, level?: "info" | "warn" | "error") => void }
+}
+
+/** Context handed to a command handler. Superset of ExtensionContext in practice; we
+ *  only read `signal`, `ui`, and `hasUI`. */
+export type ExtensionCommandContext = ExtensionContext
+
+export type AutocompleteItem = { value: string; label?: string }
+
+export type ExecResult = { stdout: string; stderr: string; code: number; killed: boolean }
+export type ExecOptions = { signal?: AbortSignal; timeout?: number; cwd?: string; env?: NodeJS.ProcessEnv }
+
+/** An LLM-visible message injected from a command. `display:true` shows it in the TUI;
+ *  `{triggerTurn:true, deliverAs:"steer"}` makes the model act on it this turn. */
+export type SendMessage = {
+    customType: string
+    content: string
+    display?: boolean
+    details?: Record<string, unknown>
+}
+export type SendMessageOptions = { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" }
+
+export type CommandSpec = {
+    description: string
+    handler: (args: string, ctx: ExtensionCommandContext) => void | Promise<void>
+    getArgumentCompletions?: (prefix: string) => AutocompleteItem[] | null
+}
+
+export interface ExtensionAPI {
+    on(
+        event: "session_start",
+        handler: (event: SessionStartEvent, ctx: ExtensionContext) => void | Promise<void>,
+    ): void
+    on(
+        event: "session_shutdown",
+        handler: (event: SessionShutdownEvent, ctx: ExtensionContext) => void | Promise<void>,
+    ): void
+    on(
+        event: "before_agent_start",
+        handler: (
+            event: BeforeAgentStartEvent,
+            ctx: ExtensionContext,
+        ) => BeforeAgentStartResult | Promise<BeforeAgentStartResult>,
+    ): void
+    registerCommand(name: string, spec: CommandSpec): void
+    exec(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>
+    sendMessage(message: SendMessage, options?: SendMessageOptions): void
+}