MCP — Referência Profunda

Visão geral

O namespace NextPDF\Enterprise\Mcp entrega o nível Enterprise do catálogo de ferramentas MCP do NextPDF. Sua superfície pública é composta por onze classes de ferramenta, uma factory de cliente e uma exceção tipada. Cada ferramenta implementa o contrato NextPDF\Server\Tools\ToolInterface do runtime nextpdf/server e declara ToolTier::Enterprise. Seis ferramentas analisam um único PDF em processo. Quatro ferramentas delegam cargas de trabalho de lote e RAG ao sidecar Spectrum através de NextPDF\Enterprise\Mcp\SpectrumClientFactory. Uma ferramenta lê uma trilha de auditoria de mutações de AST injetada por construtor em vez dos bytes do PDF. Cada ferramenta se autodescreve com seu nome MCP, entrada em JSON Schema, anotações de cliente, RiskLevel e categoria.

Disponibilidade e licenciamento

Este recurso é entregue no NextPDF Enterprise (nextpdf/enterprise) e é ativado com um envelope de licença do nível Enterprise. Uma implantação sem essa habilitação não carrega as classes do recurso. Compare as edições e obtenha uma licença.

Superfície da API pública

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
ForensicAnalyzeTool::execute	array $arguments, InMemoryDocumentStore $store; args: document_id ou source	Executa análise forense: revisões, atualizações incrementais, assinaturas	ToolResult (relatório JSON)	ToolResult de erro; exceções são capturadas, nunca relançadas	Ferramenta forensic_analyze; RiskLevel::Safe; somente leitura, idempotente; categoria document; desde 2.0.0
BatchForensicAnalyzeTool::execute	args: workspace_token, documents[] (cada um com id + path)	Análise forense em lote via o sidecar Spectrum	ToolResult com status por documento, contagens de sucesso e falha	ToolResult de erro (argumentos ausentes, falha do sidecar)	Ferramenta batch_forensic_analyze; RiskLevel::Safe; categoria document; desde 2.1.0
ComplianceCheckTool::execute	args: policy (enum de 12 valores), document_id ou source	Avalia o PDF contra uma política de conformidade nomeada	ToolResult com constatações, aprovação/reprovação, duration_ms e um campo disclaimer	ToolResult de erro; política desconhecida retorna um erro listando as chaves suportadas	Ferramenta compliance_check; RiskLevel::Review; categoria document; desde 2.0.0
BatchComplianceCheckTool::execute	args: workspace_token, documents[], policies (pdfa, pades, zugferd; padrão ["pdfa"])	Verificações de conformidade em lote via o sidecar Spectrum	ToolResult com contagens de conformes / não conformes	ToolResult de erro; cada elemento de documents[] é validado para id e path não vazios	Ferramenta batch_compliance_check; RiskLevel::Safe; categoria document; desde 2.1.0
LtvHealthCheckTool::execute	args: document_id ou source	Executa a política de saúde de LTV sobre um PDF assinado	ToolResult com constatações e aprovação/reprovação	ToolResult de erro	Ferramenta ltv_health_check; RiskLevel::Safe; categoria document; desde 2.0.0
AiReadyCertifyTool::execute	args: document_id ou source	Avaliação somente leitura de prontidão para IA sobre quatro critérios	ToolResult com certification_level (certified, partial, not_certified) e booleanos por critério	ToolResult de erro	Ferramenta ai_ready_certify; RiskLevel::Review; somente leitura; categoria document; desde 2.0.0
CertifyAiReadyTool::execute	args: document_id ou source, return_stamped_pdf (padrão true)	Avalia três critérios e anexa um carimbo de proveniência XMP	ToolResult; inclui stamped_pdf_base64 a menos que desabilitado ou not_certified	ToolResult de erro	Ferramenta certify_ai_ready; RiskLevel::Review; não é somente leitura; categoria document; desde 3.0.0
AstAwareChunkTool::execute	args: document_id ou source, max_chunk_chars (padrão 1500), overlap_chars (padrão 150)	Constrói a AST e emite chunks ancorados em citações com proveniência	ToolResult com chunk_count e, por chunk, ID de nó, índice de página, bbox, tipo de nó	ToolResult de erro	Ferramenta ast_aware_chunk; RiskLevel::Review; categoria extraction; desde 3.0.0
AuditAstMutationsTool::__construct	AstAuditTrailInterface $auditTrail	Injeta o backend da trilha de auditoria	instância	—	Dependência injetada por construtor; desde 3.0.0
AuditAstMutationsTool::execute	args: document_source_hash (hex SHA-256, obrigatório)	Retorna todos os eventos de mutação de AST registrados para aquele documento	ToolResult com entries[] e count	ToolResult de erro quando o argumento está ausente ou vazio	Ferramenta audit_ast_mutations; RiskLevel::Review; categoria document; desde 3.0.0
EmbedDocumentsTool::execute	args: collection_id, workspace_token, documents[] (todos obrigatórios)	Ingere PDFs em uma coleção RAG via o sidecar Spectrum	ToolResult com contagens de sucesso / total / falha	ToolResult de erro	Ferramenta embed_documents; RiskLevel::Caution; não é somente leitura, não é idempotente; categoria extraction; desde 2.1.0
SearchDocumentsTool::execute	args: collection_id, query (obrigatório), top_k (padrão 10, limitado a 1–100), mode (hybrid, bm25, semantic)	Recuperação híbrida sobre uma coleção ingerida	ToolResult com chunks ranqueados e pontuações de relevância	ToolResult de erro; um mode fora da allowlist é rejeitado	Ferramenta search_documents; RiskLevel::Safe; categoria extraction; desde 2.1.0
SpectrumClientFactory::create	nenhum (lê SPECTRUM_URL, SPECTRUM_TIMEOUT, SPECTRUM_AUTH_TOKEN, SPECTRUM_APP_SECRET)	Constrói e faz cache de um cliente de sidecar único para todo o processo	SpectrumClient	InvalidArgumentException quando SPECTRUM_URL está malformado ou aponta para um endereço bloqueado	Endpoint padrão http://127.0.0.1:7800; timeout 30.0 s; desde 2.1.0
SpectrumClientFactory::reset	nenhum	Limpa a instância de cliente em cache	void	—	Destinado a testes
SpectrumClientFactory::createRequest	string $method, $uri (string ou UriInterface)	Constrói uma requisição PSR-7 a partir das classes HTTP do Core	RequestInterface	—	Implementação PSR-17 de RequestFactoryInterface
SpectrumClientFactory::createStream	string $content = ''	Constrói um stream PSR-7 em memória	StreamInterface	—	Implementação PSR-17 de StreamFactoryInterface
SpectrumClientFactory::createStreamFromFile	string $filename, string $mode = 'r'	Abre o arquivo e o envolve como um stream	StreamInterface	McpStreamException quando o arquivo não pode ser aberto	McpStreamException estende RuntimeException
SpectrumClientFactory::createStreamFromResource	$resource (recurso PHP)	Envolve um recurso existente como um stream	StreamInterface	—	Implementação PSR-17 de StreamFactoryInterface
McpStreamException	—	Falha tipada de aquisição de stream	—	—	final class, estende RuntimeException; a fonte documenta compatibilidade com PSR-17 §1.5; a fonte a anota como @since 3.2.0 (presente na linha de dev atual com alias 3.1.0)

Cada ferramenta também expõe os métodos de autodescrição de ToolInterface: name, description, inputSchema, annotations, riskLevel, tier e category. Seus valores por ferramenta aparecem na coluna Notas acima.

Assinaturas do ponto de entrada, textuais da fonte:

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 comportamento

• Cada ferramenta implementa NextPDF\Server\Tools\ToolInterface e declara ToolTier::Enterprise explicitamente. O tier nunca é inferido do namespace ou do empacotamento.
• execute não lança exceções. Cada falha é capturada e retornada como um ToolResult de erro carregando a mensagem de falha.
• Ferramentas de documento único resolvem os bytes do PDF com uma prioridade fixa. Um document_id é procurado primeiro no InMemoryDocumentStore. Caso contrário, source é interpretado como uma URI data:, depois como base64 bruto (acima de 256 caracteres) e, por fim, como um caminho de arquivo.
• Caminhos de arquivo em source estão desabilitados por padrão. Eles são ativados somente quando a variável de ambiente NEXTPDF_MCP_INPUT_DIR nomeia um diretório de entrada confinado. O caminho real resolvido deve permanecer dentro desse diretório. Todo o resto falha de forma fechada.
• Esquemas de stream-wrapper (phar://, php://, file:// e qualquer outro esquema) e bytes nulos em um source de caminho de arquivo são rejeitados antes de qualquer chamada ao sistema de arquivos. Travessia (traversal) e escapes por symlink falham na verificação de confinamento por caminho real.
• Ferramentas apoiadas por sidecar (embed_documents, search_documents, batch_compliance_check, batch_forensic_analyze) obtêm seu cliente de SpectrumClientFactory::create. A factory valida um SPECTRUM_URL não-localhost contra faixas de endereços privados e reservados antes do uso. Localhost explícito é permitido para o modo de sidecar local.
• ai_ready_certify deriva seu nível de quatro critérios: integridade forense, presença de assinatura, validade de LTV e ausência de criptografia. Todos os quatro aprovados resultam em certified; de um a três resultam em partial; zero resulta em not_certified. A integridade forense é uma heurística estrutural sobre a cadeia de revisões, não uma verificação criptográfica de integridade dos bytes. A verificação de criptografia inspeciona apenas a região do trailer.
• certify_ai_ready avalia três critérios e anexa um carimbo de proveniência XMP. Os bytes carimbados são retornados codificados em base64, a menos que return_stamped_pdf seja false ou o nível seja not_certified.
• compliance_check aceita exatamente doze chaves 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. Uma chave desconhecida retorna um resultado de erro nomeando o conjunto suportado.
• audit_ast_mutations lê apenas o AstAuditTrailInterface injetado. Ele próprio não registra nada.

Casos extremos e modos de falha

• Nem document_id nem source fornecidos: resultado de erro instruindo o chamador a fornecer um deles.
• document_id desconhecido: resultado de erro nomeando o ID e apontando para create_pdf.
• source de sistema de arquivos com NEXTPDF_MCP_INPUT_DIR não definido: rejeitado com uma mensagem nomeando os canais suportados.
• Caminho de source que resolve para fora do diretório de entrada configurado, inclusive via symlink: rejeitado. A comparação ocorre em um limite de separador de diretório, de modo que diretórios irmãos que compartilham um prefixo de nome não podem passar.
• URI data: sem um separador de vírgula, ou payload base64 inválido: resultado de erro.
• top_k de search_documents fora de 1–100: limitado (clamped), não rejeitado. Um top_k não inteiro recai para o padrão do pipeline configurado.
• mode de search_documents fora de hybrid, bm25, semantic: resultado de erro da allowlist do pipeline.
• Elemento de documents[] de batch_compliance_check sem id ou path, ou carregando strings vazias: resultado de erro nomeando o índice ofensor. batch_forensic_analyze valida apenas o formato do array externo; defeitos de elemento afloram na camada de lote.
• SpectrumClientFactory::create com um SPECTRUM_URL malformado, ou apontando para um endereço privado, link-local ou de metadados: InvalidArgumentException. Dentro de um execute de ferramenta, isso aflora como um resultado de erro.
• SpectrumClientFactory::createStreamFromFile sobre um caminho ilegível: McpStreamException.
• Variáveis de ambiente vazias são tratadas como não definidas e recaem para os padrões.

Conformidade

O NextPDF não possui nenhuma certificação e não concede nenhuma. As ferramentas MCP reportam avaliações em nível de capacidade; suporte não é conformidade, e conformidade não é certificação. Os valores de certification_level retornados por ai_ready_certify e certify_ai_ready são o vocabulário reportado pelas próprias ferramentas. Eles não constituem uma atestação de terceiros. As respostas de compliance_check incluem um campo disclaimer produzido pelo relatório subjacente pela mesma razão. Referências a cláusulas de política, como a base da política de LTV que a fonte do produto declara como ISO 32000-2:2020 §12.8.4.3, são carregadas nas descrições das ferramentas e nos campos clause por constatação; esta página não adiciona nenhuma afirmação independente sobre normas. Se um documento verificado satisfaz uma regulação é uma determinação para o operador e seus avaliadores.

Notas de desenvolvimento

• SpectrumClientFactory::create faz cache de um cliente por processo. Chame SpectrumClientFactory::reset no setup do teste para forçar um cliente novo.
• Leituras de ambiente consultam $_ENV, depois $_SERVER, depois getenv, e tratam strings vazias como ausentes.
• RiskLevel orienta o tratamento no lado do host no runtime do servidor: Safe executa automaticamente, Caution e acima são registrados em auditoria, e ApprovalRequired exige confirmação humana. Nenhuma ferramenta MCP Enterprise declara ApprovalRequired. Substituições do operador podem elevar um nível declarado, nunca rebaixá-lo.
• Os valores de annotations (readOnlyHint, idempotentHint) são dicas do cliente MCP, não imposição. Confinamento e validação acontecem no lado do servidor independentemente das dicas.
• As ferramentas reportam valores de category document ou extraction para a filtragem de tools/list.
• AuditAstMutationsTool é a única ferramenta que exige injeção por construtor; registre-a com uma implementação concreta de AstAuditTrailInterface.

Veja também

• MCP (página de capacidade)
• Accelerator — Referência aprofundada — a superfície do cliente do sidecar Spectrum.
• Forensics — Referência Profunda — o analisador por trás de forensic_analyze.
• Compliance — Referência Profunda — as políticas por trás de compliance_check.
• AST — Referência aprofundada — chunking e a trilha de auditoria de mutações.
• Validation — Referência aprofundada

Limite de publicação

Esta página documenta apenas o comportamento observável externamente e a superfície de API pública suportada. Caminhos de namespace internos, classes auxiliares, tabelas de mecanismos, nomes de arquivos de runbook e prefixos de ticket estão fora de escopo.