pdfnative-mcp: Instructions file for Claude Code

CLAUDE.md

Guidance for Claude Code (and other Claude-based agents) working in this repository. For the runtime tool catalogue and end-user recipes, read AGENTS.md; for architecture depth, docs/KNOWLEDGE_BASE.md. This file is about contributing to the codebase, not using the server.

What this is

pdfnative-mcp is a thin, faithful Model Context Protocol server wrapping the zero-dependency pdfnative PDF engine. TypeScript (strict, ESM-only), Node ≥ 22, @modelcontextprotocol/server (MCP SDK v2, protocol 2026-07-28 with automatic 2025-era fallback). 28 tools, 6 MCP prompts + resources. Three runtime dependencies (pdfnative, the MCP SDK, zod). Current release: 1.6.0 (on pdfnative 1.7.0).

Commands

npm run build          # tsc -p tsconfig.build.json  (emits dist/)
npm run typecheck:all  # tsc --noEmit  (covers src + tests)
npm run lint           # eslint src
npm test               # vitest run
npm run test:coverage  # vitest run --coverage  (enforces thresholds)
npm run examples:check # runs examples/*.json live through the tools/call handler
npm run validate:pdfa  # advisory: veraPDF over the 26-file PDF/A corpus (24 validated; skips when veraPDF is absent; VERAPDF_REQUIRED=1 fails closed; non-blocking in CI)
node scripts/tool-shape.mjs --write   # ONLY after a deliberate tools/list schema change — refreshes tests/_fixtures/tool-shape.json (catalogue parity gate)

Quality gate (run before every commit/PR):

npm run typecheck:all && npm run lint && npm run test && npm run test:coverage && npm run build

Coverage thresholds (global, in vitest.config.ts): statements 89 · branches 80 · functions 90 · lines 91. New code must keep the aggregate above these; never lower them.

Architecture map

• src/cli.ts — entry point (stdio via serveStdio by default; Streamable HTTP via createMcpHandler when PDFNATIVE_MCP_PORT is set; both with the SDK's legacy fallback).
• src/http.ts — Node http ↔ Web Request/Response bridge and the Host/Origin loopback guard for the HTTP transport (disconnect detection per response, not per socket). src/auth.ts — opt-in bearer token (PDFNATIVE_MCP_HTTP_TOKEN).
• src/server.ts — the TOOLS registry (with MCP annotations), request handlers on the low-level Server (not McpServer.registerTool; the read tools' output schemas are projectable — every property optional — so structuredContent always validates, asserted by tests/schema-conformance.test.ts), dispatchOutput (duck-typed result → content builder), SERVER_INSTRUCTIONS, SERVER_CACHE_HINTS, and the resources / prompts capabilities. TOOL_API_VERSION lives here.
• src/tools/<name>.ts — one file per tool: a hand-written JSON Schema as const, a parallel Zod schema (kept in lock-step), and the handler. src/tools/inspect-layout.ts (28th tool) reuses generate_basic_pdf's block schema and the layout fragment.
• Shared schema/util modules: src/network.ts (operator-configured TSA / OCSP / CRL providers + SSRF guard — the only egress path), src/blocks.ts (the 7 extended document blocks — table, image, link, toc, barcode, svg, formField — on top of the 6 basic ones; 13 kinds total), src/layout.ts (pageSize / margins / headerTemplate / footerTemplate / compress / debug / encrypt → PdfLayoutOptions; assertLayoutPdfACompatible), src/table.ts / src/barcode.ts / src/form.ts / src/image.ts (bodies shared by a dedicated tool and its inline block; form.ts maps textarea → multilineText; image.ts decodes + checks magic bytes and the PNG IHDR, ImageByteBudget 24 MiB per call — embed_image stays unbounded, blocks / watermarks use the bounded variant), src/inflate-cap.ts (PDFNATIVE_MCP_MAX_INFLATE_BYTES → engine cap; throwIfInflateCapError → PDF_PARSE_FAILED), src/print.ts (print-production print / outputIntent / metadata / creationDate schema + mappers), src/diagnostics.ts (PDF/A diagnostics sink, strict / includeDiagnostics / embedFonts, mapBuildError), src/encryption.ts (password + encrypt schema, mapDecryptError), src/chart.ts (charts v2 schema + toChartBlock), src/cms.ts (CMS parser), src/pdf-introspection.ts (signature widgets, /DSS, page boxes, annotations), src/pagetree.ts (mapPageTreeError — page-index errors → VALIDATION_ERROR), src/base64.ts (base64 / DER boundary decoding with agent-facing diagnostics — use it for every pdfBase64 / DER input), src/pdfa.ts, src/doc-features.ts, src/watermark.ts (text and/or image + position), src/projection.ts (token-frugal verbosity/fields), src/output.ts (sandboxed file write), src/resources.ts.
• tests/ — one *.test.ts per tool/module; shared fixtures are _-prefixed (_pdf-assert.ts, _cert-fixtures.ts, _pagetree-fixtures.ts, _encrypted-fixtures.ts, _ltv-fixtures.ts (offline mock PKI + RFC 3161 / OCSP / CRL providers), _tsa-server.ts (loopback TSA), _http-fixture.ts, _mcp-harness.ts). tests/http-modern.test.ts asserts the MCP 2026-07-28 conformance; tests/catalogue-parity.test.ts compares tools/list with the structural fixture tests/_fixtures/tool-shape.json; tests/catalogue-superset.test.ts proves the live catalogue is a superset of the published 1.5.0 one (tests/_fixtures/tool-shape.v1.5.0.json — never regenerate that file). New in 1.6.0: document-blocks, layout-options, inspect-layout, watermark, inflate-cap, error-codes (src ↔ AGENTS §6 inventory).