docgen mcp server AGENTS.md changelog

https://raw.githubusercontent.com/cyanheads/docgen-mcp-server/HEAD/AGENTS.md

− **Version:** 0.3.0− **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.15`− **Engines:** Bun ≥1.4.0, Node ≥24.0.0− **MCP SDK:** `@modelcontextprotocol/server` ^2.3.1− **Zod:** ^4.6.5− | `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_list_form_fields` | tool | Read-only field discovery from the same source: `{ fields: [{ name, type, required, options? }] }`. Types: text, checkbox, dropdown, optionList, radioGroup, signature, button. Only choice fields include options; signatures/buttons are discovery only. No PDF modification or document storage. |− - `fetch-guard.ts` — HTTPS PDF fetcher shared by both form tools. Vets all resolved addresses at every redirect hop, connects only to a vetted address using a fresh socket with TLS identity and Host preserved, blocks private/loopback/link-local/metadata destinations, enforces PDF content type, byte cap, deadline and cancellation. Failures are leak-free `source_unfetchable` errors.− docgen semantic reasons use `ValidationError` (`-32007`): empty_workbook, invalid_source, invalid_sheet_name, invalid_pdf_source, not_a_form, template_render_failed, document_too_large. Schema failures stay `InvalidParams` (`-32602`); fetch, timeout and missing-document codes remain unchanged.− Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. The directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand these development skills to every agent that installs it. Keep `skills/` free for skills meant f− **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.− | `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |− `bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings. MCPB is stdio-only — HTTP deployments are unaffected. Consume+ **Version:** 0.4.0+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.22`+ **Engines:** Bun ≥1.4.4, Node ≥24.0.0+ **MCP SDK:** `@modelcontextprotocol/server` ^2.4.0+ **Zod:** ^4.6.7+ | `docgen_fill_form` | tool | Fill (and optionally flatten) AcroForm fields from `{ base64 }` or an SSRF-guarded `{ url }`. Reports unmatched names, resolved aliases, checkbox notices, and dropdowns made editable; invalid assignments fail together as `invalid_field_value`. |+ | `docgen_list_form_fields` | tool | Read-only field discovery: names, types, required flags, choices, stored values, and available labels, length limits, checkbox on-states and first-widget pages. Types: text, checkbox, dropdown, optionList, radioGroup, signature, button. Signatures/buttons are discovery only. No PDF modification or document storage. |+ | `skill://docgen-guide/SKILL.md` | resource | Published guide for inspecting, filling, reviewing and flattening PDFs, also available through the Skills extension. |+ - `fetch-guard.ts` — HTTPS PDF fetcher shared by both form tools. Vets all resolved addresses at every redirect hop, tries vetted addresses with bounded TCP fallback, preserves TLS identity and Host, and blocks private/loopback/link-local/metadata destinations. Accepts PDF content type or octet-stream bodies starting with `%PDF-`; enforces byte cap, deadline and cancellation. Failures are leak-free `source_unfetchable` errors.+ - `form-assignments.ts` / `form-inventory.ts` — AcroForm name resolution, assignment validation and read-only field metadata.+ docgen semantic reasons use `ValidationError` (`-32007`): empty_workbook, invalid_source, invalid_sheet_name, invalid_pdf_source, not_a_form, invalid_field_value, template_render_failed, document_too_large. Schema failures stay `InvalidParams` (`-32602`); fetch, timeout and missing-document codes remain unchanged.+       form-assignments.ts               # Field-name resolution and aggregate assignment validation+       form-inventory.ts                 # Read-only AcroForm constraints and stored values+ Development skills live in `framework-skills/`. Read the matching skill directly, such as `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the registry.+ Published skills live in root `skills/` and teach tool workflows to agents using the server. Plugin installs, the npm package, Docker, and the MCPB carry this tree. `createApp({ skills: 'skills' })` also serves it to MCP clients. Author and validate published skills with `framework-skills/add-skill/SKILL.md`.+ **Agent skill directory:** Copy `framework-skills/` into the directory your development agent discovers (Claude Code: `.claude/skills/`, others: equivalent). The `maintenance` skill re-syncs these copies after framework updates.+ | `add-skill` | Author and validate a published skill in root `skills/` |+ | `bun run lint:packaging` | Check env-var parity, `.mcpbignore` coverage, plugin manifests and published skills |+ `bun run bundle` produces a stdio `.mcpb` extension for Claude Desktop. List build-only and local files in `.mcpbignore` with root-anchored patterns such as `/docs/`. Root `skills/` ships in the bundle. After packing, `scripts/clean-mcpb.ts` prunes dev dependencies, agent docs at dependency roots, platform-specific native bindings, node-gyp build metadata and framework build files. Nested runtime `skills/` modules stay in the bundle.+ - [ ] Keep the root Agent Plugins manifests `plugin.json` and `mcp.json` aligned with package metadata and the fixed stdio environment. Keep user-supplied values in the existing Claude and Codex overlays.+ - [ ] Validate any published `skills/` tree with `lint:packaging` and field-test its workflows.

https://raw.githubusercontent.com/cyanheads/docgen-mcp-server/HEAD/AGENTS.md

− **Version:** 0.2.4− **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.13`− **MCP SDK:** `@modelcontextprotocol/server` ^2.2.0− | `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). |− - `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.− `breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` renders a `· 🛡️ Security` badge and pairs with a `## Security` body section. When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.+ **Version:** 0.3.0+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.15`+ **MCP SDK:** `@modelcontextprotocol/server` ^2.3.1+ | `docgen_render_pdf` | tool | HTML / markdown / `{{template}}+data` → PDF (lightweight pdf-lib engine). Sets `degraded` for dropped styling or character replacement on any text surface; smart-punctuation transliteration alone remains non-degraded. |+ | `docgen_list_form_fields` | tool | Read-only field discovery from the same source: `{ fields: [{ name, type, required, options? }] }`. Types: text, checkbox, dropdown, optionList, radioGroup, signature, button. Only choice fields include options; signatures/buttons are discovery only. No PDF modification or document storage. |+ - `fetch-guard.ts` — HTTPS PDF fetcher shared by both form tools. Vets all resolved addresses at every redirect hop, connects only to a vetted address using a fresh socket with TLS identity and Host preserved, blocks private/loopback/link-local/metadata destinations, enforces PDF content type, byte cap, deadline and cancellation. Failures are leak-free `source_unfetchable` errors.+ - `source-pdf.ts` — shared source-pair validation, base64 decoding and guarded URL resolution.+ docgen semantic reasons use `ValidationError` (`-32007`): empty_workbook, invalid_source, invalid_sheet_name, invalid_pdf_source, not_a_form, template_render_failed, document_too_large. Schema failures stay `InvalidParams` (`-32602`); fetch, timeout and missing-document codes remain unchanged.+       source-pdf.ts                     # Shared form-source validation and resolution+       list-form-fields.tool.ts          # docgen_list_form_fields+ `breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` renders a `· 🛡️ Security` badge and pairs with a `## Security` body section — set it only for a security fix in this server's own source code, never for a dependency or transitive CVE bump (record those under `## Dependencies`). When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.

https://raw.githubusercontent.com/cyanheads/docgen-mcp-server/HEAD/AGENTS.md

− **Version:** 0.2.3− **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.6`− **MCP SDK:** `@modelcontextprotocol/server` ^2.0.0−   title: 'docgen-mcp-server', // display identity is the unscoped package name on every surface−     // Handlers throw; ctx.fail is typed against the declared reasons, recoveryFor mirrors the hint into content[].−       throw ctx.fail('document_expired', `No document found for id ${input.documentId}.`, {−         ...ctx.recoveryFor('document_expired'),−       });−   title: 'docgen-mcp-server',−       throw ctx.fail('document_expired', `No document found for id ${params.documentId}.`, {−         ...ctx.recoveryFor('document_expired'),−       });− | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |− | `ctx.inputs` | Reader over a retried request's responses — `.accepted(key, schema)`, `.view(key)`, `.state()`, `.dropped`. Empty on the first round. |− | `ctx.recoveryFor(reason)` | Typed lookup of the contract `recovery` for a declared reason. Returns `{ recovery: { hint } }` for known reasons, `{}` otherwise. Spread into `ctx.fail` data to mirror the contract hint into `content[]`. |− | `ctx.requestId` | Unique request ID. |− **Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, and the linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) and is the single source of truth for the agent's next move. Pass `ctx.recov−   if (!item) throw ctx.fail('no_match', `No item ${input.id}`, ctx.recoveryFor('no_match'));− | `devcheck` | Lint, format, typecheck, audit |− **Every release goes through a release PR, straight-through** — `git-wrapup`'s "Release PR mode", mode `straight-through`. One run: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the changelog entry plus a gates section); `release-and-publish` then fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. A caller's bri+ **Version:** 0.2.4+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.13`+ **MCP SDK:** `@modelcontextprotocol/server` ^2.2.0+   title: 'Get Document',+     // The framework fills the declared recovery hint on both error surfaces.+       throw ctx.fail('document_expired', `No document found for id ${input.documentId}.`);+   title: 'Rendered Document',+       throw ctx.fail('document_expired', `No document found for id ${params.documentId}.`);+ | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts JSON-serializable values; reads return their JSON form (a Date reads as its ISO string). |+ | `ctx.inputs` | Client-supplied responses — `.accepted(key, schema)`, `.view(key)`, `.state()`, `.dropped` — limited to the capabilities the client declared. Consent gates redeem a server-stored record bound to the operation, caller, target and content; see `api-context`. |+ | `ctx.clientCapabilities` | Capabilities declared for this request, or undefined. Decides whether to ask for optional context, never whether to skip consent. |+ | `ctx.recoveryFor(reason)` | Typed lookup of the contract `recovery` for a declared reason. Returns `{ recovery: { hint } }` for known reasons, `{}` otherwise. Use for direct handler tests or intentional hint overrides; production tool calls fill declared hints automatically. |+ | `ctx.requestId` | Framework-generated request ID carried by log records and error envelopes as `data.requestId`. The client's JSON-RPC id is logged separately as `jsonRpcId`. |+ **Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive a typed `ctx.fail(reason, …)`. Production tool calls fill `data.recovery.hint` from the matching declared reason when the throw has no hint; both `structuredContent` and `content[]` carry it. Explicit hints override the contract. `recovery` is required (≥ 5 words, lint-validated). Tool error envelopes carry `data.requestId`, and tool +   if (!item) throw ctx.fail('no_match', `No item ${input.id}`);+ **Every release goes through a release PR, straight-through** — `git-wrapup`'s "Release PR mode", mode `straight-through`. One run: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the release digest: theme line, `## Changes`, `## Gates`, changelog link last); `release-and-publish` then fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the