Why docgen

An agent can write a perfect invoice's HTML, a clean data table, or a filled-form field map as tokens — but it cannot emit bytes. docgen is the renderer that closes the gap: structured content in, a downloadable binary document out. It wraps no external API; the "service" is a bundled rendering stack (pdf-lib for PDF and form fill, exceljs for spreadsheets, marked for the markdown path). Every output is stored tenant-scoped with a short TTL and handed back as a stable resource URI plus inline base64 when small enough.

Tools

Four tools sharing one delivery shape — three renderers that write a stored document and one read that re-fetches by id. Every render/export/fill call returns a DocumentEnvelope (a documentId, a docgen://document/{id} resource URI, byte size, TTL, and inline base64 when the artifact is small enough); docgen_get_document returns the same envelope for an id you already hold.

docgen_render_pdf

Render content to a downloadable PDF.

• Provide exactly one source: { html } (raw HTML you compose — the recommended path), { markdown } (converted to HTML, then rendered), or { template, data } (a {{key}} template filled from a data object, with server-owned layout)
• pageOptions control size (A4 / Letter / Legal / A3 / A5, default Letter), orientation, per-side margins (CSS lengths like "10mm", "0.5in", "72pt"), header/footer text (supporting the {{page}}, {{total}}, {{date}} tokens), and automatic page numbers
• The lightweight engine renders structured layout (headings, paragraphs, lists, tables) but not arbitrary CSS — a degraded enrichment flag is set when unsupported styling is dropped, so the agent isn't misled about fidelity
• Returns a DocumentEnvelope with pageCount

docgen_export_spreadsheet

Render tabular data to an .xlsx workbook — the natural export stage for rows pulled from another server.

• Each entry in sheets[] is a worksheet name plus an array of row objects (property → scalar string / number / boolean / null)
• An optional per-column spec sets the header label, value type (string / number / date / boolean), column width, and an Excel number/date format string (e.g. "#,##0.00", "yyyy-mm-dd"); when omitted, columns derive from the first row's keys
• An empty rows array yields a header-only sheet; an empty sheets[] is rejected (empty_workbook)
• Returns a DocumentEnvelope with sheetCount

docgen_fill_form

Fill the AcroForm fields of a supplied PDF and optionally flatten it.

• Provide the source as exactly one of { base64 } or { url } — an https URL fetched behind an SSRF guard (private/loopback/link-local ranges blocked, application/pdf required, response size capped); base64 avoids the fetch entirely
• fields is an AcroForm field name → value map; names must match the PDF's internal field names exactly (case-sensitive), obtained from whoever supplied the form (docgen does not expose them)
• Names with no AcroForm counterpart come back in unmatchedFields[] rather than failing the call — correct them and re-render
• Set flatten: true to bake the values in so the result is no longer editable
• AcroForm only — XFA-based PDFs (some government forms) report not_a_form
• Returns a DocumentEnvelope with pageCount, plus unmatchedFields[]

docgen_get_document

Re-fetch a stored document by id.

• The documentId is obtainable only from an earlier docgen_render_pdf, docgen_export_spreadsheet, or docgen_fill_form result — it is not guessable or constructible
• Use it to recover a document whose inline copy was dropped (over the inline size limit) while it is still within its TTL
• An expired or unknown id returns document_expired; ids are single-render and not reusable

Resources

The resource is the stable-URI delivery surface for hosts that support resources. All document data is also reachable via the tool surface — docgen_get_document is the tool-only twin of this resource, reading the same store and returning the same envelope. Neither re-renders.

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool and resource definitions — single file per primitive, framework handles registration and validation
• Unified error handling — handlers throw, framework catches, classifies, and formats
• Pluggable auth: none, jwt, oauth
• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
• Structured logging with optional OpenTelemetry tracing
• STDIO and Streamable HTTP transports

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 is decided 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):