Enterprise édition

Outils MCP

En bref

NextPDF Enterprise ajoute onze outils MCP au serveur NextPDF Connect. Ils donnent aux assistants IA et aux frameworks d’agents un accès direct et typé au moteur Enterprise : contrôles de politique de conformité, forensique PDF, contrôles de santé LTV, estampillage de préparation à l’IA, découpage sensible à l’AST, ainsi qu’ingestion et recherche RAG. Chaque outil déclare son propre niveau de risque et sa posture en lecture seule, afin que ton hôte MCP puisse contrôler, journaliser et auditer l’activité des agents en toute confiance. Les échecs ne se manifestent jamais sous forme d’exceptions ; les agents reçoivent toujours un résultat structuré et analysable.

Disponibilité et licence

Cette fonctionnalité est fournie dans NextPDF Enterprise (nextpdf/enterprise) et s’active avec une enveloppe de licence de niveau Enterprise. Un déploiement dépourvu de ce droit ne charge pas les classes de la fonctionnalité. Comparer les éditions et obtenir une licence.

Installation

composer require nextpdf/enterprise:^3

L’hôte MCP lui-même est NextPDF Connect, fourni dans le paquet nextpdf/server ; voir Installation de Connect. Lorsque les deux paquets sont présents, le registre d’outils du serveur découvre automatiquement NextPDF\Enterprise\McpToolProvider et enregistre les onze outils Enterprise. Aucun code de câblage n’est requis. Si nextpdf/server est absent, le fichier du fournisseur se termine prématurément et rien n’est chargé.

Les outils de traitement par lots et RAG requièrent en outre le sidecar Spectrum. Configure-le via les variables d’environnement lues par NextPDF\Enterprise\Mcp\SpectrumClientFactory : SPECTRUM_URL (http://127.0.0.1:7800 par défaut), SPECTRUM_TIMEOUT (30.0 secondes par défaut), SPECTRUM_AUTH_TOKEN et SPECTRUM_APP_SECRET.

Vue d’ensemble conceptuelle

Le Model Context Protocol (MCP) est un protocole ouvert qui permet aux assistants IA et aux frameworks d’agents d’appeler des outils typés exposés par un serveur. Au lieu de coller des octets PDF dans un prompt en espérant que ça marche, un agent appelle un outil nommé avec une charge utile validée par schéma JSON et reçoit un résultat déterministe et structuré. NextPDF Connect est ce serveur pour les PDF ; le paquet Enterprise étend son catalogue avec les outils ci-dessous. Chaque outil est un mince habillage des mêmes API Enterprise que ton code PHP appelle directement, de sorte qu’un contrôle exécuté par un agent et un contrôle exécuté par le code produisent le même verdict.

Catalogue des outils

Outil MCP	Classe	Rôle	Risque	Lecture seule
`compliance_check`	`ComplianceCheckTool`	Valide un PDF selon une politique nommée : `pdfa4`, `pdfa4e`, `pdfa4f`, `pades-baseline`, `ltv-health`, `eidas-qualified`, `zugferd`, `fda-part11`, et quatre variantes `sec-17a4`.	Review	oui
`batch_compliance_check`	`BatchComplianceCheckTool`	Vérifie de nombreux PDF selon les politiques `pdfa`, `pades` ou `zugferd` en un seul lot du sidecar Spectrum.	Safe	oui
`forensic_analyze`	`ForensicAnalyzeTool`	Rapporte l’historique des révisions, les mises à jour incrémentielles et les événements de modification pour la détection d’altération.	Safe	oui
`batch_forensic_analyze`	`BatchForensicAnalyzeTool`	Exécute une analyse forensique sur de nombreux PDF en un seul lot du sidecar.	Safe	oui
`ltv_health_check`	`LtvHealthCheckTool`	Vérifie qu’un PDF signé contient le matériel de validation à long terme : dictionnaire DSS, réponses OCSP, entrées CRL, entrées VRI et magasins de certificats.	Safe	oui
`ai_ready_certify`	`AiReadyCertifyTool`	Verdict de préparation à l’IA défini par le produit, en lecture seule, sur quatre critères : intégrité forensique, présence de signature, validité LTV, absence de chiffrement.	Review	oui
`certify_ai_ready`	`CertifyAiReadyTool`	Verdict de préparation défini par le produit sur trois critères (les quatre de l’outil en lecture seule moins l’intégrité forensique - par conception, puisque cet outil réécrit le fichier qu’il estampille) et ajoute une estampille de provenance XMP ; renvoie le PDF estampillé en base64.	Review	non
`ast_aware_chunk`	`AstAwareChunkTool`	Découpe un PDF en fragments ancrés pour citation le long des limites de titres, avec identifiant de nœud, index de page et boîte englobante par fragment.	Review	oui
`audit_ast_mutations`	`AuditAstMutationsTool`	Récupère la piste d’audit des mutations de l’AST d’un document par hachage source SHA-256.	Review	oui
`embed_documents`	`EmbedDocumentsTool`	Ingère des PDF dans une collection RAG : analyse, découpage, plongement, indexation. Modifie l’état de la collection.	Caution	non
`search_documents`	`SearchDocumentsTool`	Récupération hybride (mot-clé BM25 et sémantique) sur une collection ingérée, avec des fragments classés et notés.	Safe	oui

Les outils « certify » émettent un verdict de préparation défini par le produit (certified, partial ou not_certified). Ce verdict est le résultat d’un contrôle technique, non une certification délivrée par un quelconque organisme d’accréditation.

Contrôle d’approbation et posture d’audit

Chaque outil déclare un niveau de risque issu du modèle Connect à quatre niveaux. Les outils Safe s’exécutent automatiquement. Les outils Caution s’exécutent automatiquement avec une entrée dans le journal d’audit. Les outils Review portent un avertissement destiné aux instructions de l’agent appelant. Les outils ApprovalRequired exigent une confirmation humaine ; aucun outil MCP Enterprise ne déclare actuellement ce niveau, car aucun n’est destructif. La configuration à l’exécution peut seulement élever le niveau de risque d’un outil, jamais l’abaisser. Les outils publient également des annotations de comportement MCP (readOnlyHint, idempotentHint), de sorte qu’un client conforme peut appliquer son propre contrôle par-dessus. Voir Niveaux de risque HITL pour le modèle complet.

Pourquoi ce fonctionnement

La décision porteuse est que les outils sont de minces habillages déterministes à gouvernance auto-déclarée : chaque outil énonce son propre niveau de risque et son tier comme un invariant du domaine, jamais inféré à partir de l’espace de noms ou de l’empaquetage. Cela garde la décision de contrôle auditable au niveau de l’hôte sans faire confiance au transport. Les outils ne contiennent aucune intelligence documentaire propre ; ils délèguent aux mêmes API Enterprise que ton code appelle, de sorte qu’il y a exactement un comportement à tester et un verdict auquel se fier. Les erreurs reviennent sur le canal d’erreur MCP au lieu de s’échapper sous forme d’exceptions, car un agent ne peut pas attraper une exception PHP mais peut toujours se brancher sur isError. Toute entrée susceptible de toucher au système de fichiers est en mode fail-closed par défaut, puisque les arguments MCP sont par définition atteignables par un attaquant.

Contexte de conception : Une API qui refuse de deviner.

Surface d’API

Les onze outils implémentent le contrat NextPDF\Server\Tools\ToolInterface de nextpdf/server et partagent la même surface publique. Les signatures ci-dessous sont présentées une seule fois sur NextPDF\Enterprise\Mcp\ComplianceCheckTool, pris comme représentant :

public function name(): string
public function description(): string
public function inputSchema(): array
public function annotations(): array
public function riskLevel(): RiskLevel
public function tier(): ToolTier
public function category(): string
public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

Lève ou échoue avec : execute() ne lève jamais d’exception. Elle attrape Throwable en interne et renvoie ToolResult::error() avec isError = true. Les arguments invalides (workspace_token manquant, entrées documents mal formées, document_id inconnu, source non sûre) se manifestent sous forme de messages InvalidArgumentException sur ce canal d’erreur.

L’outil de piste d’audit reçoit son backend de stockage par injection dans le constructeur :

public function __construct(private readonly AstAuditTrailInterface $auditTrail)

Le fournisseur qui enregistre le catalogue :

public function getTier(): string
public function getTools(): array

getTier() renvoie 'enterprise'. getTools() renvoie les onze instances d’outils ; audit_ast_mutations est câblé avec NextPDF\Enterprise\Ast\InMemoryAstAuditTrail par défaut.

La fabrique de client du sidecar Spectrum, qui est aussi une fabrique de requêtes et de flux PSR-17 :

public static function create(): SpectrumClient
public static function reset(): void
public function createRequest(string $method, $uri): RequestInterface
public function createStream(string $content = ''): StreamInterface
public function createStreamFromFile(string $filename, string $mode = 'r'): StreamInterface
public function createStreamFromResource($resource): StreamInterface

Lève ou échoue avec : create() lève InvalidArgumentException lorsque SPECTRUM_URL est mal formée ou lorsque le point de terminaison configuré vise une adresse privée ou réservée connue (sauf localhost). Il s’agit d’un garde-fou au moment de la configuration, non d’un contrôle de couche réseau : applique quand même une politique de sortie, la gestion des redirections et l’épinglage DNS dans l’environnement hôte. createStreamFromFile() lève NextPDF\Enterprise\Mcp\McpStreamException (une sous-classe de RuntimeException, conformément au contrat PSR-17) lorsque le fichier ne peut pas être ouvert.

Exemple de code — Démarrage rapide

Exécute un contrôle de conformité PDF/A-4 exactement comme le ferait un agent, en utilisant le canal d’URI data: en mémoire :

<?php

declare(strict_types=1);

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

use NextPDF\Enterprise\Mcp\ComplianceCheckTool;
use NextPDF\Enterprise\Mcp\McpStreamException;
use NextPDF\Enterprise\Mcp\SpectrumClientFactory;
use NextPDF\Server\Document\InMemoryDocumentStore;

$streams = new SpectrumClientFactory(); // PSR-17 stream factory from this module

try {
    $pdfBytes = (string) $streams->createStreamFromFile(__DIR__ . '/invoice.pdf');
} catch (McpStreamException $e) {
    fwrite(STDERR, 'Cannot read PDF: ' . $e->getMessage() . PHP_EOL);
    exit(1);
}

$tool   = new ComplianceCheckTool();
$result = $tool->execute(
    [
        'source' => 'data:application/pdf;base64,' . base64_encode($pdfBytes),
        'policy' => 'pdfa4',
    ],
    new InMemoryDocumentStore(),
);

// Tool failures arrive on the MCP error channel, never as exceptions.
if ($result->isError) {
    fwrite(STDERR, $result->content[0]['text'] . PHP_EOL);
    exit(1);
}

echo $result->content[0]['text'] . PHP_EOL;

Sortie attendue pour un fichier conforme (le nombre de constats varie selon le document) :

Compliance check (PDF/A-4): PASS — 0 finding(s)

Le rapport complet lisible par machine, incluant la sévérité par constat, l’identifiant de règle, la clause et la suggestion, est disponible sur $result->structured.

Exemple de code — Production

Effectue un contrôle préalable du sidecar, applique la posture de risque déclarée, puis exécute un contrôle de conformité par lots :

<?php

declare(strict_types=1);

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

use NextPDF\Enterprise\Mcp\BatchComplianceCheckTool;
use NextPDF\Enterprise\Mcp\SpectrumClientFactory;
use NextPDF\Server\Document\InMemoryDocumentStore;

// 1. Fail fast on sidecar misconfiguration before accepting agent traffic.
//    The factory validates SPECTRUM_URL and rejects private/reserved targets.
try {
    SpectrumClientFactory::create();
} catch (InvalidArgumentException $e) {
    fwrite(STDERR, 'Spectrum sidecar rejected: ' . $e->getMessage() . PHP_EOL);
    exit(1);
}

$tool = new BatchComplianceCheckTool();
$risk = $tool->riskLevel();

// 2. Enforce the declared risk posture before execution.
if ($risk->requiresHumanConfirmation()) {
    // Route to your approval queue instead of executing.
    exit(0);
}

if ($risk->requiresAuditLog()) {
    error_log(sprintf('[mcp-audit] tool=%s risk=%s', $tool->name(), $risk->label()));
}

// 3. Execute the batch.
$result = $tool->execute(
    [
        'workspace_token' => (string) getenv('SPECTRUM_WORKSPACE_TOKEN'),
        'documents'       => [
            ['id' => 'contract-001', 'path' => '/var/pdf-inbox/contract-001.pdf'],
            ['id' => 'contract-002', 'path' => '/var/pdf-inbox/contract-002.pdf'],
        ],
        'policies'        => ['pdfa', 'pades'],
    ],
    new InMemoryDocumentStore(),
);

echo $result->content[0]['text'] . PHP_EOL;

Sortie attendue (les décomptes reflètent tes documents) :

Batch compliance check complete: 1 compliant, 1 non-compliant

Cas limites et pièges

Les chemins source du système de fichiers sont désactivés par défaut. Sans la variable d’environnement NEXTPDF_MCP_INPUT_DIR, un source en forme de chemin est rejeté avec un résultat d’erreur. Utilise plutôt document_id, un URI data: ou du base64 brut.
Le base64 brut n’est reconnu qu’au-delà de 256 caractères. Un blob base64 plus court est traité comme un chemin de fichier et rejeté. Enveloppe les petites charges utiles dans un URI data:application/pdf;base64,.
Les valeurs document_id inconnues échouent avec une indication. Le texte d’erreur est Unknown document_id: ... Call create_pdf first. Les documents du magasin en mémoire expirent aussi selon le TTL du magasin, de sorte qu’un identifiant périmé échoue de la même manière.
compliance_check rejette les clés de politique inconnues et liste l’ensemble pris en charge dans le message d’erreur.
Les outils de traitement par lots et RAG nécessitent le sidecar. batch_compliance_check, batch_forensic_analyze, embed_documents et search_documents requièrent un point de terminaison Spectrum accessible et un workspace_token. La fabrique met en cache un client par processus ; appelle SpectrumClientFactory::reset() dans les tests.
search_documents borne top_k entre 1 et 100 ; les valeurs non entières retombent sur la valeur serveur par défaut de 10.
Les valeurs par défaut de ast_aware_chunk sont de 1500 caractères par fragment avec 150 caractères de chevauchement.
certify_ai_ready omet les octets estampillés lorsque return_stamped_pdf vaut false ou que le verdict est not_certified. Lorsqu’elle est présente, la charge utile base64 est environ un tiers plus volumineuse que le PDF lui-même.
La piste d’audit AST par défaut est en mémoire. Les entrées enregistrées via le câblage de fournisseur d’origine ne persistent pas d’un processus à l’autre ; injecte une implémentation persistante de AstAuditTrailInterface pour des pistes d’audit durables.

Notes de sécurité

Résolution de source en mode fail-closed. Les appelants MCP contrôlent entièrement les arguments d’outil, aussi le résolveur les traite-t-il comme hostiles. Les wrappers de flux (phar://, php://, file:// et tout schéma) et les octets nuls sont rejetés avant tout appel au système de fichiers. La traversée de chemin est rejetée. Les chemins de fichiers bruts ne fonctionnent que lorsque NEXTPDF_MCP_INPUT_DIR est défini, et la cible canonisée par realpath doit se résoudre strictement à l’intérieur de ce répertoire, comparée sur une frontière de séparateur pour bloquer les évasions par confusion de préfixe.
Garde SSRF sur le point de terminaison du sidecar. SpectrumClientFactory autorise localhost pour le mode sidecar local et valide toute autre SPECTRUM_URL par rapport aux plages privées, réservées, link-local et de métadonnées cloud, levant InvalidArgumentException sur une adresse bloquée. Il s’agit d’un garde-fou au moment de la configuration sur le point de terminaison configuré, non d’un contrôle de couche réseau - conserve la politique de sortie, la gestion des redirections et l’épinglage DNS dans l’environnement hôte.
Les secrets restent dans l’environnement. Le jeton bearer du sidecar (SPECTRUM_AUTH_TOKEN) et le secret de signature HMAC (SPECTRUM_APP_SECRET) sont lus depuis des variables d’environnement et n’apparaissent jamais dans les charges utiles ou les résultats des outils.
Erreurs non réfléchissantes. Les messages de rejet de chemin sont génériques par conception (Source path is not permitted.), de sorte qu’un appelant qui sonde n’apprend rien sur le système de fichiers hôte.
Les surcharges de risque ne vont que vers le haut. La configuration de l’opérateur peut élever le niveau de risque déclaré d’un outil mais ne peut jamais l’abaisser en deçà de la déclaration propre de l’outil.

Conformité

La prise en charge n’est pas la conformité, et la conformité n’est pas la certification. NextPDF ne détient aucune certification et n’en accorde aucune. Les outils de conformité vérifient la structure du document par rapport aux profils de politique nommés et rapportent les constats avec des références de clause ; le rapport compliance_check porte en outre l’avertissement propre au moteur selon lequel il s’agit d’un contrôle technique de structure à titre de référence, non d’un conseil juridique ni d’une approbation de conformité. Les verdicts ai_ready_certify et certify_ai_ready sont des niveaux de préparation définis par le produit, non une attestation délivrée par un quelconque organisme de normalisation. MCP est un protocole ouvert publié par son responsable éditeur, non une norme d’un SDO ; cette page documente le comportement d’implémentation de NextPDF et ne formule aucune revendication indépendante de conformité protocolaire ou de certification.

Contrat de comportement

Les échecs d’outil sont renvoyés sous forme de résultats d’erreur (isError = true avec un message) ; les exceptions ne franchissent jamais la frontière MCP.
Les résultats réussis portent un résumé d’une ligne lisible par un humain, plus une charge utile JSON structurée avec un ensemble de champs stable et documenté par outil.
Chaque outil rapporte tier() = ToolTier::Enterprise et un RiskLevel déclaré ; le risque ne peut pas être abaissé à l’exécution.
Les outils en lecture seule déclarent readOnlyHint: true et ne modifient ni le magasin de documents, ni le PDF source, ni aucune collection.
certify_ai_ready n’altère jamais le document d’entrée en place ; l’estampille est appliquée à une copie renvoyée.
Les rapports de conformité et LTV incluent un horodatage de validation et des décomptes de constats par sévérité ; la charge utile compliance_check inclut en outre la chaîne d’avertissement juridique du moteur.

Repli sur Core

L’hôte MCP lui-même ne requiert pas Enterprise. NextPDF Connect (nextpdf/server, Apache-2.0) fonctionne avec le moteur Core ouvert et sert son catalogue d’outils de niveau core : création de documents, opérations de texte et de contenu, et extraction. Voir le catalogue des outils. Core seul ne fournit ni contrôles de politique de conformité, ni analyse forensique, ni contrôles de santé LTV, ni estampillage de préparation à l’IA, ni découpage sensible à l’AST, ni pistes d’audit de mutation, ni les outils de traitement par lots et RAG ; ces onze outils ne s’enregistrent qu’avec nextpdf/enterprise installé et sous licence.

Périmètre 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 utilitaires, les tables de mécanismes, les noms de fichiers de runbook et les préfixes de tickets sont hors périmètre.