Enterprise edición

Herramientas MCP

Panorama general

NextPDF Enterprise añade once herramientas MCP al servidor NextPDF Connect. Estas otorgan a los asistentes de IA y a los marcos de agentes acceso directo y tipado al motor Enterprise: comprobaciones de política de conformidad, análisis forense de PDF, verificaciones de salud LTV, sellado de preparación para IA, fragmentación consciente del AST, e ingesta y búsqueda RAG. Cada herramienta declara su propio nivel de riesgo y postura de solo lectura, de modo que el host MCP puede limitar, registrar y auditar la actividad de los agentes con confianza. Los fallos nunca se manifiestan como excepciones; los agentes siempre reciben un resultado estructurado y analizable.

Disponibilidad y licencias

Esta capacidad se incluye en NextPDF Enterprise (nextpdf/enterprise) y se activa con un sobre de licencia de nivel Enterprise. Un despliegue sin esa habilitación no carga las clases de la capacidad. Comparar ediciones y obtener una licencia.

Instalación

composer require nextpdf/enterprise:^3

El propio host MCP es NextPDF Connect, incluido en el paquete nextpdf/server; consultar Instalación de Connect. Cuando ambos paquetes están presentes, el registro de herramientas del servidor descubre NextPDF\Enterprise\McpToolProvider automáticamente y registra las once herramientas Enterprise. No se requiere código de conexión. Si nextpdf/server está ausente, el archivo del proveedor retorna de inmediato y no se carga nada.

Las herramientas de lote y RAG requieren además el sidecar Spectrum. Configurarlo mediante las variables de entorno leídas por NextPDF\Enterprise\Mcp\SpectrumClientFactory: SPECTRUM_URL (por defecto http://127.0.0.1:7800), SPECTRUM_TIMEOUT (por defecto 30.0 segundos), SPECTRUM_AUTH_TOKEN y SPECTRUM_APP_SECRET.

Visión conceptual

El Model Context Protocol (MCP) es un protocolo abierto que permite a los asistentes de IA y a los marcos de agentes invocar herramientas tipadas expuestas por un servidor. En lugar de pegar los bytes del PDF en un prompt y confiar en la suerte, un agente invoca una herramienta con nombre con una carga útil validada por esquema JSON y recibe un resultado determinista y estructurado. NextPDF Connect es ese servidor para los PDF; el paquete Enterprise extiende su catálogo con las herramientas que se detallan a continuación. Cada herramienta es una envoltura delgada sobre las mismas API de Enterprise que su código PHP invoca directamente, de modo que una comprobación ejecutada por un agente y una comprobación ejecutada por código producen el mismo veredicto.

Catálogo de herramientas

Herramienta MCP	Clase	Qué hace	Riesgo	Solo lectura
`compliance_check`	`ComplianceCheckTool`	Valida un PDF contra una política con nombre: `pdfa4`, `pdfa4e`, `pdfa4f`, `pades-baseline`, `ltv-health`, `eidas-qualified`, `zugferd`, `fda-part11` y cuatro variantes `sec-17a4`.	Revisión	sí
`batch_compliance_check`	`BatchComplianceCheckTool`	Comprueba muchos PDF contra las políticas `pdfa`, `pades` o `zugferd` en un solo lote del sidecar Spectrum.	Seguro	sí
`forensic_analyze`	`ForensicAnalyzeTool`	Informa del historial de revisiones, las actualizaciones incrementales y los eventos de modificación para la detección de manipulaciones.	Seguro	sí
`batch_forensic_analyze`	`BatchForensicAnalyzeTool`	Ejecuta el análisis forense sobre muchos PDF en un solo lote del sidecar.	Seguro	sí
`ltv_health_check`	`LtvHealthCheckTool`	Comprueba en un PDF firmado el material de validación a largo plazo: diccionario DSS, respuestas OCSP, entradas CRL, entradas VRI y almacenes de certificados.	Seguro	sí
`ai_ready_certify`	`AiReadyCertifyTool`	Veredicto de solo lectura de preparación para IA definido por el producto sobre cuatro criterios: integridad forense, presencia de firma, validez LTV, sin cifrado.	Revisión	sí
`certify_ai_ready`	`CertifyAiReadyTool`	Veredicto de preparación definido por el producto sobre tres criterios (los cuatro de la herramienta de solo lectura menos la integridad forense, por diseño, ya que esta herramienta reescribe el archivo que sella) y añade un sello de procedencia XMP; devuelve el PDF sellado como base64.	Revisión	no
`ast_aware_chunk`	`AstAwareChunkTool`	Divide un PDF en fragmentos anclados por cita a lo largo de los límites de encabezado, con ID de nodo, índice de página y caja delimitadora por fragmento.	Revisión	sí
`audit_ast_mutations`	`AuditAstMutationsTool`	Recupera el rastro de auditoría de mutaciones del AST de un documento por su hash de origen SHA-256.	Revisión	sí
`embed_documents`	`EmbedDocumentsTool`	Ingiere PDF en una colección RAG: analizar, fragmentar, embeber, indexar. Modifica el estado de la colección.	Precaución	no
`search_documents`	`SearchDocumentsTool`	Recuperación híbrida (palabra clave BM25 más semántica) sobre una colección ingerida, con fragmentos clasificados y puntuados.	Seguro	sí

Las herramientas «certify» emiten un veredicto de preparación definido por el producto (certified, partial o not_certified). Ese veredicto es el resultado de una comprobación técnica, no una certificación por parte de ningún organismo de acreditación.

Limitación por aprobación y postura de auditoría

Cada herramienta declara un nivel de riesgo del modelo Connect de cuatro niveles. Las herramientas Safe se ejecutan automáticamente. Las herramientas Caution se ejecutan automáticamente con una entrada en el registro de auditoría. Las herramientas Review conllevan una advertencia para las instrucciones del agente invocador. Las herramientas ApprovalRequired exigen confirmación humana; ninguna herramienta MCP de Enterprise declara actualmente este nivel, porque ninguna es destructiva. La configuración en tiempo de ejecución solo puede elevar el nivel de riesgo de una herramienta, nunca reducirlo. Las herramientas también publican anotaciones de comportamiento MCP (readOnlyHint, idempotentHint), de modo que un cliente conforme puede aplicar su propia limitación por encima. Consultar Niveles de riesgo HITL para el modelo completo.

Por qué funciona así

La decisión determinante es que las herramientas son envolturas delgadas y deterministas con gobernanza autodeclarada: cada herramienta indica su propio nivel de riesgo y su nivel como invariante de dominio, nunca inferido del espacio de nombres o del empaquetado. Esto mantiene la decisión de limitación auditable en el host sin confiar en el transporte. Las herramientas no contienen inteligencia documental propia; delegan en las mismas API de Enterprise que invoca su código, de modo que hay exactamente un comportamiento que probar y un veredicto en el que confiar. Los errores se devuelven por el canal de errores de MCP en lugar de escapar como excepciones, porque un agente no puede capturar una excepción de PHP pero siempre puede ramificar según isError. La entrada que podría tocar el sistema de archivos es de fallo cerrado por defecto, ya que los argumentos de MCP son alcanzables por atacantes por definición.

Contexto de diseño: Una API que se niega a adivinar.

Superficie de la API

Las once herramientas implementan el contrato NextPDF\Server\Tools\ToolInterface de nextpdf/server y comparten la misma superficie pública. Las firmas siguientes se muestran una sola vez sobre NextPDF\Enterprise\Mcp\ComplianceCheckTool como representante:

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

Lanza o falla con: execute() nunca lanza. Captura Throwable internamente y devuelve ToolResult::error() con isError = true. Los argumentos no válidos (falta de workspace_token, entradas documents malformadas, document_id desconocido, source no seguro) se manifiestan como mensajes de InvalidArgumentException en ese canal de errores.

La herramienta de rastro de auditoría recibe su backend de almacenamiento por inyección en el constructor:

public function __construct(private readonly AstAuditTrailInterface $auditTrail)

El proveedor que registra el catálogo:

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

getTier() devuelve 'enterprise'. getTools() devuelve las once instancias de herramienta; audit_ast_mutations se conecta con NextPDF\Enterprise\Ast\InMemoryAstAuditTrail por defecto.

La fábrica del cliente del sidecar Spectrum, que también es una fábrica de solicitudes y flujos 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

Lanza o falla con: create() lanza InvalidArgumentException cuando SPECTRUM_URL está malformado o cuando el endpoint configurado apunta a una dirección privada o reservada conocida (excepto localhost). Esto es una limitación en tiempo de configuración, no un control a nivel de red: aún así, aplique la política de egreso, la gestión de redirecciones y el anclaje de DNS en el entorno del host. createStreamFromFile() lanza NextPDF\Enterprise\Mcp\McpStreamException (una subclase de RuntimeException, según el contrato PSR-17) cuando el archivo no se puede abrir.

Ejemplo de código — Inicio rápido

Ejecutar una comprobación de conformidad PDF/A-4 exactamente como lo haría un agente, usando el canal de URI data: en memoria:

<?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;

Salida esperada para un archivo conforme (los recuentos de hallazgos varían por documento):

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

El informe completo legible por máquina, incluida la gravedad por hallazgo, el ID de regla, la cláusula y la sugerencia, está disponible en $result->structured.

Ejemplo de código — Producción

Preverificar el sidecar, aplicar la postura de riesgo declarada y, luego, ejecutar una comprobación de conformidad por lotes:

<?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;

Salida esperada (los recuentos reflejan sus documentos):

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

Casos límite y advertencias

Las rutas de sistema de archivos en source están deshabilitadas por defecto. Sin la variable de entorno NEXTPDF_MCP_INPUT_DIR, un source con forma de ruta se rechaza con un resultado de error. Use document_id, una URI data: o base64 sin procesar en su lugar.
El base64 sin procesar solo se reconoce por encima de 256 caracteres. Un blob base64 más corto se trata como una ruta de archivo y se rechaza. Envuelva las cargas pequeñas en una URI data:application/pdf;base64,.
Los valores de document_id desconocidos fallan con orientación. El texto de error es Unknown document_id: ... Call create_pdf first. Los documentos del almacén en memoria también caducan según el TTL del almacén, de modo que un ID obsoleto falla de la misma manera.
compliance_check rechaza las claves de política desconocidas y enumera el conjunto admitido en el mensaje de error.
Las herramientas de lote y RAG necesitan el sidecar. batch_compliance_check, batch_forensic_analyze, embed_documents y search_documents requieren un endpoint Spectrum accesible y un workspace_token. La fábrica almacena en caché un cliente por proceso; llame a SpectrumClientFactory::reset() en las pruebas.
search_documents limita top_k a 1–100; los valores no enteros recurren al valor por defecto del servidor de 10.
Los valores por defecto de ast_aware_chunk son 1500 caracteres por fragmento con 150 caracteres de solapamiento.
certify_ai_ready omite los bytes sellados cuando return_stamped_pdf es false o el veredicto es not_certified. Cuando está presente, la carga útil base64 es alrededor de un tercio más grande que el propio PDF.
El rastro de auditoría del AST por defecto está en memoria. Las entradas registradas a través de la conexión estándar del proveedor no persisten entre procesos; inyecte una implementación persistente de AstAuditTrailInterface para obtener rastros de auditoría duraderos.

Notas de seguridad

Resolución de origen de fallo cerrado. Los invocadores de MCP controlan por completo los argumentos de la herramienta, de modo que el resolutor los trata como hostiles. Los envoltorios de flujo (phar://, php://, file:// y cualquier esquema) y los bytes nulos se rechazan antes de cualquier llamada al sistema de archivos. El recorrido de rutas se rechaza. Las rutas de archivo sin procesar solo funcionan cuando NEXTPDF_MCP_INPUT_DIR está definido, y el objetivo canonicalizado por realpath debe resolverse estrictamente dentro de ese directorio, comparado en un límite de separador para bloquear los escapes por confusión de prefijos.
Protección SSRF en el endpoint del sidecar. SpectrumClientFactory permite localhost para el modo de sidecar local y valida cada otra SPECTRUM_URL contra rangos privados, reservados, de enlace local y de metadatos de nube, lanzando InvalidArgumentException en una dirección bloqueada. Esto es una limitación en tiempo de configuración sobre el endpoint configurado, no un control a nivel de red: mantenga la política de egreso, la gestión de redirecciones y el anclaje de DNS en el entorno del host.
Los secretos permanecen en el entorno. El token de portador del sidecar (SPECTRUM_AUTH_TOKEN) y el secreto de firma HMAC (SPECTRUM_APP_SECRET) se leen de variables de entorno y nunca aparecen en las cargas útiles ni en los resultados de las herramientas.
Errores no reflectantes. Los mensajes de rechazo de rutas son genéricos por diseño (Source path is not permitted.), de modo que un invocador que sondea no aprende nada sobre el sistema de archivos del host.
Las anulaciones de riesgo solo suben. La configuración del operador puede elevar el nivel de riesgo declarado de una herramienta, pero nunca puede reducirlo por debajo de la propia declaración de la herramienta.

Conformidad

El soporte no es conformidad, y la conformidad no es certificación. NextPDF no posee ninguna certificación y no otorga ninguna. Las herramientas de conformidad comprueban la estructura del documento contra los perfiles de política con nombre e informan de los hallazgos con referencias de cláusula; el informe de compliance_check incluye además la propia advertencia del motor de que es una comprobación técnica de estructura de referencia, no un asesoramiento legal ni un respaldo de conformidad. Los veredictos de ai_ready_certify y certify_ai_ready son niveles de preparación definidos por el producto, no una certificación por parte de ningún organismo de normalización. MCP es un protocolo abierto publicado por su administrador proveedor, no una norma de un SDO; esta página documenta el comportamiento de implementación de NextPDF y no formula ninguna reivindicación independiente de conformidad de protocolo ni de certificación.

Contrato de comportamiento

Los fallos de las herramientas se devuelven como resultados de error (isError = true con un mensaje); las excepciones nunca cruzan el límite de MCP.
Los resultados correctos llevan un resumen de una línea legible por humanos más una carga útil JSON estructurada con un conjunto de campos estable y documentado por herramienta.
Cada herramienta informa de tier() = ToolTier::Enterprise y un RiskLevel declarado; el riesgo no se puede reducir en tiempo de ejecución.
Las herramientas de solo lectura declaran readOnlyHint: true y no modifican el almacén de documentos, el PDF de origen ni ninguna colección.
certify_ai_ready nunca altera el documento de entrada en el sitio; el sello se aplica a una copia devuelta.
Los informes de conformidad y LTV incluyen una marca de tiempo de validación y recuentos de hallazgos por gravedad; la carga útil de compliance_check incluye además la cadena de advertencia legal del motor.

Alternativa Core

El propio host MCP no requiere Enterprise. NextPDF Connect (nextpdf/server, Apache-2.0) funciona con el motor Core abierto y sirve su catálogo de herramientas de nivel Core: creación de documentos, operaciones de texto y contenido, y extracción. Consultar el catálogo de herramientas. Core por sí solo no proporciona comprobaciones de política de conformidad, análisis forense, verificaciones de salud LTV, sellado de preparación para IA, fragmentación consciente del AST, rastros de auditoría de mutaciones, ni las herramientas de lote y RAG; esas once herramientas se registran únicamente con nextpdf/enterprise instalado y licenciado.

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie pública de la API admitida. Las rutas de espacios de nombres internos, las clases auxiliares, las tablas de mecanismos, los nombres de archivo de runbooks y los prefijos de tickets quedan fuera del alcance.