MCP — Referencia detallada

De un vistazo

El espacio de nombres NextPDF\Enterprise\Mcp incluye el nivel Enterprise del catálogo de herramientas MCP de NextPDF. Su superficie pública son once clases de herramienta, una fábrica de clientes y una excepción tipada. Cada herramienta implementa el contrato NextPDF\Server\Tools\ToolInterface del runtime nextpdf/server y declara ToolTier::Enterprise. Seis herramientas analizan un único PDF en el propio proceso. Cuatro herramientas delegan las cargas de trabajo por lotes y de RAG en el sidecar Spectrum a través de NextPDF\Enterprise\Mcp\SpectrumClientFactory. Una herramienta lee un registro de auditoría de mutaciones del AST inyectado por constructor en lugar de bytes de PDF. Cada herramienta se autodescribe con su nombre MCP, su entrada de JSON Schema, sus anotaciones de cliente, su RiskLevel y su categoría.

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 ese derecho no carga las clases de la capacidad. Comparar ediciones y obtener una licencia.

Superficie de API pública

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
ForensicAnalyzeTool::execute	array $arguments, InMemoryDocumentStore $store; args: document_id o source	Ejecuta análisis forense: revisiones, actualizaciones incrementales, firmas	ToolResult (informe JSON)	ToolResult de error; las excepciones se capturan, nunca se relanzan	Herramienta forensic_analyze; RiskLevel::Safe; de solo lectura, idempotente; categoría document; desde 2.0.0
BatchForensicAnalyzeTool::execute	args: workspace_token, documents[] (cada uno id + path)	Análisis forense por lotes a través del sidecar Spectrum	ToolResult con status por documento y recuentos de éxitos y fallos	ToolResult de error (argumentos faltantes, fallo del sidecar)	Herramienta batch_forensic_analyze; RiskLevel::Safe; categoría document; desde 2.1.0
ComplianceCheckTool::execute	args: policy (enum de 12 valores), document_id o source	Evalúa el PDF frente a una política de conformidad nombrada	ToolResult con hallazgos, aprobado/no aprobado, duration_ms y un campo disclaimer	ToolResult de error; una política desconocida devuelve un error que enumera las claves admitidas	Herramienta compliance_check; RiskLevel::Review; categoría document; desde 2.0.0
BatchComplianceCheckTool::execute	args: workspace_token, documents[], policies (pdfa, pades, zugferd; predeterminado ["pdfa"])	Comprobaciones de conformidad por lotes a través del sidecar Spectrum	ToolResult con recuentos de conformes / no conformes	ToolResult de error; cada elemento de documents[] se valida para id y path no vacíos	Herramienta batch_compliance_check; RiskLevel::Safe; categoría document; desde 2.1.0
LtvHealthCheckTool::execute	args: document_id o source	Ejecuta la política de salud LTV sobre un PDF firmado	ToolResult con hallazgos y aprobado/no aprobado	ToolResult de error	Herramienta ltv_health_check; RiskLevel::Safe; categoría document; desde 2.0.0
AiReadyCertifyTool::execute	args: document_id o source	Evaluación de preparación para IA de solo lectura sobre cuatro criterios	ToolResult con certification_level (certified, partial, not_certified) y booleanos por criterio	ToolResult de error	Herramienta ai_ready_certify; RiskLevel::Review; de solo lectura; categoría document; desde 2.0.0
CertifyAiReadyTool::execute	args: document_id o source, return_stamped_pdf (predeterminado true)	Evalúa tres criterios y añade un sello de procedencia XMP	ToolResult; incluye stamped_pdf_base64 salvo que esté desactivado o not_certified	ToolResult de error	Herramienta certify_ai_ready; RiskLevel::Review; no es de solo lectura; categoría document; desde 3.0.0
AstAwareChunkTool::execute	args: document_id o source, max_chunk_chars (predeterminado 1500), overlap_chars (predeterminado 150)	Construye el AST y emite fragmentos anclados a citas con procedencia	ToolResult con chunk_count y, por fragmento, ID de nodo, índice de página, bbox y tipo de nodo	ToolResult de error	Herramienta ast_aware_chunk; RiskLevel::Review; categoría extraction; desde 3.0.0
AuditAstMutationsTool::__construct	AstAuditTrailInterface $auditTrail	Inyecta el backend del registro de auditoría	instancia	—	Dependencia inyectada por constructor; desde 3.0.0
AuditAstMutationsTool::execute	args: document_source_hash (hex SHA-256, obligatorio)	Devuelve todos los eventos de mutación del AST registrados para ese documento	ToolResult con entries[] y count	ToolResult de error cuando el argumento falta o está vacío	Herramienta audit_ast_mutations; RiskLevel::Review; categoría document; desde 3.0.0
EmbedDocumentsTool::execute	args: collection_id, workspace_token, documents[] (todos obligatorios)	Ingiere PDF en una colección RAG a través del sidecar Spectrum	ToolResult con recuentos de éxitos / total / fallos	ToolResult de error	Herramienta embed_documents; RiskLevel::Caution; no es de solo lectura, no es idempotente; categoría extraction; desde 2.1.0
SearchDocumentsTool::execute	args: collection_id, query (obligatorio), top_k (predeterminado 10, acotado 1–100), mode (hybrid, bm25, semantic)	Recuperación híbrida sobre una colección ingerida	ToolResult con fragmentos clasificados y puntuaciones de relevancia	ToolResult de error; un mode fuera de la lista de permitidos se rechaza	Herramienta search_documents; RiskLevel::Safe; categoría extraction; desde 2.1.0
SpectrumClientFactory::create	ninguno (lee SPECTRUM_URL, SPECTRUM_TIMEOUT, SPECTRUM_AUTH_TOKEN, SPECTRUM_APP_SECRET)	Construye y almacena en caché un único cliente de sidecar para todo el proceso	SpectrumClient	InvalidArgumentException cuando SPECTRUM_URL está malformada o apunta a una dirección bloqueada	Endpoint predeterminado http://127.0.0.1:7800; tiempo de espera 30.0 s; desde 2.1.0
SpectrumClientFactory::reset	ninguno	Borra la instancia de cliente en caché	void	—	Pensado para pruebas
SpectrumClientFactory::createRequest	string $method, $uri (string o UriInterface)	Construye una solicitud PSR-7 a partir de clases HTTP de Core	RequestInterface	—	Implementación de RequestFactoryInterface de PSR-17
SpectrumClientFactory::createStream	string $content = ''	Construye un flujo PSR-7 en memoria	StreamInterface	—	Implementación de StreamFactoryInterface de PSR-17
SpectrumClientFactory::createStreamFromFile	string $filename, string $mode = 'r'	Abre el archivo y lo envuelve como un flujo	StreamInterface	McpStreamException cuando el archivo no se puede abrir	McpStreamException extiende RuntimeException
SpectrumClientFactory::createStreamFromResource	$resource (recurso PHP)	Envuelve un recurso existente como un flujo	StreamInterface	—	Implementación de StreamFactoryInterface de PSR-17
McpStreamException	—	Fallo tipado de adquisición de flujo	—	—	final class, extiende RuntimeException; la fuente documenta la compatibilidad con PSR-17 §1.5; la fuente la anota como @since 3.2.0 (presente en la línea de desarrollo actual con alias 3.1.0)

Cada herramienta también expone los métodos de autodescripción de ToolInterface: name, description, inputSchema, annotations, riskLevel, tier y category. Sus valores por herramienta aparecen en la columna Notas anterior.

Firmas de los puntos de entrada, textuales de la fuente:

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

Contrato de comportamiento

• Cada herramienta implementa NextPDF\Server\Tools\ToolInterface y declara ToolTier::Enterprise de forma explícita. El nivel nunca se infiere del espacio de nombres ni del empaquetado.
• execute no lanza excepciones. Cada fallo se captura y se devuelve como un ToolResult de error que lleva el mensaje del fallo.
• Las herramientas de documento único resuelven los bytes del PDF con una prioridad fija. Primero se busca un document_id en el InMemoryDocumentStore. En caso contrario, source se interpreta como un URI data:, luego como base64 sin procesar (más de 256 caracteres) y finalmente como una ruta de archivo.
• Las rutas source del sistema de archivos están desactivadas de forma predeterminada. Solo se activan cuando la variable de entorno NEXTPDF_MCP_INPUT_DIR nombra un directorio de entrada confinado. La ruta real resuelta debe permanecer dentro de ese directorio. Todo lo demás falla de forma cerrada.
• Los esquemas de contenedor de flujos (phar://, php://, file:// y cualquier otro esquema) y los bytes nulos en un source de ruta de archivo se rechazan antes de cualquier llamada al sistema de archivos. Los escapes por recorrido de directorios y por enlaces simbólicos fracasan frente a la comprobación de confinamiento de ruta real.
• Las herramientas respaldadas por el sidecar (embed_documents, search_documents, batch_compliance_check, batch_forensic_analyze) obtienen su cliente de SpectrumClientFactory::create. La fábrica valida una SPECTRUM_URL que no sea localhost frente a rangos de direcciones privadas y reservadas antes de usarla. Se permite localhost explícito para el modo de sidecar local.
• ai_ready_certify deriva su nivel de cuatro criterios: integridad forense, presencia de firma, validez LTV y ausencia de cifrado. Que los cuatro se cumplan produce certified; de uno a tres produce partial; cero produce not_certified. La integridad forense es una heurística estructural sobre la cadena de revisiones, no una verificación criptográfica de integridad de bytes. La comprobación de cifrado inspecciona únicamente la región del tráiler.
• certify_ai_ready evalúa tres criterios y añade un sello de procedencia XMP. Los bytes sellados se devuelven codificados en base64 salvo que return_stamped_pdf sea false o el nivel sea not_certified.
• compliance_check acepta exactamente doce claves de política: pdfa4, pdfa4e, pdfa4f, pades-baseline, ltv-health, eidas-qualified, zugferd, fda-part11, sec-17a4, sec-17a4-compatible, sec-17a4-structural, sec-17a4-pre-sign. Una clave desconocida devuelve un resultado de error que nombra el conjunto admitido.
• audit_ast_mutations lee únicamente el AstAuditTrailInterface inyectado. No registra nada por sí mismo.

Casos límite y modos de fallo

• No se proporciona ni document_id ni source: resultado de error que indica al llamador que aporte uno de ellos.
• document_id desconocido: resultado de error que nombra el ID y remite a create_pdf.
• source del sistema de archivos con NEXTPDF_MCP_INPUT_DIR sin definir: se rechaza con un mensaje que nombra los canales admitidos.
• Una ruta source que se resuelve fuera del directorio de entrada configurado, incluso mediante enlace simbólico: se rechaza. La comparación se realiza en el límite del separador de directorios, por lo que directorios hermanos que comparten un prefijo de nombre no pueden pasar.
• URI data: sin separador de coma, o carga base64 no válida: resultado de error.
• top_k de search_documents fuera de 1–100: se acota, no se rechaza. Un top_k no entero recurre al valor predeterminado configurado del pipeline.
• mode de search_documents fuera de hybrid, bm25, semantic: resultado de error de la lista de permitidos del pipeline.
• Un elemento de documents[] de batch_compliance_check sin id o path, o con cadenas vacías: resultado de error que nombra el índice infractor. batch_forensic_analyze valida únicamente la forma del array externo; los defectos de los elementos afloran desde la capa de lotes.
• SpectrumClientFactory::create con una SPECTRUM_URL malformada, o que apunta a una dirección privada, de enlace local o de metadatos: InvalidArgumentException. Dentro del execute de una herramienta esto aflora como un resultado de error.
• SpectrumClientFactory::createStreamFromFile sobre una ruta no legible: McpStreamException.
• Las variables de entorno vacías se tratan como no definidas y recurren a los valores predeterminados.

Conformidad

NextPDF no posee ninguna certificación ni concede ninguna. Las herramientas MCP informan evaluaciones a nivel de capacidad; la compatibilidad no es conformidad, y la conformidad no es certificación. Los valores de certification_level que devuelven ai_ready_certify y certify_ai_ready son el vocabulario declarado por las propias herramientas. No constituyen una atestación de terceros. Las respuestas de compliance_check incluyen un campo disclaimer producido por el informe subyacente por la misma razón. Las referencias a cláusulas de política, como la base de la política LTV que la fuente del producto indica como ISO 32000-2:2020 §12.8.4.3, se transportan en las descripciones de las herramientas y en los campos clause por hallazgo; esta página no añade afirmaciones de normas independientes. Que un documento comprobado satisfaga una regulación es una determinación del operador y de sus evaluadores.

Notas de desarrollo

• SpectrumClientFactory::create almacena en caché un cliente por proceso. Para forzar un cliente nuevo, llamar a SpectrumClientFactory::reset en la configuración de las pruebas.
• Las lecturas de entorno consultan $_ENV, luego $_SERVER, luego getenv, y tratan las cadenas vacías como ausentes.
• RiskLevel dirige el tratamiento del lado del host en el runtime del servidor: Safe se ejecuta automáticamente, Caution y superiores quedan registrados en auditoría, y ApprovalRequired exige confirmación humana. Ninguna herramienta MCP de Enterprise declara ApprovalRequired. Las anulaciones del operador pueden elevar un nivel declarado, nunca reducirlo.
• Los valores de annotations (readOnlyHint, idempotentHint) son sugerencias para el cliente MCP, no una imposición. El confinamiento y la validación ocurren del lado del servidor con independencia de las sugerencias.
• Las herramientas informan valores de category document o extraction para el filtrado de tools/list.
• AuditAstMutationsTool es la única herramienta que requiere inyección por constructor; debe registrarse con una implementación concreta de AstAuditTrailInterface.

Consulte también

• MCP (página de capacidad)
• Accelerator — Referencia detallada — la superficie de cliente del sidecar Spectrum.
• Análisis forense — Referencia detallada — el analizador detrás de forensic_analyze.
• Cumplimiento — Referencia detallada — las políticas detrás de compliance_check.
• AST — Referencia detallada — la fragmentación y el registro de auditoría de mutaciones.
• Validation — Referencia detallada

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 internas, las clases auxiliares, las tablas de mecanismos, los nombres de archivo de runbook y los prefijos de tickets quedan fuera de alcance.