pdfnative-mcp: Instructions file for GitHub Copilot

pdfnative-mcp - Project Guidelines

Full context (architecture, tool schemas, output system, security design): docs/KNOWLEDGE_BASE.md. Don't duplicate it here. Repository rules shared by every coding agent: AGENTS.md — keep this file consistent with it. Contract for agents that use the server (tool catalogue, decision tree, token economy, error codes): docs/AGENT_CONTRACT.md.

Overview

MCP server bridging pdfnative 1.8.0 (pinned ^1.8.0) to AI clients over stdio or Streamable HTTP, on the MCP TypeScript SDK v2 (@modelcontextprotocol/server, MCP 2026-07-28 with automatic 2025-era fallback). 28 tools, 7 prompts, 47 error codes, 27 Unicode scripts. Current release 1.7.0 (TOOL_API_VERSION 1.7.0). Three runtime dependencies (pdfnative, the MCP SDK, zod) — never add one. Quality bar: production-grade OSS (strict TypeScript, strong validation, secure file IO, no egress except operator-configured TSA / OCSP / CRL endpoints, reproducible output, deterministic releases). Faithful thin wrapper: every PDF feature lives in the engine; never reimplement one, never over-promise (state engine limits in the tool description and ROADMAP.md).

Architecture (one line each)

• src/cli.ts — stdio (serveStdio) / Streamable HTTP (createMcpHandler) entry point; boot-time operator knobs.
• src/http.ts — Node http ↔ Web Request/Response bridge + Host/Origin loopback guard.
• src/auth.ts — opt-in HTTP bearer token (PDFNATIVE_MCP_HTTP_TOKEN, constant-time compare, 401 + WWW-Authenticate).
• src/base64.ts — base64 boundary helpers (data: URI tolerated, PEM-vs-DER and double-encoding hints).
• src/server.ts — TOOLS registry (+ annotations, _meta.examples), request handlers, dispatchOutput, classifyUnexpected (unexpected failure on PDF input → PDF_PARSE_FAILED), SERVER_INSTRUCTIONS, prompts, resources, cache hints, TOOL_API_VERSION.
• src/tools/* — one file per tool (JSON schema as const + parallel Zod + handler); inspect-layout.ts reuses the generate_basic_pdf block schema + layout fragment.
• src/network.ts — the only egress path: operator-configured TSA / OCSP / CRL providers + SSRF guard; URLs never come from tool arguments.
• src/blocks.ts — the 7 extended document blocks (table, image, link, toc, barcode, svg, formField) → 13 block kinds in total.
• src/layout.ts — pageSize / margins / headerTemplate / footerTemplate / compress / debug / encrypt / typography fragment shared by the nine document tools.
• src/typography.ts — the opt-in typography fragment (12 keys, all off by default; no hyphenation dictionary is installed).
• src/color.ts — shared colour fragment: hex / RGB plus CMYK operand strings (0–1) and percent tuples (0–100); toEngineColor().
• src/print.ts — shared print-production schema (boxes, bleed, marks + colour bars, userUnit, outputIntent RGB / CMYK / Gray, metadata, creationDate).
• src/pdfx.ts, src/pdfa.ts — conformance targets from the engine's own tuples; static PDF/X conflicts refused as VALIDATION_ERROR before the build.
• src/reproducible.ts — operator pin of the creation instant (PDFNATIVE_MCP_CREATION_DATE, then SOURCE_DATE_EPOCH); read once at boot.
• src/diagnostics.ts — diagnostics sink (strict / includeDiagnostics / embedFonts), escalate() by diagnostic code, mapBuildError.
• src/table.ts, src/barcode.ts, src/form.ts, src/image.ts — bodies shared by a dedicated tool and its inline block (image.ts checks magic bytes + PNG IHDR, 24 MiB per-call budget; embed_image stays unbounded).
• src/watermark.ts — text and/or image watermark + position; PDF/A-1b transparency guard.
• src/inflate-cap.ts — PDFNATIVE_MCP_MAX_INFLATE_BYTES → engine decompression cap (read once at boot; invalid value refuses to start).
• src/encryption.ts — shared password/encrypt schema + decrypt error mapper.
• src/chart.ts — shared charts v2 schema + mapper (add_chart and the generate_basic_pdf chart block).
• src/projection.ts — token-frugal responses (verbosity: 'summary', fields); src/cache.ts — opt-in response cache.
• src/resources.ts — native MCP resources over the sandbox output dir (pdfnative://output/…).
• src/output.ts — output mode (base64 or sandboxed file write); src/text.ts — newline sanitizer; src/errors.ts — ToolError, SecurityError, GovernanceError.
• scripts/* — TypeScript run by tsx: gate.ts, generate-samples.ts + verify-samples.ts (byte baseline), generate-pdfa-corpus.ts + validate-pdfa.ts / validate-pdfx.ts (conformance corpus), tool-shape.ts, verify-docs.ts, release-prepare.ts, build-claude-rules.ts. See scripts/README.md.
• tests/* — vitest, one *.test.ts per tool or module; _-prefixed shared fixtures; tests/_fixtures/ (tool shape, sample baseline, engine-surface matrix, build-error registry); tests/tools/ (repository tooling). Never regenerate tests/_fixtures/tool-shape.v1.5.0.json.
• examples/*.json — executable tools/call sequences (43), run by npm run examples:check and rendered into the sample baseline.