docgen-mcp-server

<div align="center">
  <h1>@cyanheads/docgen-mcp-server</h1>
  <p><b>Render HTML/markdown to PDF, export rows to xlsx, and fill AcroForm PDFs via MCP. STDIO or Streamable HTTP.</b>
  <div>4 Tools • 1 Resource</div>
  </p>
</div>

<div align="center">

[![Version](https://img.shields.io/badge/Version-0.2.2-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/docgen-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/docgen-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/docgen-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)

</div>

<div align="center">

[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/docgen-mcp-server/releases/latest/download/docgen-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=docgen-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvZG9jZ2VuLW1jcC1zZXJ2ZXIiXX0=) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22docgen-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fdocgen-mcp-server%22%5D%7D)

[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)

</div>

---

## 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.

| Tool | Description |
|:---|:---|
| `docgen_render_pdf` | Render HTML, markdown, or a `{{key}}` template + data object to a downloadable PDF. |
| `docgen_export_spreadsheet` | Render one or more named worksheets of row objects to a downloadable `.xlsx` workbook. |
| `docgen_fill_form` | Fill the AcroForm fields of a supplied PDF (base64 or https URL) and optionally flatten it. |
| `docgen_get_document` | Re-fetch a previously rendered document by the id a render/export/fill tool returned. |

### `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

| Type | Name | Description |
|:---|:---|:---|
| Resource | `docgen://document/{documentId}` | A rendered document by id — the raw bytes as a `blob` (with the document's real mime type) plus a JSON metadata block. Readable until the document TTL expires. |

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`](https://www.npmjs.com/package/@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.

```json
{
  "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):

```json
{
  "mcpServers": {
    "docgen-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/docgen-mcp-server