Pro edición

Herramientas MCP

De un vistazo

NextPDF Pro añade ocho herramientas del Model Context Protocol (MCP) que permiten a un agente de IA ejecutar operaciones avanzadas con PDF a través de NextPDF Server. Las herramientas se exponen automáticamente cuando están instalados tanto nextpdf/pro como nextpdf/server; no se requiere ningún paso de registro independiente.

Disponibilidad y licenciamiento

Esta capacidad se incluye en NextPDF Pro (nextpdf/pro) y se activa con un sobre de licencia de nivel Pro. Un despliegue sin ese derecho no carga las clases de la capacidad. Comparar ediciones y obtener una licencia.

La superficie MCP base —creación de documentos, texto, tablas, diagnósticos— se incluye con el NextPDF Server de código abierto y no necesita licencia. Las ocho herramientas de esta página requieren una licencia de Pro y se registran únicamente cuando el paquete nextpdf/pro se resuelve al arrancar. El nivel de herramientas pro protege todo el conjunto: cada herramienta declara su nivel explícitamente y no existe un indicador por herramienta; instalar nextpdf/pro junto con nextpdf/server habilita el conjunto.

Contrato de comportamiento

Las ocho herramientas MCP de Pro se registran automáticamente cuando tanto nextpdf/pro como nextpdf/server se resuelven al arrancar, bajo el nivel pro, mediante el flujo estándar de MCP tools/list y tools/call. No hay un indicador por herramienta ni ningún cambio de código en la aplicación consumidora.
Cada herramienta acepta un PDF a través de un document_id de una llamada anterior a create_pdf, un source en línea (ruta de archivo, base64 o URI data:) o —en el caso de compare_pdfs— dos de esas fuentes. Las herramientas devuelven JSON estructurado.
Toda herramienta declara una clase de riesgo HITL que el servidor aplica: segura (autoejecución, solo lectura), revisión (salida que podría usarse de forma indebida) y aprobación requerida. sign_pdf requiere aprobación y se retiene hasta que una persona lo confirma. Un operador solo puede endurecer la clase de riesgo de una herramienta, nunca relajarla.
sign_pdf produce únicamente una firma PAdES B-B (línea base): sin marca de tiempo confiable y sin material de validación a largo plazo. Los perfiles a largo plazo (B-LT / B-LTA), la custodia de claves en hardware y la firma con registro de auditoría son de nivel Enterprise y estas herramientas no los proporcionan; B-T (una firma con marca de tiempo) está disponible en el motor Core cuando se configura un proveedor de marca de tiempo.
redact_pii realiza detección y enmascaramiento de patrones en la capa de texto, no redacción visual; check_accessibility es una heurística estructural, no un veredicto de conformidad PDF/UA o WCAG. El esquema autoritativo de entrada/salida es la respuesta tools/list en vivo del servidor, no esta página.

Panorama conceptual

NextPDF Server es la capa de ejecución MCP determinista de NextPDF. Descubre los proveedores de herramientas al arrancar mediante una comprobación de existencia de clases, de modo que el paquete de Pro no necesita figurar en las dependencias del servidor. Cuando el paquete de Pro está presente, el servidor registra sus ocho herramientas bajo el nivel pro y las expone mediante el flujo estándar de MCP tools/list y tools/call sobre el transporte que tengas configurado.

Cada herramienta de Pro acepta un PDF de una de tres fuentes: un document_id devuelto por una llamada anterior a create_pdf, un source en línea (ruta de archivo, cadena base64 o URI data:) o —en el caso de la herramienta de comparación— dos de esas fuentes. Las herramientas devuelven resultados JSON estructurados: texto extraído, regiones de diferencias, texto enmascarado, árboles de segmentos, hallazgos de accesibilidad o un PDF firmado.

Toda herramienta de Pro lleva una clasificación de riesgo que el servidor usa para la aplicación de la supervisión humana (HITL). Las herramientas de análisis de solo lectura se clasifican como seguras y se autoejecutan. Las herramientas que generan una salida que el llamador podría usar de forma indebida se clasifican para revisión. La herramienta de firma se clasifica como de aprobación requerida, así que el servidor la retiene hasta que una persona la confirma. La propia herramienta declara esta clasificación; un operador solo puede endurecerla en tiempo de ejecución, nunca aflojarla.

La superficie de herramientas MCP está intencionadamente separada del motor PDF de Pro. Las herramientas son adaptadores ligeros: validan las entradas, resuelven el PDF, delegan en un componente del motor de Pro y serializan el resultado. No son una segunda API del motor ni forman parte de la API pública de PHP de Pro; el punto de integración admitido es el protocolo MCP que expone NextPDF Server.

Catálogo de herramientas (ocho herramientas de Pro)

Las ocho herramientas MCP de Pro, por nombre de protocolo MCP. Los niveles de riesgo siguen el modelo HITL del servidor: segura (autoejecución, solo lectura), revisión (genera una salida que podría usarse de forma indebida; advertida en las instrucciones del agente) y aprobación requerida (debe ser confirmada por una persona).

`extract_text`

Propósito: Extracción de texto. Extrae la capa de texto de un PDF, opcionalmente limitada a un intervalo de páginas indexado desde 1.
Entradas: Un PDF (document_id o source); page_start y page_end opcionales.
Salidas: Texto extraído y recuento total de páginas.
Riesgo: Segura. Solo lectura e idempotente.
Límite: Extrae la capa de texto existente. No realiza OCR en páginas escaneadas o que solo contienen imágenes.

`segment_document`

Propósito: Segmentación estructural. Divide un PDF en secciones lógicas: título, encabezados, cuerpo, tablas, figuras.
Entradas: Un PDF (document_id o source).
Salidas: Un recuento de segmentos y una lista estructurada de segmentos.
Riesgo: Segura. Solo lectura e idempotente.
Límite: Segmentación estructural basada en el análisis de maquetación; no es un esquema semántico ni un árbol de estructura de PDF etiquetado.

`compare_pdfs`

Propósito: Diferencia estructural. Compara dos PDF y devuelve una diferencia estructurada de su contenido de texto.
Entradas: Dos PDF (source_a y source_b, cada uno una ruta, base64, URI de datos o document_id).
Salidas: Un indicador de identidad, un recuento total de cambios, recuentos de páginas por documento y una lista de regiones cambiadas con índices de página y de línea.
Riesgo: Segura. Solo lectura e idempotente.
Límite: Diferencia del contenido de texto. No compara el renderizado visual, las fuentes incrustadas ni la estructura binaria.

`redact_pii`

Propósito: Detección y enmascaramiento de PII. Detecta información de identificación personal en la capa de texto de un PDF y devuelve una vista enmascarada del texto.
Entradas: Un PDF (document_id o source); filtro types opcional (email, phone, ssn, credit_card).
Salidas: Un indicador de presencia de PII, el recuento detectado, el texto enmascarado y la lista de tipos analizados.
Riesgo: Revisión. La salida enmascarada podría usarse de forma indebida si se trata como un documento saneado.
Límite: Se trata de detección y enmascaramiento de patrones en la capa de texto, no de redacción visual. No elimina ni sobrescribe glifos en el PDF renderizado, y la coincidencia de patrones no garantiza que se encuentre cada instancia de datos sensibles. No trates su salida como una garantía de eliminación completa de PII. Para una redacción a nivel de documento que destruya el contenido subyacente, usa la superficie de redacción dedicada en las herramientas del servidor de código abierto o la edición Enterprise.

`fill_form`

Propósito: Datos de relleno de AcroForm. Genera datos XFDF (ISO 19444-1) que rellenan los campos de un AcroForm de PDF a partir de un mapa de nombres de campo a valores.
Entradas: Un mapa fields de nombre de campo a valor de cadena; un pdf_filename opcional incrustado como referencia del XFDF.
Salidas: El documento XFDF generado y el recuento de campos.
Riesgo: Revisión. Produce datos de formulario destinados a aplicarse a un documento.
Límite: Produce XFDF conforme con el estándar; no escribe por sí misma los valores de vuelta en un PDF. Aplica el XFDF con cualquier lector o herramienta de procesamiento conforme.

`extract_form_data`

Propósito: Relectura de AcroForm. Extrae nombres y valores de campos de AcroForm a partir del XFDF incrustado en un PDF.
Entradas: Un PDF (document_id o source).
Salidas: Un recuento de campos y un mapa de nombres de campo a valores; una nota explícita cuando no hay datos de formulario incrustados.
Riesgo: Segura. Solo lectura e idempotente.
Límite: Lee flujos XFDF (ISO 19444-1) incrustados. Un PDF que solo contiene valores de formulario en objetos AcroForm sin XFDF incrustado devuelve un resultado vacío.

`check_accessibility`

Propósito: Análisis de accesibilidad estructural. Analiza la accesibilidad estructural de un PDF —encabezados, párrafos, tablas e imágenes— e informa de los problemas probables con referencias a WCAG.
Entradas: Un PDF (document_id o source).
Salidas: Una puntuación estructural (0-100), una lista de problemas y un resumen de segmentos.
Riesgo: Segura. Solo lectura e idempotente.
Límite: Se trata de una heurística estructural, no de un veredicto de conformidad. Las pruebas completas de conformidad PDF/UA y WCAG —árbol de etiquetas, orden de lectura, contraste de color— requieren un motor de accesibilidad dedicado. Una puntuación alta no es una declaración de conformidad PDF/UA.

`sign_pdf`

Propósito: Firma digital PAdES B-B. Aplica una firma digital PAdES B-B (línea base) a un PDF usando un certificado X.509 local y una clave privada.
Entradas: Un PDF (document_id o source); un certificado PEM y una clave privada PKCS#8; un algoritmo opcional (RSA-SHA256 por defecto, RSA + SHA-3 256/384/512 o Ed25519); nombre del firmante y motivo opcionales; un sobre de transporte AES-GCM opcional alrededor de la carga útil de la clave privada.
Salidas: El PDF firmado, el recuento de firmas, el indicador de finalización y el algoritmo, el OID y el resumen utilizados.
Riesgo: Aprobación requerida. La firma es una operación destructiva y jurídicamente significativa; el servidor exige una confirmación humana explícita antes de ejecutarla.
Límite: Esta herramienta produce una firma PAdES B-B (línea base): no incrusta una marca de tiempo confiable ni material de validación a largo plazo. Los perfiles a largo plazo (B-LT / B-LTA), la custodia de claves respaldada por hardware y la firma con registro de auditoría forman parte de la edición Enterprise; B-T (una firma con marca de tiempo) está disponible en el motor Core cuando se configura un proveedor de marca de tiempo. Consulta la superficie de firma de Pro para conocer las capacidades de firma más amplias del paquete de Pro y la edición Enterprise para B-LT/B-LTA.

Cómo se exponen las herramientas

composer require nextpdf/pro
composer require nextpdf/server

Con ambos paquetes instalados, inicia NextPDF Server con el transporte que elijas. El servidor descubre el nivel Pro al arrancar y las ocho herramientas aparecen en la respuesta MCP tools/list bajo el nivel pro junto a las herramientas Core de código abierto. Tu aplicación no necesita ningún cambio de código: el descubrimiento se ejecuta automáticamente y un nivel ausente nunca impide que los demás se carguen.

El esquema autoritativo de entrada y salida de cada herramienta es el esquema que el servidor publica en su respuesta tools/list. Trata esa respuesta —y no esta página— como el contrato: este catálogo describe la intención y los límites; el esquema en vivo describe los nombres y tipos de campo exactos.

Código de ejemplo — Inicio rápido

Las herramientas de Pro se consumen mediante el protocolo MCP, no a través de una API de PHP de Pro. La integración del lado del host consiste en arrancar NextPDF Server. Con nextpdf/pro presente, las ocho herramientas se registran mediante el descubrimiento en tiempo de ejecución —sin cableado por herramienta— y el host las sirve entonces a los agentes.

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

Código de ejemplo — Producción

Endurece la ruta de arranque. Carga un archivo de política explícito, rehúsa iniciar ante una anulación de nivel de riesgo no válida y confirma que el nivel Pro se expuso antes de servir. El cableado en McpServer::create() lanza InvalidArgumentException cuando un bloque risk_level_overrides intenta debilitar una herramienta de aprobación requerida como sign_pdf, de modo que una política mal configurada falla de forma cerrada antes del bucle de servicio.

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

Orientación para producción

Restricción HITL. Mantén sign_pdf tras la confirmación humana. El servidor lo aplica a partir del nivel de riesgo declarado de la herramienta; no configures tu agente para eludirlo. Un operador solo puede endurecer el nivel de riesgo de una herramienta, nunca relajarlo.
Tratamiento de fuentes. Prefiere document_id para documentos que ya están en la sesión. Para datos en línea, las herramientas aceptan base64 y URI data:; las cargas útiles en línea muy grandes se ejecutan más despacio que un documento referenciado.
Expectativas sobre PII. Establece explícitamente las expectativas del llamador: redact_pii es una ayuda de detección y enmascaramiento, no una garantía de saneamiento. Para una eliminación irreversible, dirígelo a una superficie de redacción dedicada.
Claves de firma. Suministra las claves a través del sobre de cifrado de transporte cuando el transporte no sea confidencial de extremo a extremo. Trata el material de clave privada como un secreto en la política de registro de llamadas a herramientas de tu agente.
Registro de auditoría. Las herramientas por encima del nivel seguro son registradas para auditoría por el servidor. Asegúrate de que tu despliegue conserve esos registros según tus requisitos de cumplimiento.

Casos límite

Los intervalos de páginas de extract_text se indexan desde 1 y se ajustan al recuento real de páginas del documento; un extremo fuera de rango no produce error.
compare_pdfs requiere ambas fuentes; pasar una devuelve un error de validación claro en lugar de una diferencia parcial.
extract_form_data devuelve un resultado poblado y explícito de «sin datos de formulario incrustados» en lugar de un error para los PDF sin XFDF incrustado.
sign_pdf rechaza los identificadores de algoritmo no admitidos con la lista de valores admitidos; Ed25519 requiere la extensión libsodium y las variantes de SHA-3 requieren una compilación de OpenSSL con compatibilidad con SHA-3.
check_accessibility puntúa por diseño bajo los PDF que solo contienen imágenes: señala la ausencia de una capa de texto legible en lugar de fallar.

Notas de seguridad

La herramienta de firma es la única que requiere aprobación; el servidor no la autoejecutará.
El sobre AES-GCM opcional alrededor de la clave privada autentica la carga útil; una discrepancia de etiqueta falla de forma cerrada con un error de descifrado y nunca recurre al uso del texto cifrado.
redact_pii no altera el PDF de origen; devuelve una representación de texto enmascarada. No es un sustituto de la destrucción de contenido.
La herramienta valida las entradas antes de cualquier trabajo del motor; rechaza fuentes, URI de datos y cargas útiles base64 malformadas con errores explícitos.

Conformidad

Las herramientas de formulario producen y consumen XFDF conforme a ISO 19444-1:2019 (XML Forms Data Format).
sign_pdf produce una firma PAdES de línea base (B-B) alineada con la familia PAdES de ETSI EN 319 142; los perfiles a largo plazo son una capacidad de Enterprise, y B-T está disponible en el motor Core cuando se configura un proveedor de marca de tiempo.
check_accessibility informa de los hallazgos con referencias a criterios de éxito de WCAG (por ejemplo, 1.1.1, 1.3.1, 2.4.6) como orientación heurística, no como una certificación de conformidad.

Límite de edición

NextPDF Pro aporta exactamente ocho herramientas MCP, todas en el nivel pro. La edición Enterprise incluye su propio conjunto independiente de herramientas MCP en el nivel enterprise, que abarca la comprobación de cumplimiento, el análisis forense, el estado de validación a largo plazo, la certificación lista para IA y la búsqueda e incrustación de documentos. Esas herramientas, sus entradas y su funcionamiento interno quedan fuera del alcance de esta página; consulta las herramientas MCP de Enterprise. La propia documentación del servidor cubre las herramientas Core (de código abierto) que se incluyen con él. El servidor descubre los tres niveles de forma independiente, y un nivel ausente nunca deshabilita los demás.

Nota sobre el límite de Enterprise

Pro aporta exactamente ocho herramientas MCP en el nivel pro. La edición Enterprise incluye un conjunto independiente de herramientas MCP en el nivel enterprise (comprobación de cumplimiento, análisis forense, estado de validación a largo plazo, certificación lista para IA, búsqueda e incrustación de documentos) y los perfiles de firma con marca de tiempo/a largo plazo; el nivel Pro no los proporciona. Consulta la sección Límite de edición anterior para el desglose completo de niveles.

Alternativa / opción de respaldo en Core

El NextPDF Server de código abierto ofrece a cualquier agente de IA un conjunto de herramientas PDF Core determinista (creación de documentos, texto, tablas, diagnósticos) sin licencia. Las ocho herramientas avanzadas de esta página son adiciones de Pro. Consulta /connect/tools/.

Límite de publicación

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