Pro edición

Herramientas MCP — Referencia detallada

Disponibilidad y licencia

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. Compare las ediciones y obtenga una licencia.

No hay ningún indicador de licencia por característica. El código se incluye con la edición Pro, y las ocho herramientas se registran en el nivel pro cuando el paquete Pro se resuelve en el arranque junto a nextpdf/server.

Contrato de comportamiento

NextPDF Server descubre los niveles en el arranque sondeando en busca de la clase proveedora de herramientas de Pro; si se resuelve, el servidor registra las ocho herramientas en el nivel pro. El paquete Pro no es una dependencia obligatoria del servidor, por lo que las herramientas de Pro son estrictamente opcionales mediante coinstalación. El registro de niveles es independiente: un nivel ausente o excluido por política nunca bloquea a los demás.
Cada herramienta declara uno de cuatro niveles de riesgo (safe, caution, review, approval-required). Una anulación opcional del operador solo puede elevar el nivel de una herramienta, nunca rebajarlo; el servidor registra en la auditoría cualquier ejecución de nivel caution o superior. sign_pdf es approval-required.
La entrada de PDF se resuelve en un orden fijo: document_id desde el almacén en memoria, luego source como URI data:, ruta del sistema de archivos o base64 en bruto. La entrada ausente devuelve un error de validación en lugar de procesar un documento vacío.
sign_pdf produce únicamente una firma de línea base PAdES B-B — sin marca de tiempo, sin validación a largo plazo. Los algoritmos admitidos y el sobre de transporte de clave AES-GCM se detallan más abajo; el descifrado falla de forma cerrada y la herramienta nunca usa el texto cifrado como material de clave.
Consulte las secciones siguientes para conocer todos los detalles de descubrimiento, riesgo, resolución de origen, por herramienta y de firma. Esta página describe únicamente el comportamiento observable desde fuera y el contrato de herramientas publicado.

Alcance

Esta página es la referencia para operadores e integradores de las ocho herramientas MCP de Pro. Cubre el modelo de descubrimiento, la semántica de riesgo/HITL que aplica el servidor, las reglas de resolución de origen, el sobre de transporte de clave de firma y el comportamiento ante fallos de cada herramienta. Describe únicamente el comportamiento observable desde fuera y el contrato de herramientas publicado. Para el catálogo orientado al usuario, consulte la página pública de MCP.

Modelo de descubrimiento y registro

NextPDF Server descubre los proveedores de nivel en el arranque. Detecta el nivel Pro sondeando en busca de la clase proveedora de herramientas de Pro; si la clase se resuelve, el servidor instancia el proveedor y registra cada herramienta que devuelve en el nivel pro. El paquete Pro no es, intencionadamente, una dependencia obligatoria del servidor — esto mantiene el servidor de código abierto instalable sin el paquete propietario y hace que las herramientas de Pro sean estrictamente opcionales mediante coinstalación.

El servidor aísla el registro por nivel. Si el paquete Pro está ausente, las herramientas de Core se siguen registrando; un proveedor de nivel presente no bloquea a otros niveles. El registro de herramientas también está sujeto a la lista de permitidos de la política de seguridad del servidor: una herramienta excluida por la política simplemente no se registra y no se contabiliza en el resumen del nivel. El servidor expone un recuento por nivel (core / pro / enterprise) para diagnósticos y registro.

El proveedor devuelve las ocho herramientas en un orden fijo: extracción de texto, segmentación, comparación, enmascaramiento de PII, relleno de formularios, lectura de formularios, análisis de accesibilidad, firma. El orden es estable, pero los llamantes no deben depender de él — resuelva las herramientas por su nombre de protocolo MCP.

Modelo de riesgo y semántica de HITL

Cada herramienta declara uno de cuatro niveles de riesgo. El servidor utiliza el nivel declarado para la aplicación con intervención humana (human-in-the-loop):

Safe — solo lectura, sin efectos secundarios. Se ejecuta automáticamente.
Caution — crea o modifica estado en memoria. Se ejecuta automáticamente con una entrada en el registro de auditoría.
Review — produce una salida que podría usarse de forma indebida. Se ejecuta automáticamente, pero las instrucciones de la skill del agente lo marcan para que el agente avise al usuario.
Approval-required — destructiva, jurídica o crítica para la privacidad. El servidor exige una confirmación humana explícita antes de la ejecución.

Clasificaciones de las herramientas de Pro: las cinco herramientas de extracción/análisis (extract_text, segment_document, compare_pdfs, extract_form_data, check_accessibility) son safe; redact_pii y fill_form son review; sign_pdf es approval-required.

El nivel de riesgo proviene de exactamente dos fuentes: la propia declaración de la herramienta y una anulación opcional del operador en tiempo de ejecución. La anulación solo puede elevar el nivel de riesgo de una herramienta (endurecer la aplicación); nunca puede rebajarlo. El servidor registra en la auditoría cualquier ejecución de nivel caution o superior. El modelo de riesgo lleva una versión; el servidor anuncia esa versión en su respuesta de inicialización para que los clientes puedan detectar un cambio incompatible.

Orden de resolución de origen

Toda herramienta que recibe un PDF lo acepta a través de una de tres formas de entrada, resueltas en este orden:

document_id — el servidor recupera los bytes de su almacén de documentos en memoria. Un id desconocido falla con un error explícito que indica al llamante que cree primero el documento.
source como URI data: — la herramienta decodifica el cuerpo base64 que sigue a la coma.
source como ruta del sistema de archivos — la herramienta lee desde el disco cuando la ruta resuelve a un archivo.
source como cadena base64 en bruto — la herramienta acepta y decodifica únicamente entradas suficientemente largas y con forma de base64.

compare_pdfs aplica la misma resolución de forma independiente a source_a y source_b, y además acepta un valor document_id en cualquiera de las dos ranuras de origen. Si no se suministra ni un document_id ni un source, la herramienta devuelve un error de validación en lugar de procesar un documento vacío.

Referencia por herramienta

Herramienta	Riesgo	Entradas	Campos de resultado	Límite de comportamiento
`extract_text`	safe	PDF; `page_start` / `page_end` opcionales con índice base 1	texto, recuento total de páginas	Solo capa de texto; los rangos se ajustan al recuento real de páginas; sin OCR
`segment_document`	safe	PDF	recuento de segmentos, lista de segmentos	Segmentos derivados de la maquetación; no es un árbol de estructura de PDF etiquetado
`compare_pdfs`	safe	dos PDF	indicador de identidad, total de cambios, recuentos de páginas por documento, regiones (tipo, texto, índice de página, índice de línea, texto homólogo opcional)	Comparación de contenido textual; no visual ni binaria
`redact_pii`	review	PDF; `types` opcionales (`email`, `phone`, `ssn`, `credit_card`)	indicador de presencia de PII, recuento detectado, texto enmascarado, tipos escaneados	Detección/enmascaramiento en la capa de texto; no es redacción visual; basada en patrones, no exhaustiva
`fill_form`	review	mapa de `fields`; `pdf_filename` opcional	documento XFDF, recuento de campos	Produce XFDF (ISO 19444-1); no escribe valores dentro de un PDF
`extract_form_data`	safe	PDF	recuento de campos, mapa de campos, nota explícita cuando no hay ninguno	Lee únicamente el XFDF incrustado
`check_accessibility`	safe	PDF	puntuación estructural (0–100), incidencias, resumen de segmentos	Heurística estructural con referencias WCAG; no es un veredicto de conformidad
`sign_pdf`	approval-required	PDF; certificado PEM + clave PKCS#8; algoritmo, nombre del firmante, motivo y sobre de transporte opcionales	PDF firmado, recuento de firmas, indicador de finalización, algoritmo, OID, resumen	Solo línea base PAdES B-B; sin marca de tiempo, sin LTV

Firma: algoritmos y transporte de clave

sign_pdf produce una firma de línea base PAdES B-B. Algoritmos admitidos, aceptados tanto en grafía con guion bajo como con guion:

RSA con SHA-256 (predeterminado).
RSA con SHA-3 256 / 384 / 512 — requiere una compilación de OpenSSL con soporte de SHA-3.
Ed25519 — requiere la extensión libsodium; la clave debe ser un PEM PKCS#8 que envuelva la clave privada Ed25519.

La herramienta rechaza los identificadores no admitidos y devuelve la lista de valores aceptados.

El sobre opcional de cifrado de transporte permite a un llamante hacer pasar la clave privada a través de un transporte que no es confidencial de extremo a extremo. El sobre es únicamente AES-GCM:

Clave simétrica: 16, 24 o 32 bytes (AES-128/192/256), codificada en base64.
Nonce: exactamente 12 bytes, codificado en base64.
Datos adicionales autenticados opcionales, codificados en base64.
La carga útil private_key es el texto cifrado en base64 con una etiqueta de autenticación GCM de 16 bytes al final.

El descifrado falla de forma cerrada: un desajuste de la etiqueta de autenticación o una carga útil malformada devuelven un error de descifrado, y la herramienta nunca usa el texto cifrado como material de clave. La herramienta rechaza tamaños incorrectos de clave o nonce antes de cualquier trabajo criptográfico.

Casos límite y modo FIPS

extract_text: la herramienta ajusta un final de rango de páginas que supera el documento en lugar de rechazarlo, y normaliza un inicio por debajo de la primera página a la primera página.
compare_pdfs: la ausencia de source_a o source_b devuelve un error de validación; los documentos idénticos devuelven un resultado de identidad explícito con cero cambios.
extract_form_data: los PDF sin un flujo XFDF incrustado devuelven un resultado de cero campos con una nota explicativa, no un error.
redact_pii: una entrada no reconocida en types se ignora; una lista totalmente no reconocida produce un escaneo vacío en lugar de un fallo.
sign_pdf: la ausencia de un certificado o de una clave privada falla antes de cualquier trabajo de firma; la herramienta comprueba los requisitos del algoritmo (soporte de SHA-3 en OpenSSL, libsodium para Ed25519) en el momento de la firma y los expone como errores explícitos.
Modo FIPS: la disponibilidad de algoritmos sigue la compilación de OpenSSL/libsodium del host. En una compilación con restricciones FIPS, los algoritmos no aprobados fallan en el límite criptográfico con un error explícito en lugar de degradarse silenciosamente. La capa MCP no añade ni relaja la política criptográfica — expone la decisión del proveedor criptográfico del host.

Notas del runbook del operador

Mantenga sign_pdf como approval-required. Confirme que no exista ninguna anulación del operador que eleve sin intención el riesgo de las herramientas safe — las anulaciones solo endurecen, por lo que una anulación accidental degrada la disponibilidad, no la seguridad.
Conservación de auditoría: el servidor registra en la auditoría toda ejecución de nivel review o superior. Dimensione la conservación de sus registros para el volumen de llamadas a redact_pii, fill_form y sign_pdf.
Elección de transporte: al ejecutar sobre un transporte que no es confidencial de extremo a extremo, exija el sobre de transporte de clave AES-GCM para sign_pdf y trate el material de clave privada como un secreto en la política de registro de llamadas a herramientas de su agente.
Recuentos de nivel: use el recuento por nivel del servidor para afirmar en el momento del despliegue que el nivel Pro registró ocho herramientas; un recuento de cero indica que el paquete Pro no se resolvió.

Límite de edición

El nivel Pro aporta exactamente ocho herramientas MCP. La edición Enterprise incluye un nivel MCP independiente con sus propias herramientas — cumplimiento, análisis forense, salud de validación a largo plazo, certificación lista para IA y búsqueda/incrustación de documentos. Las entradas, salidas e interioridades de las herramientas de Enterprise quedan fuera del alcance de esta página y se documentan con la edición Enterprise. El servidor descubre los niveles de forma independiente; un nivel ausente nunca deshabilita otro.

Límite de publicación

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