docgen-mcp-server

---

概述

通过 Agent 生成文档：将 HTML、Markdown 或模板数据渲染为 PDF，将行数据导出为 Excel，并填写 PDF 表单。所有操作都使用随附的技术栈（pdf-lib、exceljs、marked）在本地完成渲染。

工具

工具	描述
docgen_render_pdf	将 HTML、Markdown 或 {{key}} 模板及数据对象渲染为可下载的 PDF
docgen_export_spreadsheet	将一个或多个命名工作表的行对象渲染为可下载的 .xlsx 工作簿
docgen_fill_form	填写所提供 PDF（base64 或 https URL）的 AcroForm 字段，并可选择将其扁平化
docgen_list_form_fields	检查精确的 AcroForm 字段名称、类型、必填标记和选项，不更改 PDF
docgen_get_document	根据渲染/导出/填写工具返回的 ID，重新获取之前生成的文档

资源

资源	描述
docgen://document/{documentId}	按 ID 获取渲染后的文档——以 blob 形式提供原始字节，并附带 JSON 元数据块

所有文档数据也可通过工具访问——docgen_get_document 是此资源仅提供工具的对应版本。

功能参考

docgen_render_pdf _工具

• 必须且只能提供一个 source：{ html }、{ markdown } 或用于 {{key}} 插值的 { template, data }。pageOptions 可控制页面大小/方向、CSS 长度单位的页边距、页眉/页脚（{{page}}、{{total}}、{{date}}）和页码。
• 返回包含 pageCount 的 DocumentEnvelope；degraded: true 表示 CSS、图像或脚本被丢弃，或字符被替换为 ?。轻量级引擎可渲染标题、段落、列表和表格。
• 类型化错误：invalid_source、template_render_failed、document_too_large、render_timeout。

---

docgen_export_spreadsheet _工具

• 至少提供一个工作表，并为其指定唯一的 name（1–31 个字符）和标量 rows[]；空行会生成仅包含表头的工作表。可选的 columns[] 用于设置表头、类型（string / number / date / boolean）、宽度和 Excel 格式。
• 未提供 columns 时，会按首次出现的顺序使用所有行键。布尔列接受 true/1/yes/on 和 false/0/no/off（不区分大小写）；其他字符串会保留为文本。
• 返回包含 sheetCount 的 DocumentEnvelope。可能的错误类型：empty_workbook、invalid_sheet_name、document_too_large、render_timeout。

---

docgen_fill_form _工具

• 请恰好提供一个 sourcePdf：{ base64 } 或 { url }（提供 application/pdf 的公开 https 地址），以及一个将精确、区分大小写的 AcroForm 字段名称映射到值的 fields。扁平 PDF 或仅包含 XFA 的 PDF 会返回 not_a_form。
• 填充不熟悉的 PDF 前，请先使用 docgen_list_form_fields 获取精确的字段名称和选项。
• 返回包含 pageCount 和 unmatchedFields[] 的 DocumentEnvelope；unmatchedFields[] 列出没有匹配字段的名称。
• flatten: true 会使填入的值不可编辑（默认值为 false）。

---

docgen_list_form_fields _工具

• 接受与 docgen_fill_form 相同的 sourcePdf base64 或 URL 来源。返回 { fields: [{ name, type, required, options? }] }，不会修改 PDF 或存储文档。
• 类型包括：text、checkbox、dropdown、optionList、radioGroup、signature、button。只有 dropdown、optionList 和 radioGroup 条目包含 options；signature 和 button 仅用于发现字段。
• 嵌套名称会保留其精确路径。没有 AcroForm 字段的 PDF 会返回 not_a_form。

---

docgen_get_document _工具

• 提供先前渲染、导出或填充操作返回的 documentId（doc_ 加 24 个 URL 安全字符）。
• 重新获取其 DocumentEnvelope，不会再次渲染；过期或未知 ID 会返回 document_expired。

---

docgen://document/{documentId} _资源

• 使用渲染、导出或填充结果中的 documentId（doc_ 加 24 个 URL 安全字符）。
• 返回一个 base64 blob，其中包含文档的 MIME 类型和 JSON 元数据（documentId、byteSize、pageCount/sheetCount、createdAt、ttlSecondsRemaining）。读取与 docgen_get_document 相同的存储；过期或未知 ID 会返回 document_expired。

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），并提供支持可选 OpenTelemetry 追踪的结构化日志。

docgen 专属：

• 无外部 API — 使用内置渲染栈（pdf-lib、exceljs、marked），因此渲染在本地完成且结果确定，不会因上游服务故障而失败
• 四种文档交付工具共用一个 DocumentEnvelope；字段检查会直接返回其清单
• 有界渲染 — 字节上限（DOCGEN_MAX_DOCUMENT_BYTES）和超时时间（DOCGEN_RENDER_TIMEOUT_MS）会将失控的渲染转为带类型的错误，而不是一直挂起
• 按租户隔离且会过期的存储 — 只有创建文档的租户才能通过文档 ID 解析该文档；文档会过期，而不会不断累积
• 防 SSRF 的表单获取 — 两种表单工具都会检查每个地址，包括每次重定向，并拦截私有、环回和链路本地目标

便于 Agent 使用的输出：

• 双重呈现交付 — 信封中的每个字段都会同时出现在 structuredContent 和 Markdown 输出中，包括 documentId、资源 URI、大小和 TTL
• 按大小内联 — 仅当大小不超过 DOCGEN_INLINE_MAX_BYTES 时才会填充 inlineBase64；更大的文档通过资源 URI 交付
• 部分填充报告 — docgen_fill_form 会返回 unmatchedFields[]，让 Agent 知道哪些字段名称未匹配
• 带恢复提示的类型化错误（invalid_source、template_render_failed、document_too_large、render_timeout、not_a_form、source_unfetchable、document_expired 等）；语义验证使用 ValidationError（-32007），参数格式错误则使用 InvalidParams（-32602）

开始使用

将以下内容添加到 MCP 客户端配置文件中。无需 API 密钥。

{
  "mcpServers": {
    "docgen-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/docgen-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

也可以使用 npx（无需 Bun）：

{
  "mcpServers": {
    "docgen-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/docgen-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

也可以使用 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"
      ]
    }
  }
}

使用 Streamable HTTP 时，设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

所有传输方式均通过 docgen://document/{id} 资源交付文档（文档较小时也会内联提供 base64）。信封中的 downloadUrl 字段为未来的 HTTP 下载路由预留，本版本不会输出该字段。

先决条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）；开发使用 Bun v1.4.3。

安装

1. 克隆代码库：

git clone https://github.com/cyanheads/docgen-mcp-server.git

2. 进入目录：

cd docgen-mcp-server

3. 安装依赖项：

bun install

4. 配置环境：

cp .env.example .env
# edit .env to override any defaults

配置

所有配置均为可选项——docgen 无需任何必需的环境变量即可运行。

变量	描述	默认值
DOCGEN_DOCUMENT_TTL_SECONDS	渲染后的文档在过期前可供获取的时长，单位为秒。	900
DOCGEN_MAX_DOCUMENT_BYTES	单个渲染产物的字节数上限；超出时将中止渲染。	26214400
DOCGEN_RENDER_TIMEOUT_MS	每次渲染的最长耗时预算，单位为毫秒；超出时将中止渲染。	30000
DOCGEN_INLINE_MAX_BYTES	字节数不超过此值的产物会以 base64 内联返回；更大的产物则不包含内联内容。	5242880
DOCGEN_PDF_ENGINE	PDF 渲染引擎。目前仅实现了 lightweight；chromium 为预留选项，启动时会被拒绝。	lightweight
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务的端口。	3010
MCP_SESSION_MODE	HTTP 会话模式：auto、stateful 或 stateless。	stateless
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_PUBLIC_URL	TLS 代理后方的公共源地址。	—
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
LOG_TOOL_FAILURE_PAYLOADS	记录失败的参数/结果；根据键名进行脱敏，并限制为 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES 指定的大小（默认值为 16384）。自由格式的值可能仍包含机密信息。	false
STORAGE_PROVIDER_TYPE	文档字节数据和元数据的存储后端。	in-memory
OTEL_ENABLED	启用 OpenTelemetry 检测（追踪 span、指标、完成日志）。	false
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP 基础 URL；追踪数据使用 /v1/traces，指标使用 /v1/metrics。特定信号的端点会覆盖此设置。	—
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	可选的日志端点，按原样使用；基础 URL 不会启用日志导出。	—

完整的可选覆盖项列表请参阅 .env.example。

默认的内存存储会在每次重启时丢弃所有文档，此前的 ID 随后会返回 document_expired。若要在重启后保留文档，请将 STORAGE_PROVIDER_TYPE 指向持久化后端。

运行服务

本地开发

• 构建并运行：

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

• 运行检查和测试：

  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

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/docgen-mcp-server。默认会安装 OpenTelemetry 对等依赖——若要省略这些依赖，请使用 --build-arg OTEL_ENABLED=false 进行构建。

项目结构

目录	用途
src/index.ts	createApp() 入口——注册工具/资源，并初始化渲染和存储服务。
src/config	使用 Zod 解析并验证服务专属环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）。
src/mcp-server/resources	资源定义（*.resource.ts）。
src/services/document	渲染栈（RenderService）和产物存储（DocumentStore）、共享类型，以及 SSRF 抓取防护。
tests/	与 src/ 结构对应的单元测试和集成测试。

开发指南

开发指南和架构规则请参阅 CLAUDE.md/AGENTS.md。简要说明：

• 处理程序抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围内的日志，使用 ctx.state 存储租户范围内的数据
• 在 src/index.ts 的 createApp() 数组中注册新工具和资源
• 所有交付工具共用一个 DocumentEnvelope——确保写入器和读取器可以互换使用

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0——详情请参阅 LICENSE。