docgen-mcp-server AGENTS.md

Developer Protocol

Server: docgen-mcp-server Version: 0.2.2 Framework: @cyanheads/mcp-ts-core ^0.12.3 Engines: Bun ≥1.3.0, Node ≥24.0.0 MCP SDK: @modelcontextprotocol/server ^2.0.0 Zod: ^4.4.3

Read the framework docs first: node_modules/@cyanheads/mcp-ts-core/CLAUDE.md contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.

---

What this server does

docgen-mcp-server renders structured agent content into downloadable binary documents. The agent composes the content; the server prints the file a human downloads. Every render is stored tenant-scoped under a TTL and handed back as a DocumentEnvelope (a documentId + resource URI + inline base64 when small enough); a later call re-fetches it within the TTL.

Surface:

Definition	Kind	What it does
docgen_render_pdf	tool	HTML / markdown / {{template}}+data → PDF (lightweight pdf-lib engine). Sets a degraded enrichment flag when it drops unsupported styling (CSS, images, scripts).
docgen_export_spreadsheet	tool	One or more named row sheets → .xlsx (exceljs), with an optional per-column type/format spec.
docgen_fill_form	tool	Fill (and optionally flatten) the AcroForm fields of a supplied PDF — source as { base64 } or an { url } fetched behind an SSRF guard. Unmatched field names come back in unmatchedFields[].
docgen_get_document	tool	Re-fetch a previously rendered document by its documentId. Pure read; document_expired once the TTL lapses.
docgen://document/{documentId}	resource	The stable-URI delivery surface — a byte blob (real mime type) + a JSON metadata block.

Services (src/services/document/):

• render-service.ts — the bundled rendering stack (PDF, xlsx, form-fill); enforces the byte ceiling + per-render timeout and classifies failures into the typed reasons the tools declare.
• document-store.ts — mints opaque ids, persists bytes + metadata via tenant-scoped ctx.state under a shared TTL, builds the envelope. A leaked id never crosses the tenant boundary.
• fetch-guard.ts — SSRF-guarded PDF fetcher for the fill_form URL source: https-only, blocks private/loopback/link-local/metadata destinations by resolving DNS and checking the resolved IP, re-validates every redirect hop, enforces application/pdf, caps the body. Every failure path is normalized to a leak-free source_unfetchable error.
• html-blocks.ts — reduces HTML/markdown to a linear block model for the lightweight engine (no JS execution, no remote-resource fetch); flags degraded for anything it can't render.
• format-envelope.ts / types.ts / render-types.ts — the shared DocumentEnvelope formatter, domain types, and render-input schemas.