Overview

Document rendering built on a bundled stack — pdf-lib for PDF and AcroForm fill, exceljs for spreadsheets, marked for markdown. Render HTML, markdown, or template data to PDF, export tabular rows to xlsx, and fill AcroForm PDF forms from any MCP client. Runs as a stdio process or a local Streamable HTTP server.

Tools

Resources

All document data is also reachable via the tool surface — docgen_get_document is the tool-only twin of this resource.

Capability reference

docgen_render_pdf _tool

• Provide exactly one source: { html } (raw HTML, recommended), { markdown } (converted to HTML), or { template, data } (a {{key}} template filled from a data object)
• pageOptions sets size (A4 / Letter / Legal / A3 / A5, default Letter), orientation (default portrait), per-side margin as CSS lengths ("10mm", "0.5in", "72pt"), header/footer text supporting {{page}} / {{total}} / {{date}} tokens, and pageNumbers
• The lightweight engine renders structured layout (headings, paragraphs, lists, tables) but not arbitrary CSS, images, or scripts — sets degraded: true in the enrichment when unsupported styling is dropped
• Returns a DocumentEnvelope with pageCount
• Typed failures: invalid_source, template_render_failed, document_too_large, render_timeout

docgen_export_spreadsheet _tool

• Each entry in sheets[] is a worksheet name (1–31 chars, unique case-insensitively, no * ? : \ / [ ], no leading/trailing apostrophe) plus a rows[] array of property → scalar objects
• Optional columns[] sets header label, value type (string / number / date / boolean), width, and an Excel number/date format string; omitted columns derive from the first row's keys
• An empty rows[] yields a header-only sheet; an empty sheets[] is rejected as empty_workbook
• Returns a DocumentEnvelope with sheetCount
• Typed failures: empty_workbook, invalid_sheet_name, document_too_large, render_timeout

docgen_fill_form _tool

• Provide the source PDF as exactly one of { base64 } (whitespace and an optional data:application/pdf;base64, prefix tolerated) or { url } — an https URL fetched behind an SSRF guard that resolves DNS, blocks private/loopback/link-local destinations, re-validates every redirect hop, and requires application/pdf
• fields is an AcroForm field name → value map; names are case-sensitive and must match the PDF's internal field names exactly
• Names with no AcroForm counterpart come back in unmatchedFields[] instead of failing the call
• flatten: true bakes the values in so the result is no longer editable (default false)
• AcroForm only — a flat or XFA-based PDF returns not_a_form
• Returns a DocumentEnvelope with pageCount, plus unmatchedFields[]

docgen_get_document _tool

• documentId must match doc_ followed by 24 url-safe characters — the format returned by docgen_render_pdf, docgen_export_spreadsheet, or docgen_fill_form; not guessable or constructible
• Pure read — re-fetches the same DocumentEnvelope, useful when an earlier response omitted inlineBase64 (over the inline threshold)
• An expired or unknown id returns document_expired; ids are single-render and not reusable

docgen://document/{documentId} _resource

• documentId format: doc_ followed by 24 url-safe characters, obtained from a docgen render/export/fill tool result
• Returns two content items: the raw bytes as a blob (real mime type — PDF or xlsx) plus a JSON metadata block (documentId, byteSize, pageCount/sheetCount when applicable, createdAt, ttlSecondsRemaining)
• Reads the same tenant-scoped store as docgen_get_document and never re-renders
• An expired or unknown id returns document_expired

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

docgen-specific:

• No external API — a bundled rendering stack (pdf-lib, exceljs, marked), so renders are local and deterministic with no upstream to fail
• One shared DocumentEnvelope across all four tools — the three writers and the reader are interchangeable to the agent, and the resource-URI vs. inline-base64 delivery decision lives in one place
• Bounded renders — a per-document byte ceiling (DOCGEN_MAX_DOCUMENT_BYTES) and a wall-clock timeout (DOCGEN_RENDER_TIMEOUT_MS) turn a runaway render into a typed, recoverable error instead of a hang
• Tenant-scoped, TTL-bounded storage — a document id minted for one tenant resolves only for that tenant; outputs are downloads, not records, so they expire rather than accumulate
• SSRF-guarded form fetch — docgen_fill_form with a URL source resolves DNS and checks the destination IP before fetching, blocking private/loopback/link-local ranges

Agent-friendly output:

• Dual-surface delivery — every envelope field lands in both structuredContent and the format() markdown twin, so tool-only and resource-only clients both see the documentId, resource URI, inline-availability status, size, and TTL
• Inline-vs-resource by size — inlineBase64 is populated only at or under DOCGEN_INLINE_MAX_BYTES, so a large workbook isn't base64-inlined into a tool result; above the threshold, delivery is via the resource URI
• Partial-fill reporting — docgen_fill_form returns unmatchedFields[] so the agent learns which field names didn't land and can correct and re-render rather than assuming a clean fill
• Typed error contract with recovery hints — each tool declares its failure surface (invalid_source, template_render_failed, document_too_large, render_timeout, not_a_form, source_unfetchable, document_expired, …) with actionable next-step text

Getting started

Add the following to your MCP client configuration file. No API keys are required.

{
  "mcpServers": {
    "docgen-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/docgen-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "docgen-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/docgen-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "docgen-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/docgen-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Documents are delivered by the docgen://document/{id} resource (and inline base64 when small enough) over every transport. The envelope's downloadUrl field is reserved for a future HTTP download route and is not emitted in this version.

Prerequisites

• Bun v1.4.0 or higher (or Node.js v24+).

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/docgen-mcp-server.git

2. Navigate into the directory:

cd docgen-mcp-server

3. Install dependencies:

bun install

4. Configure environment:

cp .env.example .env
# edit .env to override any defaults

Configuration

All configuration is optional — docgen runs with no required environment variables.

See .env.example for the full list of optional overrides.

Documents are stored in ctx.state, which the in-memory provider keeps in process memory — a restart drops every stored document, and an id minted before the restart returns document_expired. This is intended (outputs are downloads, not records); for durable retention across restarts, point STORAGE_PROVIDER_TYPE at a persistent backend.

Running the server

Local development

• Build and run:

  sh

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• Run checks and tests:

  sh

  bun run devcheck   # Lint, format, typecheck, security, changelog sync
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t docgen-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=http -p 3010:3010 docgen-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/docgen-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Development guide

See CLAUDE.md/AGENTS.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
• Register new tools and resources in src/index.ts's createApp() arrays
• One shared DocumentEnvelope across all delivery tools — keep the writers and reader interchangeable

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.