@cyanheads/docgen-mcp-server

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.

Related MCP server: md2pdf-mcp

Capability reference

docgen_render_pdf tool

• Provide exactly one source: { html }, { markdown }, or { template, data } for {{key}} interpolation. pageOptions controls page size/orientation, CSS-length margins, headers/footers ({{page}}, {{total}}, {{date}}) and page numbers.

• Returns a DocumentEnvelope with pageCount; degraded: true signals dropped CSS, images or scripts, or character replacement with ? on body text, tables, headers or footers. Supported Latin-1 and existing smart-punctuation transliteration remain non-degraded. The lightweight engine renders headings, paragraphs, lists and tables.

• Typed failures: invalid_source, template_render_failed, document_too_large, render_timeout.

docgen_export_spreadsheet tool

• Supply at least one sheet with a unique name (1–31 characters) and scalar rows[]; empty rows yield a header-only sheet. Optional columns[] sets headers, type (string / number / date / boolean), width and Excel format.

• Omitted columns use all row keys in first-seen order. Boolean strings are trimmed and case-insensitive: true/1/yes/on and false/0/no/off/empty; unknown strings stay text. Blank numeric strings stay blank, and numeric date values stay decimal text.

• Returns a DocumentEnvelope with sheetCount. Typed failures: empty_workbook, invalid_sheet_name, document_too_large, render_timeout.

docgen_fill_form tool

• Provide exactly one sourcePdf: { base64 } or { url } (public https serving application/pdf), plus fields mapping exact, case-sensitive AcroForm field names to values. Flat or XFA-only PDFs return not_a_form.

• Obtain exact names and choice options with docgen_list_form_fields before filling an unfamiliar PDF.

• Returns a DocumentEnvelope with pageCount and unmatchedFields[] for names with no matching field.

• flatten: true makes the filled values non-editable (default false).

docgen_list_form_fields tool

• Accepts the same sourcePdf base64-or-URL source as docgen_fill_form. Returns { fields: [{ name, type, required, options? }] } without modifying the PDF or storing a document.

• Types: text, checkbox, dropdown, optionList, radioGroup, signature, button. Only dropdown, optionList and radioGroup entries include options; signatures and buttons are discovery only.

• Nested names retain their exact paths. PDFs without AcroForm fields return not_a_form.

docgen_get_document tool

• Supply the documentId an earlier render/export/fill returned (doc_ plus 24 url-safe characters).

• Re-fetches its DocumentEnvelope without rendering again; an expired or unknown id returns document_expired.

docgen://document/{documentId} resource

• Use the documentId from a render/export/fill result (doc_ plus 24 url-safe characters).

• Returns a base64 blob with the document's MIME type and JSON metadata (documentId, byteSize, pageCount/sheetCount, createdAt, ttlSecondsRemaining). Reads the same store as docgen_get_document; expired or unknown ids return 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 the four document delivery tools; field inspection returns its inventory directly

• 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 — both form tools vet every resolved address at each HTTPS redirect hop and open a fresh connection only to a vetted destination, preserving TLS identity and HTTP Host; private, loopback and link-local destinations are blocked

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

• Semantic validation uses ValidationError (-32007); malformed arguments use InvalidParams (-32602). Fetch errors remain ServiceUnavailable, timeouts Timeout, and expired documents NotFound.

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+); development uses Bun v1.4.3.

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:

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

• Run checks and tests:

  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.