Pro édition

Outils MCP

En bref

NextPDF Pro ajoute huit outils Model Context Protocol (MCP) qui permettent à un agent IA d’exécuter des opérations PDF avancées via NextPDF Server. Les outils apparaissent automatiquement lorsque nextpdf/pro et nextpdf/server sont tous deux installés — aucune étape d’enregistrement distincte n’est nécessaire.

Disponibilité et licence

Cette capacité est livrée dans NextPDF Pro (nextpdf/pro) et s’active avec une enveloppe de licence de palier Pro. Un déploiement dépourvu de ce droit ne charge pas les classes de la capacité. Comparer les éditions et obtenir une licence.

La surface MCP de base — création de document, texte, tableaux, diagnostics — est livrée avec NextPDF Server open source et ne nécessite aucune licence. Les huit outils de cette page nécessitent une licence Pro et ne s’enregistrent que lorsque le paquet nextpdf/pro se résout au démarrage. Le palier d’outils pro restreint l’ensemble complet : chaque outil déclare son palier explicitement, et il n’y a aucun indicateur par outil — installer nextpdf/pro à côté de nextpdf/server active l’ensemble.

Contrat de comportement

Les huit outils MCP Pro s’enregistrent automatiquement lorsque nextpdf/pro et nextpdf/server se résolvent au démarrage, sous le palier pro, via le flux MCP standard tools/list et tools/call. Il n’y a aucun indicateur par outil et aucun changement de code dans l’application consommatrice.
Chaque outil accepte un PDF via un document_id issu d’un appel create_pdf antérieur, une source en ligne (chemin de fichier, base64 ou URI data:), ou — pour compare_pdfs — deux sources de ce type. Les outils renvoient du JSON structuré.
Chaque outil déclare une classe de risque HITL que le serveur applique : safe (auto-exécution, lecture seule), review (sortie susceptible d’être détournée) et approval-required. sign_pdf est approval-required et est retenu jusqu’à ce qu’un humain le confirme. Un opérateur ne peut que durcir la classe de risque d’un outil, jamais la relâcher.
sign_pdf ne produit qu’une signature PAdES B-B (baseline) — sans horodatage de confiance et sans matériel de validation à long terme. Les profils à long terme (B-LT / B-LTA), la garde matérielle des clés et la signature à piste d’audit relèvent du palier Enterprise et ne sont pas fournis par ces outils ; B-T (une signature horodatée) est disponible dans le moteur Core lorsqu’un fournisseur d’horodatage est configuré.
redact_pii effectue une détection et un masquage par motif dans la couche de texte, et non un caviardage visuel ; check_accessibility est une heuristique structurelle, et non un verdict de conformité PDF/UA ou WCAG. Le schéma d’entrée/sortie qui fait autorité est la réponse en direct tools/list du serveur, et non cette page.

Vue d’ensemble conceptuelle

NextPDF Server est la couche d’exécution MCP déterministe de NextPDF. Il découvre les fournisseurs d’outils au démarrage à l’aide d’une sonde d’existence de classe, si bien que le paquet Pro n’a pas besoin d’être listé dans les dépendances du serveur. Lorsque le paquet Pro est présent, le serveur enregistre ses huit outils sous le palier pro et les expose via le flux MCP standard tools/list et tools/call sur le transport que tu as configuré.

Chaque outil Pro accepte un PDF issu de l’une de trois sources : un document_id renvoyé par un appel create_pdf antérieur, une source en ligne (chemin de fichier, chaîne base64 ou URI data:), ou — pour l’outil de comparaison — deux sources de ce type. Les outils renvoient des résultats JSON structurés : texte extrait, régions de diff, texte masqué, arbres de segments, constats d’accessibilité ou un PDF signé.

Chaque outil Pro porte une classification de risque que le serveur utilise pour l’application humaine dans la boucle (HITL). Les outils d’analyse en lecture seule sont classés safe et s’auto-exécutent. Les outils qui génèrent une sortie qu’un appelant pourrait détourner sont classés review. L’outil de signature est classé approval-required, de sorte que le serveur le retient jusqu’à ce qu’un humain le confirme. L’outil lui-même déclare cette classification ; un opérateur ne peut que la durcir à l’exécution — jamais la relâcher.

La surface d’outils MCP est intentionnellement distincte du moteur PDF Pro. Les outils sont de fins adaptateurs : ils valident les entrées, résolvent le PDF, délèguent à un composant du moteur Pro et sérialisent le résultat. Ils ne constituent pas une seconde API pour le moteur et ne font pas partie de l’API PHP publique Pro — le point d’intégration pris en charge est le protocole MCP exposé par NextPDF Server.

Catalogue d’outils (huit outils Pro)

Les huit outils MCP Pro, par nom de protocole MCP. Les niveaux de risque suivent le modèle HITL du serveur : safe (auto-exécution, lecture seule), review (génère une sortie susceptible d’être détournée ; signalé dans les instructions de l’agent) et approval-required (doit être confirmé par un humain).

`extract_text`

Objet : Extraction de texte. Extrait la couche de texte d’un PDF, éventuellement limitée à une plage de pages indexée à partir de 1.
Entrées : Un PDF (document_id ou source) ; page_start et page_end optionnels.
Sorties : Le texte extrait et le nombre total de pages.
Risque : Safe. Lecture seule et idempotent.
Frontière : Extrait la couche de texte existante. Il n’effectue pas d’OCR sur les pages numérisées ou uniquement composées d’images.

`segment_document`

Objet : Segmentation structurelle. Découpe un PDF en sections logiques — titre, en-têtes, corps, tableaux, figures.
Entrées : Un PDF (document_id ou source).
Sorties : Un nombre de segments et une liste structurée de segments.
Risque : Safe. Lecture seule et idempotent.
Frontière : Segmentation structurelle fondée sur l’analyse de mise en page ; ce n’est pas un plan sémantique ni un arbre de structure de PDF balisé.

`compare_pdfs`

Objet : Diff structurel. Compare deux PDF et renvoie un diff structuré de leur contenu textuel.
Entrées : Deux PDF (source_a et source_b, chacun un chemin, du base64, un URI data ou un document_id).
Sorties : Un indicateur identique, le nombre total de changements, le nombre de pages par document et une liste de régions modifiées avec indices de page et de ligne.
Risque : Safe. Lecture seule et idempotent.
Frontière : Diff de contenu textuel. Il ne compare pas le rendu visuel, les polices incorporées ni la structure binaire.

`redact_pii`

Objet : Détection et masquage de PII. Détecte les informations personnellement identifiables dans la couche de texte d’un PDF et renvoie une vue masquée du texte.
Entrées : Un PDF (document_id ou source) ; un filtre types optionnel (email, phone, ssn, credit_card).
Sorties : Un indicateur de présence de PII, le nombre détecté, le texte masqué et la liste des types analysés.
Risque : Review. La sortie masquée pourrait être détournée si elle était traitée comme un document assaini.
Frontière : Il s’agit de détection et masquage par motif dans la couche de texte, et non d’un caviardage visuel. Il ne supprime ni n’écrase les glyphes dans le PDF rendu, et la correspondance par motif ne garantit pas que chaque occurrence de données sensibles est trouvée. Ne traite pas sa sortie comme une garantie de suppression complète des PII. Pour un caviardage au niveau du document qui détruit le contenu sous-jacent, utilise la surface de caviardage dédiée dans les outils du serveur open source ou l’édition Enterprise.

`fill_form`

Objet : Données de remplissage d’AcroForm. Génère des données XFDF (ISO 19444-1) qui remplissent les champs d’AcroForm PDF à partir d’une table de noms de champ vers des valeurs.
Entrées : Une table fields de nom de champ vers valeur chaîne ; un pdf_filename optionnel incorporé comme référence XFDF.
Sorties : Le document XFDF généré et le nombre de champs.
Risque : Review. Il produit des données de formulaire destinées à être appliquées à un document.
Frontière : Il produit du XFDF conforme aux normes ; il n’écrit pas lui-même les valeurs dans un PDF. Applique le XFDF avec n’importe quel lecteur ou outil de traitement conforme.

`extract_form_data`

Objet : Relecture d’AcroForm. Extrait les noms et valeurs des champs d’AcroForm depuis le XFDF incorporé dans un PDF.
Entrées : Un PDF (document_id ou source).
Sorties : Un nombre de champs et une table de noms de champ vers valeurs ; une note explicite lorsqu’aucune donnée de formulaire incorporée n’est présente.
Risque : Safe. Lecture seule et idempotent.
Frontière : Lit les flux XFDF (ISO 19444-1) incorporés. Un PDF qui ne contient des valeurs de formulaire que dans des objets AcroForm sans XFDF incorporé renvoie un résultat vide.

`check_accessibility`

Objet : Analyse d’accessibilité structurelle. Analyse l’accessibilité structurelle d’un PDF — en-têtes, paragraphes, tableaux et images — et signale les problèmes probables avec des références WCAG.
Entrées : Un PDF (document_id ou source).
Sorties : Un score structurel (0–100), une liste de problèmes et un résumé des segments.
Risque : Safe. Lecture seule et idempotent.
Frontière : Il s’agit d’une heuristique structurelle, et non d’un verdict de conformité. Un test complet de conformité PDF/UA et WCAG — arbre de balises, ordre de lecture, contraste de couleurs — nécessite un moteur d’accessibilité dédié. Un score élevé n’est pas une déclaration de conformité PDF/UA.

`sign_pdf`

Objet : Signature numérique PAdES B-B. Applique une signature numérique PAdES B-B (baseline) à un PDF à l’aide d’un certificat X.509 local et d’une clé privée.
Entrées : Un PDF (document_id ou source) ; un certificat PEM et une clé privée PKCS#8 ; un algorithme optionnel (RSA-SHA256 par défaut, RSA + SHA-3 256/384/512 ou Ed25519) ; un nom de signataire et une raison optionnels ; une enveloppe de transport AES-GCM optionnelle autour de la charge de clé privée.
Sorties : Le PDF signé, le nombre de signatures, un indicateur d’achèvement et l’algorithme, l’OID et l’empreinte utilisés.
Risque : Approval-required. La signature est une opération juridiquement significative et destructive ; le serveur exige une confirmation humaine explicite avant son exécution.
Frontière : Cet outil produit une signature PAdES B-B (baseline) — il n’incorpore ni horodatage de confiance ni matériel de validation à long terme. Les profils à long terme (B-LT / B-LTA), la garde de clés adossée au matériel et la signature à piste d’audit font partie de l’édition Enterprise ; B-T (une signature horodatée) est disponible dans le moteur Core lorsqu’un fournisseur d’horodatage est configuré. Voir la surface de signature Pro pour les capacités de signature plus larges du paquet Pro et l’édition Enterprise pour B-LT/B-LTA.

Comment les outils apparaissent

composer require nextpdf/pro
composer require nextpdf/server

Une fois les deux paquets installés, démarre NextPDF Server avec le transport de ton choix. Le serveur découvre le palier Pro au démarrage et les huit outils apparaissent dans la réponse MCP tools/list sous le palier pro, aux côtés des outils Core open source. Ton application ne nécessite aucun changement de code — la découverte s’exécute automatiquement et un palier manquant ne bloque jamais le chargement des autres.

Le schéma d’entrée et de sortie qui fait autorité pour chaque outil est le schéma que le serveur publie dans sa réponse tools/list. Traite cette réponse — et non cette page — comme le contrat : ce catalogue décrit l’intention et les frontières ; le schéma en direct décrit les noms et types de champs exacts.

Exemple de code — Démarrage rapide

Les outils Pro se consomment via le protocole MCP, et non via une API PHP Pro. L’intégration côté hôte consiste à démarrer NextPDF Server. Avec nextpdf/pro présent, les huit outils s’enregistrent par découverte à l’exécution — aucun câblage par outil — et l’hôte les sert ensuite aux agents.

<?php

declare(strict_types=1);

use NextPDF\Server\Mcp\McpServer;

require __DIR__ . '/vendor/autoload.php';

// Runtime discovery registers the Pro tier when nextpdf/pro is installed
// alongside nextpdf/server. The consuming application changes no code.
$server = McpServer::create();

// A Pro tool name resolves only when the Pro package is present.
$signTool = $server->getToolRegistry()->get('sign_pdf');

\fwrite(\STDERR, $signTool !== null
    ? "Pro MCP tools active.\n"
    : "Pro MCP tools unavailable; install nextpdf/pro.\n");

// Serve the MCP protocol over stdio (Claude Desktop, Cursor, local agents).
$server->run();

Exemple de code — Production

Durcis le chemin de démarrage. Charge un fichier de politique explicite, refuse de démarrer sur une surcharge de niveau de risque invalide, et confirme que le palier Pro est apparu avant de servir. Le câblage dans McpServer::create() lève InvalidArgumentException lorsqu’un bloc risk_level_overrides tente d’affaiblir un outil approval-required tel que sign_pdf, de sorte qu’une politique mal configurée échoue de manière verrouillée avant la boucle de service.

<?php

declare(strict_types=1);

use NextPDF\Server\Mcp\McpServer;
use NextPDF\Server\Tools\ToolInterface;

require __DIR__ . '/vendor/autoload.php';

// A downgrade of an approval-required tool's HITL gate is rejected at boot,
// never silently applied — the server refuses to start on such a policy.
try {
    $server = McpServer::create(__DIR__ . '/nextpdf-mcp.yaml');
} catch (\InvalidArgumentException $e) {
    \fwrite(\STDERR, 'Refusing to start: invalid MCP policy. ' . $e->getMessage() . "\n");
    exit(1);
}

// Confirm the Pro tier surfaced before advertising it to agents.
$signTool = $server->getToolRegistry()->get('sign_pdf');

if (!$signTool instanceof ToolInterface) {
    \fwrite(\STDERR, "nextpdf/pro is not resolving; Pro MCP tools are unavailable.\n");
    exit(1);
}

// sign_pdf is approval-required; the server holds it for human confirmation.
$risk = $signTool->riskLevel()->label();
\fwrite(\STDERR, "Pro MCP tools ready. sign_pdf risk: {$risk}.\n");

$server->run();

Conseils de production

Verrouillage HITL. Garde sign_pdf derrière une confirmation humaine. Le serveur l’impose à partir du niveau de risque déclaré de l’outil ; ne configure pas ton agent pour le contourner. Un opérateur ne peut que durcir le niveau de risque d’un outil, jamais le relâcher.
Gestion des sources. Privilégie document_id pour les documents déjà présents dans la session. Pour les données en ligne, les outils acceptent les URI base64 et data: ; les très grandes charges en ligne s’exécutent plus lentement qu’un document référencé.
Attentes en matière de PII. Fixe explicitement les attentes de l’appelant : redact_pii est une aide à la détection et au masquage, et non une garantie d’assainissement. Pour une suppression irréversible, route vers une surface de caviardage dédiée.
Clés de signature. Fournis les clés via l’enveloppe de chiffrement du transport lorsque le transport n’est pas confidentiel de bout en bout. Traite le matériel de clé privée comme un secret dans la politique de journalisation des appels d’outils de ton agent.
Journalisation d’audit. Les outils au-dessus du niveau safe sont journalisés en audit par le serveur. Assure-toi que ton déploiement conserve ces journaux conformément à tes exigences de conformité.

Cas limites

Les plages de pages d’extract_text sont indexées à partir de 1 et bornées au nombre réel de pages du document ; une fin hors plage ne provoque pas d’erreur.
compare_pdfs exige les deux sources ; en passer une seule renvoie une erreur de validation claire plutôt qu’un diff partiel.
extract_form_data renvoie un résultat « aucune donnée de formulaire incorporée » peuplé et explicite plutôt qu’une erreur pour les PDF sans XFDF incorporé.
sign_pdf rejette les identifiants d’algorithme non pris en charge avec la liste des valeurs prises en charge ; Ed25519 nécessite l’extension libsodium et les variantes SHA-3 nécessitent une compilation OpenSSL avec prise en charge de SHA-3.
check_accessibility attribue par conception un mauvais score aux PDF uniquement composés d’images — il signale l’absence d’une couche de texte lisible plutôt que d’échouer.

Notes de sécurité

L’outil de signature est le seul outil approval-required ; le serveur ne l’auto-exécutera pas.
L’enveloppe AES-GCM optionnelle autour de la clé privée authentifie la charge ; une non-correspondance de balise échoue de manière verrouillée avec une erreur de déchiffrement et ne se rabat jamais sur l’utilisation du texte chiffré.
redact_pii n’altère pas le PDF source ; il renvoie une représentation textuelle masquée. Ce n’est pas un substitut à la destruction de contenu.
L’outil valide les entrées avant tout travail du moteur ; il rejette les sources malformées, les URI data et les charges base64 avec des erreurs explicites.

Conformité

Les outils de formulaire produisent et consomment du XFDF conformément à ISO 19444-1:2019 (XML Forms Data Format).
sign_pdf produit une signature PAdES baseline (B-B) alignée sur la famille PAdES ETSI EN 319 142 ; les profils à long terme sont une capacité Enterprise, et B-T est disponible dans le moteur Core lorsqu’un fournisseur d’horodatage est configuré.
check_accessibility rapporte des constats avec des références aux critères de succès WCAG (par exemple 1.1.1, 1.3.1, 2.4.6) à titre d’orientation heuristique, et non d’attestation de conformité.

Frontière d’édition

NextPDF Pro contribue exactement huit outils MCP, tous au palier pro. L’édition Enterprise livre son propre ensemble distinct d’outils MCP au palier enterprise — couvrant la vérification de conformité, l’analyse forensique, la santé de la validation à long terme, la certification prête pour l’IA, ainsi que la recherche et le plongement de documents. Ces outils, leurs entrées et leurs rouages internes sortent du périmètre de cette page ; voir les outils MCP Enterprise. La documentation propre au serveur couvre les outils Core (open source) livrés avec lui. Le serveur découvre les trois paliers indépendamment, et un palier manquant ne désactive jamais les autres.

Note sur la frontière Enterprise

Pro contribue exactement huit outils MCP au palier pro. L’édition Enterprise livre un ensemble distinct d’outils MCP au palier enterprise (vérification de conformité, analyse forensique, santé de la validation à long terme, certification prête pour l’IA, recherche et plongement de documents) ainsi que les profils de signature horodatés/à long terme ; ceux-ci ne sont pas fournis par le palier Pro. Voir la section Frontière d’édition ci-dessus pour la répartition complète des paliers.

Repli / alternative dans le Core

NextPDF Server open source donne à tout agent IA un jeu d’outils PDF Core déterministe (création de document, texte, tableaux, diagnostics) sans licence. Les huit outils avancés de cette page sont des ajouts Pro. Voir /connect/tools/.

Frontière de publication

Cette page documente uniquement le comportement observable de l’extérieur et la surface d’API publique prise en charge. Les chemins d’espaces de noms internes, les classes auxiliaires, les tables de mécanismes, les noms de fichiers de runbook et les préfixes de tickets sortent du périmètre.