plan-export-mcp

The visual export engine for coding agents. Turn Markdown plans and Mermaid diagrams into beautiful, shareable documents.

---

The Problem

When coding agents (Cursor, Claude Code, Pi, Windsurf, Aider) draft implementation plans or audit codebases, they generate rich Markdown with code diffs, Mermaid architecture diagrams, GitHub callouts, and task lists.

• Inside your IDE: It looks crisp and structured.
• When sharing: Sending raw .md on WhatsApp, Slack, or Email turns into an unreadable mess. Generic PDF converters output 1990s-style plain black-and-white academic papers, break Mermaid diagrams, and strip dark themes.

plan-export-mcp bridges this gap. It gives your AI agent a native MCP tool to export plans with pixel-perfect visual fidelity.

---

Key Features

• High-Res PNG (Long Screenshot): Rendered at 2x Retina DPR. Ideal for WhatsApp and Slack because it renders inline in chat feeds without forcing teammates to download a PDF reader.
• VS Code Code Highlighting: Powered by Shiki with language badges and diff support (+ / - lines).
• GitHub Callouts & Alerts: Native support for > [!NOTE], > [!WARNING], > [!TIP], > [!IMPORTANT], and > [!CAUTION].
• Technical Typography: Visible Markdown prose uses Unicode arrows, comparisons, plus/minus, and ellipses while code, autolinks, HTML, and Mermaid stay unchanged.
• Private Artifact References: file://, vscode://, cursor://, and windsurf:// links render only their labels as inline code, without exposing local paths.
• Mermaid Architecture Diagrams: Client-side vector rendering directly embedded as SVG.
• Clean A4 PDF: Print-optimized with background colors and screen contrast preserved.
• Standalone HTML: Embedded styles; Mermaid diagrams load a pinned CDN script, and HTTPS images remain external. Fully offline viewing requires no Mermaid diagrams or external images.
• Dual Mode: Use it as an MCP server for AI agents or as a standalone CLI tool.

---

Installation and Usage

Prerequisites

• Node.js 20+
• npm, pnpm, or yarn

(Note: HTML exports run in pure Node.js with zero browser dependencies. For PDF/PNG rendering, Puppeteer manages a lightweight headless browser automatically or uses system Chromium if present).

---

1. Run with NPX (Recommended)

Runs on-demand without any global installation.

Claude Code (One-liner CLI)

claude mcp add plan-export npx -y @agmonetti/plan-export-mcp

Claude Desktop & Cursor (JSON Configuration)

Add to your claude_desktop_config.json or .cursor/mcp.json:

{
  "mcpServers": {
    "plan-export": {
      "command": "npx",
      "args": ["-y", "@agmonetti/plan-export-mcp"]
    }
  }
}

Tip (Linux/Docker): If Puppeteer cannot locate Chrome automatically, specify its path explicitly:

"env": {
  "PUPPETEER_EXECUTABLE_PATH": "/usr/bin/google-chrome-stable"
}

---

2. Install Globally from NPM

Ideal for instant startup without network latency on every invocation:

npm install -g @agmonetti/plan-export-mcp

{
  "mcpServers": {
    "plan-export": {
      "command": "plan-export-mcp"
    }
  }
}

---

3. Install from Source (Development)

Clone the repository and build locally:

git clone https://github.com/agmonetti/plan-export-mcp.git
cd plan-export-mcp
npm install
npm run build

{
  "mcpServers": {
    "plan-export": {
      "command": "node",
      "args": ["/path/to/plan-export-mcp/dist/index.js"]
    }
  }
}

---

Standalone CLI Usage

You can also run it directly in your terminal:

# Export to PNG and PDF in dark mode
npx @agmonetti/plan-export-mcp docs/plan.md --theme dark

# Export to all formats in light mode
npx @agmonetti/plan-export-mcp docs/plan.md --theme light --formats png,pdf,html --output-dir exports/

---

MCP Tool Reference: export_plan

Your AI agent can invoke this tool directly:

{
  "input": "docs/plans/feature-auth.md", // or raw markdown string
  "theme": "dark",                       // "dark" | "light" (default: "light")
  "formats": ["png", "pdf"],             // ["png", "pdf", "html"]
  "outputDir": "./exports",              // default: "./exports"
  "outputName": "auth-plan"              // default: derived from file
}

Remote images are format-dependent: standalone HTML may load HTTPS images from the viewer's network, while PNG/PDF browser rendering blocks external images. The browser permits the pinned Mermaid CDN script as a fallback if the bundled script is unavailable. Use embedded data: images for portable exports; local file URLs are not loaded.

Input files may be reached through symlinks to permitted targets. Path validation assumes a trusted local filesystem: it does not protect against another local process replacing files or directory entries concurrently between path resolution and opening. Do not accept input paths in directories an untrusted local user can modify.

---

Architecture

• Runtime: Node.js (>= 20) + TypeScript
• MCP SDK: @modelcontextprotocol/sdk (stdio transport)
• Highlighter: Shiki (VS Code TextMate engine)
• Diagrams: Mermaid.js
• Headless Engine: Puppeteer with intelligent fallback to system Chrome/Chromium.

---

License

MIT © 2025