\n\n[](https://github.com/cyanheads/docgen-mcp-server/releases/latest/download/docgen-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=docgen-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvZG9jZ2VuLW1jcC1zZXJ2ZXIiXX0=) [](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)\n\n[](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)\n\n
\n\n---\n\n## Why docgen\n\nAn 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.\n\n## Tools\n\nFour 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.\n\n| Tool | Description |\n|:---|:---|\n| `docgen_render_pdf` | Render HTML, markdown, or a `{{key}}` template + data object to a downloadable PDF. |\n| `docgen_export_spreadsheet` | Render one or more named worksheets of row objects to a downloadable `.xlsx` workbook. |\n| `docgen_fill_form` | Fill the AcroForm fields of a supplied PDF (base64 or https URL) and optionally flatten it. |\n| `docgen_get_document` | Re-fetch a previously rendered document by the id a render/export/fill tool returned. |\n\n### `docgen_render_pdf`\n\nRender content to a downloadable PDF.\n\n- 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)\n- `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\n- 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\n- Returns a `DocumentEnvelope` with `pageCount`\n\n---\n\n### `docgen_export_spreadsheet`\n\nRender tabular data to an `.xlsx` workbook — the natural export stage for rows pulled from another server.\n\n- Each entry in `sheets[]` is a worksheet `name` plus an array of row objects (property → scalar string / number / boolean / null)\n- 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\n- An empty `rows` array yields a header-only sheet; an empty `sheets[]` is rejected (`empty_workbook`)\n- Returns a `DocumentEnvelope` with `sheetCount`\n\n---\n\n### `docgen_fill_form`\n\nFill the AcroForm fields of a supplied PDF and optionally flatten it.\n\n- 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\n- `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)\n- Names with no AcroForm counterpart come back in `unmatchedFields[]` rather than failing the call — correct them and re-render\n- Set `flatten: true` to bake the values in so the result is no longer editable\n- AcroForm only — XFA-based PDFs (some government forms) report `not_a_form`\n- Returns a `DocumentEnvelope` with `pageCount`, plus `unmatchedFields[]`\n\n---\n\n### `docgen_get_document`\n\nRe-fetch a stored document by id.\n\n- 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\n- Use it to recover a document whose inline copy was dropped (over the inline size limit) while it is still within its TTL\n- An expired or unknown id returns `document_expired`; ids are single-render and not reusable\n\n## Resources\n\n| Type | Name | Description |\n|:---|:---|:---|\n| 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. |\n\nThe 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.\n\n## Features\n\nBuilt on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):\n\n- Declarative tool and resource definitions — single file per primitive, framework handles registration and validation\n- Unified error handling — handlers throw, framework catches, classifies, and formats\n- Pluggable auth: `none`, `jwt`, `oauth`\n- Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`\n- Structured logging with optional OpenTelemetry tracing\n- STDIO and Streamable HTTP transports\n\ndocgen-specific:\n\n- No external API — a bundled rendering stack (`pdf-lib`, `exceljs`, `marked`), so renders are local and deterministic with no upstream to fail\n- 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\n- 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\n- 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\n- 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\n\nAgent-friendly output:\n\n- 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\n- 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\n- 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\n- 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\n\n## Getting started\n\nAdd the following to your MCP client configuration file. No API keys are required.\n\n```json\n{\n \"mcpServers\": {\n \"docgen-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"bunx\",\n \"args\": [\"@cyanheads/docgen-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_LOG_LEVEL\": \"info\"\n }\n }\n }\n}\n```\n\nOr with npx (no Bun required):\n\n```json\n{\n \"mcpServers\": {\n \"docgen-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@cyanheads/docgen-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_LOG_LEVEL\": \"info\"\n }\n }\n }\n}\n```\n\nOr with Docker:\n\n```json\n{\n \"mcpServers\": {\n \"docgen-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"docker\",\n \"args\": [\n \"run\", \"-i\", \"--rm\",\n \"-e\", \"MCP_TRANSPORT_TYPE=stdio\",\n \"ghcr.io/cyanheads/docgen-mcp-server:latest\"\n ]\n }\n }\n}\n```\n\nFor Streamable HTTP, set the transport and start the server:\n\n```sh\nMCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http\n# Server listens at http://localhost:3010/mcp\n```\n\nDocuments 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.\n\n### Prerequisites\n\n- [Bun v1.4.0](https://bun.sh/) or higher (or Node.js v24+).\n\n### Installation\n\n1. **Clone the repository:**\n\n```sh\ngit clone https://github.com/cyanheads/docgen-mcp-server.git\n```\n\n2. **Navigate into the directory:**\n\n```sh\ncd docgen-mcp-server\n```\n\n3. **Install dependencies:**\n\n```sh\nbun install\n```\n\n4. **Configure environment:**\n\n```sh\ncp .env.example .env\n# edit .env to override any defaults\n```\n\n## Configuration\n\nAll configuration is optional — docgen runs with no required environment variables.\n\n| Variable | Description | Default |\n|:---------|:------------|:--------|\n| `DOCGEN_DOCUMENT_TTL_SECONDS` | How long a rendered document is retrievable before it expires, in seconds. | `900` |\n| `DOCGEN_MAX_DOCUMENT_BYTES` | Hard ceiling on a single rendered artifact in bytes; exceeding it aborts the render. | `26214400` |\n| `DOCGEN_RENDER_TIMEOUT_MS` | Per-render wall-clock budget in milliseconds; exceeding it aborts the render. | `30000` |\n| `DOCGEN_INLINE_MAX_BYTES` | Artifacts at or under this byte size are returned inline as base64; larger ones omit it. | `5242880` |\n| `DOCGEN_PDF_ENGINE` | PDF rendering engine. Only `lightweight` is implemented; `chromium` is reserved and rejected at startup. | `lightweight` |\n| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |\n| `MCP_HTTP_PORT` | Port for the HTTP server. | `3010` |\n| `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |\n| `MCP_PUBLIC_URL` | Public origin behind a TLS proxy. (The `downloadUrl` envelope field is reserved for a future HTTP download route and is not emitted in this version.) | — |\n| `MCP_LOG_LEVEL` | Log level (RFC 5424). | `info` |\n| `STORAGE_PROVIDER_TYPE` | Storage backend for document bytes + metadata. | `in-memory` |\n| `OTEL_ENABLED` | Enable [OpenTelemetry instrumentation](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry) (spans, metrics, completion logs). | `false` |\n\nSee [`.env.example`](./.env.example) for the full list of optional overrides.\n\n> 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.\n\n## Running the server\n\n### Local development\n\n- **Build and run:**\n\n ```sh\n # One-time build\n bun run rebuild\n\n # Run the built server\n bun run start:stdio\n # or\n bun run start:http\n ```\n\n- **Run checks and tests:**\n\n ```sh\n bun run devcheck # Lint, format, typecheck, security, changelog sync\n bun run test # Vitest test suite\n bun run lint:mcp # Validate MCP definitions against spec\n ```\n\n### Docker\n\n```sh\ndocker build -t docgen-mcp-server .\ndocker run --rm -e MCP_TRANSPORT_TYPE=http -p 3010:3010 docgen-mcp-server\n```\n\nThe 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.\n\n## Project structure\n\n| Directory | Purpose |\n|:----------|:--------|\n| `src/index.ts` | `createApp()` entry point — registers the tools/resource and inits the render + storage services. |\n| `src/config` | Server-specific environment variable parsing and validation with Zod. |\n| `src/mcp-server/tools` | Tool definitions (`*.tool.ts`). |\n| `src/mcp-server/resources` | Resource definitions (`*.resource.ts`). |\n| `src/services/document` | The rendering stack (`RenderService`) and artifact store (`DocumentStore`), shared types, and the SSRF fetch guard. |\n| `tests/` | Unit and integration tests mirroring `src/`. |\n\n## Development guide\n\nSee [`CLAUDE.md`/`AGENTS.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:\n\n- Handlers throw, framework catches — no `try/catch` in tool logic\n- Use `ctx.log` for request-scoped logging, `ctx.state` for tenant-scoped storage\n- Register new tools and resources in `src/index.ts`'s `createApp()` arrays\n- One shared `DocumentEnvelope` across all delivery tools — keep the writers and reader interchangeable\n\n## Contributing\n\nIssues and pull requests are welcome. Run checks and tests before submitting:\n\n```sh\nbun run devcheck\nbun run test\n```\n\n## License\n\nApache-2.0 — see [LICENSE](LICENSE) for details.\n",
"bytes": 15256,
"sha": "e8602ec78a9c49f101676ea55f32e032ba21d30e215e6b7d768defd26dd02489",
"repo_slug": "cyanheads/docgen-mcp-server",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_cyanheads_docgen_mcp_server_06a86738/readme"
}