Run environment diagnostics over NextPDF Connect

At a glance

Confirm that a NextPDF Connect server is healthy and has the capabilities your workflow needs before you run real work. Use this as the first step in any agentic pipeline. The tools, verified against the server tool registry, are diagnostic.doctor, diagnostic.capabilities, and diagnostic.verify. The registry exposes them under dotted protocol names, and a related diagnostic.inspect also exists. All are Core tools.

Install

composer require nextpdf/server

Bind a transport. You need veraPDF only for the optional compliance verification step. Structural verification does not need an external tool.

Conceptual overview

diagnostic.doctor returns a baseline health report: PHP version, loaded extensions, server version, active tier, and any warnings. Treat status as the gate. Proceed on ok, read warnings on warning, and stop on error.
diagnostic.capabilities lists the registered capabilities with their tier and runtime status (available, unavailable, degraded). The number of capabilities is runtime- and tier-dependent, so do not hard-code a total. Check each capability your workflow needs.
diagnostic.verify checks structural integrity: the PDF header, EOF marker, and cross-reference table. This is the document structure reached through the page tree (ISO 32000-2 §7.5). With compliance_flavour, it also invokes veraPDF.

A diagnostic result is a normal response in every transport (PHP Standard Recommendation 18, PSR-18 §p2).

API surface

Tool	Role	Risk tier
`diagnostic.doctor`	Environment health report	Safe
`diagnostic.capabilities`	Capability inventory with status	Safe
`diagnostic.verify`	Structural / compliance verification	Safe
`create_pdf`, `add_text`, `output_pdf`	Smoke-test a document	as documented elsewhere

These names are the registry’s protocol names. The tool catalog is the catalog of record. The installed tier determines which tools and capabilities exist, so never assert a fixed tool or capability count.

Code sample — Quick start

diagnostic.doctor (no arguments) → read status.
diagnostic.capabilities (no arguments) → confirm each needed capability is available.
create_pdf then add_text → a minimal smoke document.
diagnostic.verify with the document_id → structural checks.
Optionally diagnostic.verify with compliance_flavour: "4" → veraPDF.
output_pdf (base64) → destroy the smoke session.

Code sample — Production

Gate the pipeline on diagnostic.doctorstatus. Map each workflow dependency to a specific capability id, and assert available before you run the dependent steps. Treat degraded as a quality risk that needs a spot-check. Always run the structural diagnostic.verify. Run the compliance variant only when conformance matters. If veraPDF is absent, it returns a clear not-found result rather than a server defect.

Edge cases & gotchas

veraPDF absent. The compliance call returns an explicit not-found result. Structural checks still work. If you need compliance verification, install veraPDF and put it on the server process’s PATH.
veraPDF timeout. Large documents can trip the verification timeout. Reduce the document size, or raise the timeout in the server config.
degraded capability. A dependency is only partially available, so output quality may drop. Check the server logs for the fallback in use.
Doctor error. A critical requirement is unmet. Do not proceed.

Performance

Structural verification is fast. The compliance path spawns veraPDF and stays within the verification timeout. The wide budget reflects that subprocess.

Security notes

Diagnostic output reveals environment details: the PHP version, extensions, and tier. Treat it as operator-only, and do not show it to untrusted callers.

Conformance

Statement	Spec	Clause	reference_id
A diagnostic result is a normal transport response.	PSR-18	§p2
Structural integrity targets the page-tree-anchored structure.	ISO 32000-2	§7.5

The compliance variant runs veraPDF and reports its verdict. NextPDF does not assert conformance itself. The validator decides.

Commercial context

Not applicable — all diagnostic tools are Core.

Transport availability

Transport	Available	Notes
MCP (stdio)	Yes	Diagnostic results are tool results.
REST	Yes	Health endpoints map to these tools.
gRPC	Yes	Unary; the result carries the same status fields.

HITL risk tier

All three diagnostic tools are Safe: read-only, with no side effect. They never trigger the confirmation gate. The smoke-test output_pdf is base64-mode (Review, no gate).

Confirmation gate JSON envelope

Diagnostics never gate.

{ "allowed": true }