docgen-mcp-server

---

概要

エージェントからドキュメントを生成します。HTML、Markdown、またはテンプレートデータを PDF にレンダリングし、行データを Excel にエクスポートして、PDF フォームに入力できます。すべての処理は同梱のスタック（pdf-lib、exceljs、marked）を使い、ローカルで行われます。

ツール

ツール	説明
docgen_render_pdf	HTML、Markdown、または {{key}} テンプレートとデータオブジェクトを、ダウンロード可能な PDF にレンダリングします
docgen_export_spreadsheet	名前付きワークシートを 1 つ以上作成し、行オブジェクトをダウンロード可能な .xlsx ブックにレンダリングします
docgen_fill_form	指定された PDF（base64 または https URL）の AcroForm フィールドに入力し、必要に応じてフラット化します
docgen_list_form_fields	PDF を変更せずに、AcroForm の正確なフィールド名、型、必須フラグ、選択肢を確認します
docgen_get_document	レンダリング／エクスポート／入力ツールが返した ID を使って、以前にレンダリングしたドキュメントを再取得します

リソース

リソース	説明
docgen://document/{documentId}	ID で指定するレンダリング済みドキュメント。生バイト列を blob として、JSON メタデータブロックとともに提供します

すべてのドキュメントデータはツール経由でも取得できます。docgen_get_document は、このリソースに対応するツールのみの機能です。

機能リファレンス

docgen_render_pdf _ツール

• source は { html }、{ markdown }、または {{key}} の補間に使う { template, data } のいずれか 1 つだけを指定します。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[] を指定したシートを、少なくとも 1 つ指定してください。行が空の場合はヘッダーのみのシートになります。columns[] は省略可能で、ヘッダー、型（string / number / date / boolean）、幅、Excel の書式を指定します。
• columns を省略すると、すべての行キーが最初に出現した順に使用されます。Boolean 型の列では、大文字と小文字を区別せず 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 URL）のいずれか 1 つだけを指定し、AcroForm の正確な大文字と小文字を区別するフィールド名を値に対応付けた fields を指定してください。フラット PDF または XFA のみの PDF は not_a_form を返します。
• 見慣れない PDF に入力する前に、docgen_list_form_fields を使って正確な名前と選択肢を取得してください。
• pageCount と、一致するフィールドのない名前を示す unmatchedFields[] を含む DocumentEnvelope を返します。
• flatten: true にすると入力済みの値が編集不可になります（デフォルトは false）。

---

docgen_list_form_fields _ツール

• docgen_fill_form と同じ sourcePdf（base64 または URL）を受け付けます。PDF を変更したり、ドキュメントを保存したりせず、{ fields: [{ name, type, required, options? }] } を返します。
• 型：text、checkbox、dropdown、optionList、radioGroup、signature、button。options を含むのは dropdown、optionList、radioGroup のエントリのみです。署名とボタンは検出のみを目的とします。
• 入れ子になった名前は正確なパスを保持します。AcroForm フィールドがない PDF は not_a_form を返します。

---

docgen_get_document _ツール

• 以前のレンダリング／エクスポート／入力処理で返された documentId（doc_ に続く URL セーフな 24 文字）を指定してください。
• 再レンダリングせずに DocumentEnvelope を再取得します。期限切れまたは不明な ID は document_expired を返します。

---

docgen://document/{documentId} _リソース

• レンダリング／エクスポート／入力処理の結果から取得した documentId（doc_ に続く URL セーフな 24 文字）を使用してください。
• ドキュメントの MIME タイプを持つ base64 の blob と 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）を同梱しているため、レンダリングはローカルで決定論的に実行され、障害が発生する可能性のある上流サービスもありません。
• 4 つのドキュメント配信ツールで共有する DocumentEnvelope を使用します。フィールド検査では、その一覧を直接返します。
• レンダリングには上限があります。バイト数の上限（DOCGEN_MAX_DOCUMENT_BYTES）とタイムアウト（DOCGEN_RENDER_TIMEOUT_MS）により、処理が終わらないレンダリングをハングではなく型付きエラーにします。
• テナント単位で有効期限付きのストレージです。ドキュメント ID で解決できるのは作成したテナントのみで、ドキュメントは蓄積されずに期限切れになります。
• SSRF 対策付きのフォーム取得です。両方のフォームツールが、リダイレクトの各段階を含むすべてのアドレスを確認し、プライベート、ループバック、リンクローカルの宛先をブロックします。

エージェントに適した出力：

• 二重形式での配信です。documentId、リソース URI、サイズ、TTL を含むすべてのエンベロープフィールドが、structuredContent と Markdown 出力の両方に含まれます。
• サイズに応じたインライン出力です。inlineBase64 が設定されるのは DOCGEN_INLINE_MAX_BYTES 以下の場合のみで、それを超えるドキュメントはリソース URI 経由で配信されます。
• 部分入力の報告です。docgen_fill_form は unmatchedFields[] を返すため、エージェントは一致しなかったフィールド名を確認できます。
• 復旧のヒントを含む型付きエラー（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	レンダリング済みアーティファクト1つあたりの最大バイト数です。超過するとレンダリングを中止します。	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 instrumentation（スパン、メトリクス、完了ログ）を有効にします。	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 を使用します。書き込み側と読み取り側を相互に置き換えられる状態に保ってください。

コントリビューション

Issue を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細は LICENSE を参照してください。