MCP — référence approfondie

En un coup d’œil

L’espace de noms NextPDF\Enterprise\Mcp fournit le niveau Enterprise du catalogue d’outils MCP de NextPDF. Sa surface publique se compose de onze classes d’outils, d’une fabrique de clients et d’une exception typée. Chaque outil implémente le contrat NextPDF\Server\Tools\ToolInterface de l’environnement d’exécution nextpdf/server et déclare ToolTier::Enterprise. Six outils analysent un seul PDF en cours de processus. Quatre outils délèguent les charges de travail par lots et RAG au sidecar Spectrum via NextPDF\Enterprise\Mcp\SpectrumClientFactory. Un outil lit une piste d’audit de mutations AST injectée par le constructeur au lieu d’octets PDF. Chaque outil décrit lui-même son nom MCP, son entrée JSON Schema, ses annotations client, son RiskLevel et sa catégorie.

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

Surface de l’API publique

Symbole	Paramètres	Comportement par défaut	Retourne	Lève ou échoue avec	Notes
ForensicAnalyzeTool::execute	array $arguments, InMemoryDocumentStore $store ; args : document_id ou source	Exécute l’analyse forensique : révisions, mises à jour incrémentielles, signatures	ToolResult (rapport JSON)	ToolResult d’erreur ; les exceptions sont interceptées, jamais relancées	Outil forensic_analyze ; RiskLevel::Safe ; lecture seule, idempotent ; catégorie document ; depuis 2.0.0
BatchForensicAnalyzeTool::execute	args : workspace_token, documents[] (chacun id + path)	Analyse forensique par lots via le sidecar Spectrum	ToolResult avec un status par document, nombres de réussites et d’échecs	ToolResult d’erreur (arguments manquants, échec du sidecar)	Outil batch_forensic_analyze ; RiskLevel::Safe ; catégorie document ; depuis 2.1.0
ComplianceCheckTool::execute	args : policy (énumération à 12 valeurs), document_id ou source	Évalue le PDF au regard d’une politique de conformité nommée	ToolResult avec constats, réussite/échec, duration_ms et un champ disclaimer	ToolResult d’erreur ; une politique inconnue retourne une erreur listant les clés prises en charge	Outil compliance_check ; RiskLevel::Review ; catégorie document ; depuis 2.0.0
BatchComplianceCheckTool::execute	args : workspace_token, documents[], policies (pdfa, pades, zugferd ; par défaut ["pdfa"])	Contrôles de conformité par lots via le sidecar Spectrum	ToolResult avec nombres de documents conformes / non conformes	ToolResult d’erreur ; chaque élément de documents[] est validé pour un id et un path non vides	Outil batch_compliance_check ; RiskLevel::Safe ; catégorie document ; depuis 2.1.0
LtvHealthCheckTool::execute	args : document_id ou source	Exécute la politique de santé LTV sur un PDF signé	ToolResult avec constats et réussite/échec	ToolResult d’erreur	Outil ltv_health_check ; RiskLevel::Safe ; catégorie document ; depuis 2.0.0
AiReadyCertifyTool::execute	args : document_id ou source	Évaluation de la préparation à l’IA en lecture seule sur quatre critères	ToolResult avec certification_level (certified, partial, not_certified) et des booléens par critère	ToolResult d’erreur	Outil ai_ready_certify ; RiskLevel::Review ; lecture seule ; catégorie document ; depuis 2.0.0
CertifyAiReadyTool::execute	args : document_id ou source, return_stamped_pdf (par défaut true)	Évalue trois critères et ajoute un tampon de provenance XMP	ToolResult ; inclut stamped_pdf_base64 sauf si désactivé ou not_certified	ToolResult d’erreur	Outil certify_ai_ready ; RiskLevel::Review ; pas en lecture seule ; catégorie document ; depuis 3.0.0
AstAwareChunkTool::execute	args : document_id ou source, max_chunk_chars (par défaut 1500), overlap_chars (par défaut 150)	Construit l’AST et émet des fragments ancrés par citation avec provenance	ToolResult avec chunk_count et, par fragment, l’ID de nœud, l’index de page, la bbox et le type de nœud	ToolResult d’erreur	Outil ast_aware_chunk ; RiskLevel::Review ; catégorie extraction ; depuis 3.0.0
AuditAstMutationsTool::__construct	AstAuditTrailInterface $auditTrail	Injecte le backend de la piste d’audit	instance	—	Dépendance injectée par le constructeur ; depuis 3.0.0
AuditAstMutationsTool::execute	args : document_source_hash (hex SHA-256, requis)	Retourne tous les événements de mutation AST enregistrés pour ce document	ToolResult avec entries[] et count	ToolResult d’erreur lorsque l’argument est manquant ou vide	Outil audit_ast_mutations ; RiskLevel::Review ; catégorie document ; depuis 3.0.0
EmbedDocumentsTool::execute	args : collection_id, workspace_token, documents[] (tous requis)	Ingère des PDF dans une collection RAG via le sidecar Spectrum	ToolResult avec nombres de réussites / total / échecs	ToolResult d’erreur	Outil embed_documents ; RiskLevel::Caution ; pas en lecture seule, pas idempotent ; catégorie extraction ; depuis 2.1.0
SearchDocumentsTool::execute	args : collection_id, query (requis), top_k (par défaut 10, borné 1–100), mode (hybrid, bm25, semantic)	Récupération hybride sur une collection ingérée	ToolResult avec fragments classés et scores de pertinence	ToolResult d’erreur ; un mode hors de la liste d’autorisation est rejeté	Outil search_documents ; RiskLevel::Safe ; catégorie extraction ; depuis 2.1.0
SpectrumClientFactory::create	aucun (lit SPECTRUM_URL, SPECTRUM_TIMEOUT, SPECTRUM_AUTH_TOKEN, SPECTRUM_APP_SECRET)	Construit et met en cache un client sidecar unique à l’échelle du processus	SpectrumClient	InvalidArgumentException lorsque SPECTRUM_URL est mal formée ou cible une adresse bloquée	Point de terminaison par défaut http://127.0.0.1:7800 ; délai d’attente 30.0 s ; depuis 2.1.0
SpectrumClientFactory::reset	aucun	Efface l’instance de client mise en cache	void	—	Destiné aux tests
SpectrumClientFactory::createRequest	string $method, $uri (string ou UriInterface)	Construit une requête PSR-7 à partir des classes HTTP de Core	RequestInterface	—	Implémentation PSR-17 de RequestFactoryInterface
SpectrumClientFactory::createStream	string $content = ''	Construit un flux PSR-7 en mémoire	StreamInterface	—	Implémentation PSR-17 de StreamFactoryInterface
SpectrumClientFactory::createStreamFromFile	string $filename, string $mode = 'r'	Ouvre le fichier et l’enveloppe en flux	StreamInterface	McpStreamException lorsque le fichier ne peut pas être ouvert	McpStreamException étend RuntimeException
SpectrumClientFactory::createStreamFromResource	$resource (ressource PHP)	Enveloppe une ressource existante en flux	StreamInterface	—	Implémentation PSR-17 de StreamFactoryInterface
McpStreamException	—	Échec typé d’acquisition de flux	—	—	final class, étend RuntimeException ; la source documente la compatibilité PSR-17 §1.5 ; la source l’annote @since 3.2.0 (présente dans la ligne de développement actuelle aliasée 3.1.0)

Chaque outil expose également les méthodes d’auto-description de ToolInterface : name, description, inputSchema, annotations, riskLevel, tier et category. Leurs valeurs propres à chaque outil figurent dans la colonne Notes ci-dessus.

Signatures des points d’entrée, telles quelles depuis la source :

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function __construct(private readonly AstAuditTrailInterface $auditTrail)
public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

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

Contrat de comportement

• Chaque outil implémente NextPDF\Server\Tools\ToolInterface et déclare explicitement ToolTier::Enterprise. Le niveau n’est jamais déduit de l’espace de noms ou de l’empaquetage.
• execute ne lève pas d’exception. Chaque échec est intercepté et retourné sous forme de ToolResult d’erreur portant le message d’échec.
• Les outils à document unique résolvent les octets PDF selon une priorité fixe. Un document_id est d’abord recherché dans l’InMemoryDocumentStore. Sinon, source est interprété comme une URI data:, puis comme du base64 brut (plus de 256 caractères), puis comme un chemin de fichier.
• Les chemins de fichier source sont désactivés par défaut. Ils ne s’activent que lorsque la variable d’environnement NEXTPDF_MCP_INPUT_DIR nomme un répertoire d’entrée confiné. Le chemin réel résolu doit rester à l’intérieur de ce répertoire. Tout le reste échoue en mode fermé.
• Les schémas de wrapper de flux (phar://, php://, file:// et tout autre schéma) ainsi que les octets nuls dans un source de type chemin de fichier sont rejetés avant tout appel au système de fichiers. Les évasions par traversée et par lien symbolique échouent face au contrôle de confinement du chemin réel.
• Les outils adossés à un sidecar (embed_documents, search_documents, batch_compliance_check, batch_forensic_analyze) obtiennent leur client depuis SpectrumClientFactory::create. La fabrique valide une SPECTRUM_URL non-localhost au regard des plages d’adresses privées et réservées avant utilisation. Le localhost explicite est autorisé pour le mode sidecar local.
• ai_ready_certify dérive son niveau de quatre critères : intégrité forensique, présence de signature, validité LTV et absence de chiffrement. Les quatre validés donnent certified ; un à trois donnent partial ; zéro donne not_certified. L’intégrité forensique est une heuristique structurelle sur la chaîne de révisions, et non une vérification cryptographique de l’intégrité des octets. Le contrôle de chiffrement n’inspecte que la région du trailer.
• certify_ai_ready évalue trois critères et ajoute un tampon de provenance XMP. Les octets tamponnés sont retournés encodés en base64 sauf si return_stamped_pdf vaut false ou si le niveau est not_certified.
• compliance_check accepte exactement douze clés de politique : pdfa4, pdfa4e, pdfa4f, pades-baseline, ltv-health, eidas-qualified, zugferd, fda-part11, sec-17a4, sec-17a4-compatible, sec-17a4-structural, sec-17a4-pre-sign. Une clé inconnue retourne un résultat d’erreur nommant l’ensemble pris en charge.
• audit_ast_mutations ne lit que l’AstAuditTrailInterface injecté. Il n’enregistre rien lui-même.

Cas limites et modes de défaillance

• Ni document_id ni source fournis : résultat d’erreur indiquant à l’appelant d’en fournir un.
• document_id inconnu : résultat d’erreur nommant l’ID et pointant vers create_pdf.
• source de type chemin de fichier avec NEXTPDF_MCP_INPUT_DIR non défini : rejeté avec un message nommant les canaux pris en charge.
• Chemin source se résolvant en dehors du répertoire d’entrée configuré, y compris via un lien symbolique : rejeté. La comparaison se fait sur une frontière de séparateur de répertoire, de sorte que des répertoires frères partageant un préfixe de nom ne peuvent pas passer.
• URI data: sans séparateur virgule, ou charge utile base64 invalide : résultat d’erreur.
• top_k de search_documents hors de 1–100 : borné, pas rejeté. Un top_k non entier revient à la valeur par défaut configurée du pipeline.
• mode de search_documents hors de hybrid, bm25, semantic : résultat d’erreur de la liste d’autorisation du pipeline.
• Élément de documents[] de batch_compliance_check sans id ou path, ou portant des chaînes vides : résultat d’erreur nommant l’index fautif. batch_forensic_analyze ne valide que la forme du tableau externe ; les défauts d’élément remontent depuis la couche de traitement par lots.
• SpectrumClientFactory::create avec une SPECTRUM_URL mal formée, ou ciblant une adresse privée, link-local ou de métadonnées : InvalidArgumentException. À l’intérieur d’un execute d’outil, cela remonte sous forme de résultat d’erreur.
• SpectrumClientFactory::createStreamFromFile sur un chemin illisible : McpStreamException.
• Les variables d’environnement vides sont traitées comme non définies et reviennent aux valeurs par défaut.

Conformité

NextPDF ne détient aucune certification et n’en accorde aucune. Les outils MCP rapportent des évaluations au niveau des capacités ; la prise en charge n’est pas la conformité, et la conformité n’est pas la certification. Les valeurs certification_level retournées par ai_ready_certify et certify_ai_ready relèvent du vocabulaire propre rapporté par les outils. Elles ne constituent pas une attestation par un tiers. Les réponses de compliance_check incluent un champ disclaimer produit par le rapport sous-jacent pour la même raison. Les références de clause de politique, telle que la base de la politique LTV que la source du produit indique comme ISO 32000-2:2020 §12.8.4.3, sont portées dans les descriptions d’outils et les champs clause par constat ; cette page n’ajoute aucune revendication de normes indépendante. Déterminer si un document contrôlé satisfait une réglementation appartient à l’opérateur et à ses évaluateurs.

Notes de développement

• SpectrumClientFactory::create met en cache un client par processus. Appelle SpectrumClientFactory::reset dans la configuration des tests pour forcer un nouveau client.
• Les lectures d’environnement consultent $_ENV, puis $_SERVER, puis getenv, et traitent les chaînes vides comme absentes.
• RiskLevel pilote le traitement côté hôte dans l’environnement d’exécution du serveur : Safe s’exécute automatiquement, Caution et au-dessus sont journalisés pour audit, et ApprovalRequired exige une confirmation humaine. Aucun outil MCP Enterprise ne déclare ApprovalRequired. Les remplacements par l’opérateur peuvent élever un niveau déclaré, jamais l’abaisser.
• Les valeurs annotations (readOnlyHint, idempotentHint) sont des indices pour le client MCP, pas une application. Le confinement et la validation ont lieu côté serveur indépendamment des indices.
• Les outils rapportent des valeurs category document ou extraction pour le filtrage de tools/list.
• AuditAstMutationsTool est le seul outil nécessitant une injection par le constructeur ; enregistre-le avec une implémentation concrète d’AstAuditTrailInterface.

Voir aussi

• MCP (page de capacité)
• Accelerator — référence approfondie — la surface du client sidecar Spectrum.
• Forensics — référence approfondie — l’analyseur derrière forensic_analyze.
• Compliance — référence approfondie — les politiques derrière compliance_check.
• AST — référence approfondie — le découpage et la piste d’audit de mutations.
• Validation — référence approfondie

Périmètre 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’espace 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.