Pro édition

MCP Tools — référence approfondie

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 sans ce droit ne charge pas les classes de la capacité. Compare les éditions et obtiens une licence.

Il n’existe aucun indicateur de licence par fonctionnalité. Le code est livré avec l’édition Pro, et les huit outils s’enregistrent sous le palier pro lorsque le paquet Pro se résout au démarrage aux côtés de nextpdf/server.

Contrat de comportement

NextPDF Server découvre les paliers au démarrage en sondant la classe de fournisseur d’outils Pro ; si elle se résout, le serveur enregistre les huit outils sous le palier pro. Le paquet Pro n’est pas une dépendance dure du serveur, les outils Pro sont donc strictement optionnels par co-installation. L’enregistrement des paliers est indépendant : un palier manquant ou exclu par politique ne bloque jamais les autres.
Chaque outil déclare l’un des quatre niveaux de risque (safe, caution, review, approval-required). Une surcharge opérateur optionnelle ne peut qu’élever le niveau d’un outil, jamais l’abaisser ; le serveur journalise dans l’audit toute exécution au niveau caution ou supérieur. sign_pdf est approval-required.
L’entrée PDF se résout dans un ordre fixe : document_id depuis le magasin en mémoire, puis source en tant qu’URI data:, chemin du système de fichiers, ou base64 brut. Une entrée manquante renvoie une erreur de validation plutôt que de traiter un document vide.
sign_pdf produit une signature de référence PAdES B-B uniquement — pas d’horodatage, pas de validation à long terme. Les algorithmes pris en charge et l’enveloppe de transport de clé AES-GCM sont détaillés ci-dessous ; le déchiffrement échoue de manière fermée et l’outil n’utilise jamais le texte chiffré comme matériel de clé.
Voir les sections ci-dessous pour le détail complet de la découverte, du risque, de la résolution de source, par outil, et de la signature. Cette page ne décrit que le comportement observable de l’extérieur et le contrat d’outil publié.

Périmètre

Cette page est la référence opérateur et intégrateur des huit outils MCP Pro. Elle couvre le modèle de découverte, la sémantique risque/HITL que le serveur applique, les règles de résolution de source, l’enveloppe de transport de clé de signature, et le comportement de défaillance par outil. Elle ne décrit que le comportement observable de l’extérieur et le contrat d’outil publié. Pour le catalogue destiné à l’utilisateur, voir la page MCP publique.

Modèle de découverte et d’enregistrement

NextPDF Server découvre les fournisseurs de paliers au démarrage. Il détecte le palier Pro en sondant la classe de fournisseur d’outils Pro ; si la classe se résout, le serveur instancie le fournisseur et enregistre chaque outil qu’il renvoie sous le palier pro. Le paquet Pro n’est intentionnellement pas une dépendance dure du serveur — cela permet que le serveur open source reste installable sans le paquet propriétaire, et rend les outils Pro strictement optionnels par co-installation.

Le serveur isole l’enregistrement par palier. Si le paquet Pro est absent, les outils Core s’enregistrent tout de même ; un fournisseur de palier présent ne bloque pas les autres paliers. L’enregistrement des outils est également soumis à la liste d’autorisation de la politique de sécurité du serveur : un outil exclu par la politique n’est silencieusement pas enregistré et n’est pas compté dans le récapitulatif du palier. Le serveur expose un décompte par palier (core / pro / enterprise) à des fins de diagnostic et de journalisation.

Le fournisseur renvoie les huit outils dans un ordre fixe : extraction de texte, segmentation, comparaison, masquage des informations personnelles, remplissage de formulaire, relecture de formulaire, analyse d’accessibilité, signature. L’ordre est stable, mais les appelants ne doivent pas en dépendre — résous les outils par leur nom de protocole MCP.

Modèle de risque et sémantique HITL

Chaque outil déclare l’un des quatre niveaux de risque. Le serveur utilise le niveau déclaré pour l’application de la supervision humaine (HITL) :

Safe — en lecture seule, sans effet de bord. S’exécute automatiquement.
Caution — crée ou modifie un état en mémoire. S’exécute automatiquement avec une entrée de journal d’audit.
Review — produit une sortie qui pourrait être mal utilisée. S’exécute automatiquement, mais les instructions de la compétence d’agent la signalent pour que l’agent avertisse l’utilisateur.
Approval-required — destructeur, juridique ou critique pour la confidentialité. Le serveur exige une confirmation humaine explicite avant l’exécution.

Classifications des outils Pro : les cinq outils d’extraction/analyse (extract_text, segment_document, compare_pdfs, extract_form_data, check_accessibility) sont safe ; redact_pii et fill_form sont review ; sign_pdf est approval-required.

Le niveau de risque provient d’exactement deux sources : la propre déclaration de l’outil, et une surcharge opérateur optionnelle au runtime. La surcharge ne peut qu’élever le niveau de risque d’un outil (renforcer l’application) ; elle ne peut jamais l’abaisser. Le serveur journalise dans l’audit toute exécution au niveau caution ou supérieur. Le modèle de risque porte une version ; le serveur annonce cette version dans sa réponse d’initialisation afin que les clients puissent détecter un changement incompatible.

Ordre de résolution de source

Chaque outil qui prend un PDF l’accepte via l’une de trois formes d’entrée, résolues dans cet ordre :

document_id — le serveur récupère les octets depuis son magasin de documents en mémoire. Un id inconnu échoue avec une erreur explicite invitant l’appelant à créer d’abord le document.
source en tant qu’URI data: — l’outil décode le corps base64 après la virgule.
source en tant que chemin du système de fichiers — l’outil lit depuis le disque lorsque le chemin se résout en un fichier.
source en tant que chaîne base64 brute — l’outil accepte et décode uniquement une entrée suffisamment longue et de forme base64.

compare_pdfs applique la même résolution indépendamment à source_a et source_b, et accepte en outre une valeur document_id dans l’un ou l’autre emplacement de source. Si ni un document_id ni une source n’est fourni, l’outil renvoie une erreur de validation plutôt que de traiter un document vide.

Référence par outil

Outil	Risque	Entrées	Champs de résultat	Limite comportementale
`extract_text`	safe	PDF ; `page_start` / `page_end` optionnels indexés à partir de 1	texte, nombre total de pages	Couche de texte uniquement ; plages bornées au nombre réel de pages ; pas d’OCR
`segment_document`	safe	PDF	nombre de segments, liste de segments	Segments dérivés de la mise en page ; pas un arbre de structure de PDF balisé
`compare_pdfs`	safe	deux PDF	indicateur identique, total des changements, nombre de pages par document, régions (type, texte, index de page, index de ligne, texte de la contrepartie optionnel)	Diff de contenu textuel ; ni visuel ni binaire
`redact_pii`	review	PDF ; `types` optionnels (`email`, `phone`, `ssn`, `credit_card`)	indicateur de présence d’informations personnelles, nombre détecté, texte masqué, types balayés	Détection/masquage en couche de texte ; pas de masquage visuel ; basé sur motifs, non exhaustif
`fill_form`	review	table `fields` ; `pdf_filename` optionnel	document XFDF, nombre de champs	Produit du XFDF (ISO 19444-1) ; n’écrit pas les valeurs dans un PDF
`extract_form_data`	safe	PDF	nombre de champs, table de champs, note explicite lorsqu’il n’y en a aucun	Lit uniquement le XFDF embarqué
`check_accessibility`	safe	PDF	score structurel (0–100), problèmes, récapitulatif des segments	Heuristique structurelle avec références WCAG ; pas un verdict de conformité
`sign_pdf`	approval-required	PDF ; certificat PEM + clé PKCS#8 ; algorithme, nom du signataire, motif, enveloppe de transport optionnels	PDF signé, nombre de signatures, indicateur d’achèvement, algorithme, OID, condensat	Référence PAdES B-B uniquement ; pas d’horodatage, pas de LTV

Signature : algorithmes et transport de clé

sign_pdf produit une signature de référence PAdES B-B. Algorithmes pris en charge, acceptés à la fois en orthographe avec tiret bas et avec tiret :

RSA avec SHA-256 (par défaut).
RSA avec SHA-3 256 / 384 / 512 — nécessite une compilation d’OpenSSL prenant en charge SHA-3.
Ed25519 — nécessite l’extension libsodium ; la clé doit être un PEM PKCS#8 enveloppant la clé privée Ed25519.

L’outil rejette les identifiants non pris en charge et renvoie la liste des valeurs acceptées.

L’enveloppe de chiffrement de transport optionnelle permet à un appelant de faire transiter la clé privée par un transport qui n’est pas confidentiel de bout en bout. L’enveloppe est AES-GCM uniquement :

Clé symétrique : 16, 24 ou 32 octets (AES-128/192/256), encodée en base64.
Nonce : exactement 12 octets, encodé en base64.
Données authentifiées supplémentaires optionnelles, encodées en base64.
La charge utile private_key est le texte chiffré en base64 avec une balise d’authentification GCM de 16 octets en fin.

Le déchiffrement échoue de manière fermée : une non-concordance de balise d’authentification ou une charge utile malformée renvoie une erreur de déchiffrement, et l’outil n’utilise jamais le texte chiffré comme matériel de clé. L’outil rejette les tailles de clé ou de nonce erronées avant tout travail cryptographique.

Cas limites et mode FIPS

extract_text : l’outil borne une fin de plage de pages qui dépasse le document plutôt que de la rejeter, et normalise un début situé avant la première page à la première page.
compare_pdfs : un source_a ou source_b manquant renvoie une erreur de validation ; des documents identiques renvoient un résultat identique explicite sans aucun changement.
extract_form_data : les PDF sans flux XFDF embarqué renvoient un résultat à zéro champ avec une note explicative, et non une erreur.
redact_pii : une entrée non reconnue dans types est ignorée ; une liste entièrement non reconnue produit un balayage vide plutôt qu’un échec.
sign_pdf : un certificat ou une clé privée manquant échoue avant tout travail de signature ; l’outil vérifie les exigences d’algorithme (prise en charge SHA-3 par OpenSSL, libsodium pour Ed25519) au moment de la signature et les fait remonter sous forme d’erreurs explicites.
Mode FIPS : la disponibilité des algorithmes suit la compilation OpenSSL/libsodium de l’hôte. Dans une compilation contrainte FIPS, les algorithmes non approuvés échouent à la frontière cryptographique avec une erreur explicite plutôt que de se dégrader silencieusement. La couche MCP n’ajoute ni ne relâche aucune politique cryptographique — elle fait remonter la décision du fournisseur cryptographique de l’hôte.

Notes de runbook opérateur

Garde sign_pdf en approval-required. Vérifie qu’aucune surcharge opérateur n’élève involontairement le risque sur les outils safe — les surcharges ne font que renforcer, donc une surcharge accidentelle dégrade la disponibilité, pas la sécurité.
Rétention d’audit : chaque exécution au niveau review ou supérieur est journalisée dans l’audit par le serveur. Dimensionne ta rétention de journaux pour le volume d’appels redact_pii, fill_form et sign_pdf.
Choix de transport : lorsque tu fonctionnes sur un transport qui n’est pas confidentiel de bout en bout, exige l’enveloppe de transport de clé AES-GCM pour sign_pdf et traite le matériel de clé privée comme un secret dans la politique de journalisation des appels d’outils de ton agent.
Décomptes de paliers : utilise le décompte par palier du serveur pour affirmer au moment du déploiement que le palier Pro a enregistré huit outils ; un décompte de zéro indique que le paquet Pro ne s’est pas résolu.

Frontière d’édition

Le palier Pro contribue exactement huit outils MCP. L’édition Enterprise livre un palier MCP distinct avec ses propres outils — conformité, analyse forensique, santé de la validation à long terme, certification prête pour l’IA, et recherche/embedding de documents. Les entrées, sorties et internes des outils Enterprise sont hors périmètre ici et documentés avec l’édition Enterprise. Le serveur découvre les paliers indépendamment ; un palier manquant n’en désactive jamais un autre.

Frontière de publication

Cette page ne documente que 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 utilitaires, les tables de mécanismes, les noms de fichiers de runbook et les préfixes de ticket sont hors périmètre.