PDF Reporter MCP

Multi-purpose MCP server for generating SVG diagrams and PDF documents. Render Mermaid diagrams to SVG, compose Markdown content with callout blocks, and produce styled PDF reports — all through standard MCP tools.

Features

• Mermaid to SVG — Render Mermaid diagrams to clean SVG via dedicated MCP tool
• Markdown to PDF — Convert Markdown content with custom callout blocks to styled PDF documents
• Callout Blocks — 9 callout types (idea, automation, warning, success, info, critical, business, expert, tip) using :::type Title syntax
• Pastel Theme — Professional styling with configurable pastel color palette
• Harmonious Diagrams — Pastel fills with tonal text and borders for visual consistency
• MCP Protocol — Standard MCP server with stdio and SSE transports

Quick Start

Installation

git clone https://github.com/alexmakeev/pdf-reporter-mcp.git
cd pdf-reporter-mcp
npm install

Usage

# Development
npm run dev

# Production
npm run build && npm start

# Docker (pre-built image)
docker run --rm -p 3000:3000 -e TRANSPORT=sse ghcr.io/alexmakeev/pdf-reporter-mcp:latest

# Docker (build locally)
docker compose up

MCP Client Configuration

{
  "mcpServers": {
    "pdf-reporter": {
      "command": "node",
      "args": ["/path/to/pdf-reporter-mcp/dist/server.js"]
    }
  }
}

Docker

Pre-built Docker images are published to GitHub Container Registry on every push to main.

Pull and Run

docker pull ghcr.io/alexmakeev/pdf-reporter-mcp:latest
docker run --rm -p 3000:3000 -e TRANSPORT=sse ghcr.io/alexmakeev/pdf-reporter-mcp:latest

MCP Client Configuration (Docker)

{
  "mcpServers": {
    "pdf-reporter": {
      "url": "http://localhost:3000/sse"
    }
  }
}

Available Tags

Tag	Description
latest	Latest build from main branch
main	Same as latest
v1.0.0	Specific release version
sha-abc1234	Specific commit build

Custom Configuration

docker run --rm \
  -p 3000:3000 \
  -e TRANSPORT=sse \
  -e THEME_PRIMARY_COLOR="#E81E63" \
  -v $(pwd)/output:/app/output \
  ghcr.io/alexmakeev/pdf-reporter-mcp:latest

---

MCP Tools

1. render_diagram

Render a single Mermaid diagram to SVG.

Input Parameters:

• mermaid (required, string) — Mermaid diagram definition

Output:

{
  "svg": "<svg>...</svg>"
}

2. render_content

Render Markdown content with callouts and diagram placeholders to HTML.

Input Parameters:

• content (required, string) — Markdown content with optional callout syntax
• diagrams (optional, object) — Pre-rendered SVG diagrams: { [name]: string }

Output:

{
  "html": "<article>...</article>"
}

3. generate_pdf

Generate a PDF document from HTML content.

Input Parameters:

• title (required, string) — Document title for cover page
• html (required, string) — Rendered HTML content
• subtitle (optional, string) — Document subtitle
• logo (optional, string) — Logo as data URI or file path
• template (optional, string, default: generic) — Template name
• options (optional, object) — PDF generation options:
  • pageSize (string, default: A4) — Page size (e.g. A4, Letter)
  • toc (boolean, default: false) — Generate table of contents
  • headerTemplate (string or false) — Custom header template HTML
  • footerTemplate (string or false) — Custom footer template HTML
  • margins (object) — Page margins with top, bottom, left, right (e.g. 17mm)

Output:

{
  "path": "/tmp/pdf-reporter-output/document-title.pdf",
  "size": "2.4 MB",
  "pages": 15
}

4. list_templates

List available report templates.

Output:

{
  "templates": [
    {
      "name": "generic",
      "description": "Universal report template with cover page, optional TOC, and markdown content"
    }
  ]
}

5. get_template_schema

Get the input schema for a specific template.

Input:

• template (required, string) — Template name

Output:

{
  "required": ["title", "html"],
  "optional": ["subtitle", "logo", "options"]
}

Workflow

The typical workflow is three steps:

1. render_diagram  →  Mermaid source  →  SVG string
2. render_content  →  Markdown + SVGs  →  HTML
3. generate_pdf    →  HTML + metadata  →  PDF file

Callout Syntax

:::info Important Note
This is an informational callout block.
Supports **markdown** inside.
:::

:::warning Caution
Be careful with this operation.
:::

:::success Achievement Unlocked
All systems operational.
:::

Supported Callout Types

Type	Emoji	Use Case
info	ℹ️	General information
idea	💡	New ideas and suggestions
automation	🤖	Automation features
warning	⚠️	Warnings and cautions
success	✅	Successful outcomes
critical	🔴	Critical alerts
business	💰	Business insights
expert	🔍	Expert recommendations
tip	💎	Tips and best practices

Example

See the demo report for a complete example featuring all capabilities.

Generated with examples/generate-demo.ts.

Theme Configuration

Variable	Default	Description
THEME_PRIMARY_COLOR	#4169E1	Primary accent color (Royal Blue)
THEME_COVER_COLOR	same as primary	Cover page accent color

The server auto-generates a pastel palette from the primary color for backgrounds, table headers, and cover elements. All text remains dark for readability.

Example:

export THEME_PRIMARY_COLOR="#E81E63"
export THEME_COVER_COLOR="#880E4F"
npm run dev

Architecture

MCP Input
  → Mermaid Renderer (mmdc CLI → SVG)
  → Callout Parser (:::syntax → HTML)
  → Markdown Renderer (marked + highlight.js)
  → Template Engine (Handlebars)
  → PDF Generator (Puppeteer)

Development

npm run dev          # Start dev server
npm test             # Run 164 tests
npm run test:watch   # Watch mode
npm run test:mutation # Mutation testing (Stryker)
npm run build        # TypeScript compilation

See docs/dev.md for the full developer guide.

Deployment

See docs/prod.md for Docker and Dokploy deployment instructions.

Testing

• 164 unit tests across 8 test suites (vitest)
• 94.21% mutation score via Stryker (minimum 89% per module)
• All tests run offline with mocked dependencies

Tech Stack

Component	Technology
Runtime	Node.js 20+, TypeScript (strict)
PDF	Puppeteer (headless Chrome)
Diagrams	@mermaid-js/mermaid-cli
Templates	Handlebars
Markdown	marked + highlight.js
MCP	@modelcontextprotocol/sdk
Tests	vitest + Stryker

License

MIT © Alexander Makeev