Enterprise phiên bản

MCP — Tài liệu tham chiếu chuyên sâu

Tổng quan

Namespace NextPDF\Enterprise\Mcp cung cấp tầng Enterprise của danh mục tool MCP của NextPDF. Bề mặt công khai của nó gồm mười một lớp tool, một client factory và một exception có kiểu. Mọi tool đều triển khai hợp đồng NextPDF\Server\Tools\ToolInterface từ runtime nextpdf/server và khai báo ToolTier::Enterprise. Sáu tool phân tích một PDF đơn ngay trong tiến trình. Bốn tool ủy thác khối lượng công việc batch và RAG cho Spectrum sidecar thông qua NextPDF\Enterprise\Mcp\SpectrumClientFactory. Một tool đọc nhật ký kiểm toán mutation AST được tiêm qua constructor thay vì đọc byte PDF. Mỗi tool tự mô tả tên MCP, đầu vào JSON Schema, các annotation client, RiskLevel và category của nó.

Tính khả dụng và cấp phép

Khả năng này được cung cấp trong NextPDF Enterprise (nextpdf/enterprise) và kích hoạt cùng một envelope giấy phép tầng Enterprise. Một triển khai không có quyền đó sẽ không nạp các lớp của khả năng này. So sánh các phiên bản và nhận giấy phép.

Bề mặt Public API

Symbol	Tham số	Hành vi mặc định	Trả về	Ném hoặc thất bại với	Ghi chú
`ForensicAnalyzeTool::execute`	`array $arguments, InMemoryDocumentStore $store`; args: `document_id` hoặc `source`	Chạy phân tích forensic: revisions, incremental updates, signatures	`ToolResult` (báo cáo JSON)	`ToolResult` lỗi; các exception được bắt, không bao giờ ném lại	Tool `forensic_analyze`; `RiskLevel::Safe`; chỉ đọc, idempotent; category `document`; từ 2.0.0
`BatchForensicAnalyzeTool::execute`	args: `workspace_token`, `documents[]` (mỗi phần tử `id` + `path`)	Phân tích forensic theo batch qua Spectrum sidecar	`ToolResult` với `status` từng document, số lượng thành công và thất bại	`ToolResult` lỗi (thiếu tham số, sidecar thất bại)	Tool `batch_forensic_analyze`; `RiskLevel::Safe`; category `document`; từ 2.1.0
`ComplianceCheckTool::execute`	args: `policy` (enum 12 giá trị), `document_id` hoặc `source`	Đánh giá PDF theo một chính sách tuân thủ có tên	`ToolResult` với findings, pass/fail, `duration_ms` và một trường `disclaimer`	`ToolResult` lỗi; policy không xác định trả về lỗi liệt kê các key được hỗ trợ	Tool `compliance_check`; `RiskLevel::Review`; category `document`; từ 2.0.0
`BatchComplianceCheckTool::execute`	args: `workspace_token`, `documents[]`, `policies` (`pdfa`, `pades`, `zugferd`; mặc định `["pdfa"]`)	Kiểm tra tuân thủ theo batch qua Spectrum sidecar	`ToolResult` với số lượng compliant / non-compliant	`ToolResult` lỗi; mỗi phần tử `documents[]` được kiểm tra `id` và `path` không rỗng	Tool `batch_compliance_check`; `RiskLevel::Safe`; category `document`; từ 2.1.0
`LtvHealthCheckTool::execute`	args: `document_id` hoặc `source`	Chạy chính sách sức khỏe LTV trên một PDF đã ký	`ToolResult` với findings và pass/fail	`ToolResult` lỗi	Tool `ltv_health_check`; `RiskLevel::Safe`; category `document`; từ 2.0.0
`AiReadyCertifyTool::execute`	args: `document_id` hoặc `source`	Đánh giá mức độ sẵn sàng cho AI ở chế độ chỉ đọc trên bốn tiêu chí	`ToolResult` với `certification_level` (`certified`, `partial`, `not_certified`) và các boolean theo từng tiêu chí	`ToolResult` lỗi	Tool `ai_ready_certify`; `RiskLevel::Review`; chỉ đọc; category `document`; từ 2.0.0
`CertifyAiReadyTool::execute`	args: `document_id` hoặc `source`, `return_stamped_pdf` (mặc định `true`)	Đánh giá ba tiêu chí và gắn một dấu provenance XMP	`ToolResult`; bao gồm `stamped_pdf_base64` trừ khi bị tắt hoặc `not_certified`	`ToolResult` lỗi	Tool `certify_ai_ready`; `RiskLevel::Review`; không chỉ đọc; category `document`; từ 3.0.0
`AstAwareChunkTool::execute`	args: `document_id` hoặc `source`, `max_chunk_chars` (mặc định 1500), `overlap_chars` (mặc định 150)	Dựng AST và phát ra các chunk neo trích dẫn kèm provenance	`ToolResult` với `chunk_count` và node ID, page index, bbox, node type theo từng chunk	`ToolResult` lỗi	Tool `ast_aware_chunk`; `RiskLevel::Review`; category `extraction`; từ 3.0.0
`AuditAstMutationsTool::__construct`	`AstAuditTrailInterface $auditTrail`	Tiêm backend nhật ký kiểm toán	instance	—	Phụ thuộc tiêm qua constructor; từ 3.0.0
`AuditAstMutationsTool::execute`	args: `document_source_hash` (SHA-256 hex, bắt buộc)	Trả về tất cả sự kiện mutation AST được ghi cho document đó	`ToolResult` với `entries[]` và `count`	`ToolResult` lỗi khi tham số bị thiếu hoặc rỗng	Tool `audit_ast_mutations`; `RiskLevel::Review`; category `document`; từ 3.0.0
`EmbedDocumentsTool::execute`	args: `collection_id`, `workspace_token`, `documents[]` (tất cả bắt buộc)	Nạp PDF vào một collection RAG qua Spectrum sidecar	`ToolResult` với số lượng succeeded / total / failed	`ToolResult` lỗi	Tool `embed_documents`; `RiskLevel::Caution`; không chỉ đọc, không idempotent; category `extraction`; từ 2.1.0
`SearchDocumentsTool::execute`	args: `collection_id`, `query` (bắt buộc), `top_k` (mặc định 10, kẹp 1–100), `mode` (`hybrid`, `bm25`, `semantic`)	Truy xuất hybrid trên một collection đã nạp	`ToolResult` với các chunk được xếp hạng và điểm liên quan	`ToolResult` lỗi; `mode` ngoài allowlist bị từ chối	Tool `search_documents`; `RiskLevel::Safe`; category `extraction`; từ 2.1.0
`SpectrumClientFactory::create`	không có (đọc `SPECTRUM_URL`, `SPECTRUM_TIMEOUT`, `SPECTRUM_AUTH_TOKEN`, `SPECTRUM_APP_SECRET`)	Dựng và cache một sidecar client cho toàn tiến trình	`SpectrumClient`	`InvalidArgumentException` khi `SPECTRUM_URL` sai định dạng hoặc trỏ tới một địa chỉ bị chặn	Endpoint mặc định `http://127.0.0.1:7800`; timeout 30.0 s; từ 2.1.0
`SpectrumClientFactory::reset`	không có	Xóa instance client đã cache	`void`	—	Dành cho test
`SpectrumClientFactory::createRequest`	`string $method, $uri` (`string` hoặc `UriInterface`)	Dựng một request PSR-7 từ các lớp Core HTTP	`RequestInterface`	—	Triển khai PSR-17 `RequestFactoryInterface`
`SpectrumClientFactory::createStream`	`string $content = ''`	Dựng một stream PSR-7 trong bộ nhớ	`StreamInterface`	—	Triển khai PSR-17 `StreamFactoryInterface`
`SpectrumClientFactory::createStreamFromFile`	`string $filename, string $mode = 'r'`	Mở file và bọc nó thành một stream	`StreamInterface`	`McpStreamException` khi không mở được file	`McpStreamException` mở rộng `RuntimeException`
`SpectrumClientFactory::createStreamFromResource`	`$resource` (PHP resource)	Bọc một resource có sẵn thành một stream	`StreamInterface`	—	Triển khai PSR-17 `StreamFactoryInterface`
`McpStreamException`	—	Thất bại có kiểu khi lấy stream	—	—	`final class`, mở rộng `RuntimeException`; source ghi nhận tương thích PSR-17 §1.5; source chú thích nó `@since 3.2.0` (có mặt trong dòng dev alias 3.1.0 hiện tại)

Mọi tool cũng phơi bày các phương thức tự mô tả của ToolInterface: name, description, inputSchema, annotations, riskLevel, tier và category. Các giá trị theo từng tool xuất hiện ở cột Ghi chú phía trên.

Chữ ký điểm vào, nguyên văn từ source:

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

Hợp đồng hành vi

Mọi tool triển khai NextPDF\Server\Tools\ToolInterface và khai báo ToolTier::Enterprise một cách tường minh. Tier không bao giờ được suy ra từ namespace hay cách đóng gói.
execute không ném. Mọi thất bại đều được bắt và trả về dưới dạng một ToolResult lỗi mang theo thông điệp thất bại.
Các tool đơn document phân giải byte PDF theo một thứ tự ưu tiên cố định. Một document_id được tra trong InMemoryDocumentStore trước. Nếu không, source được diễn giải như một URI data:, rồi như base64 thô (trên 256 ký tự), rồi như một đường dẫn file.
Các đường dẫn source trên hệ thống tệp bị tắt theo mặc định. Chúng chỉ kích hoạt khi biến môi trường NEXTPDF_MCP_INPUT_DIR chỉ định một thư mục đầu vào bị giới hạn. Đường dẫn thực đã phân giải phải nằm bên trong thư mục đó. Mọi thứ khác đều thất bại đóng.
Các scheme stream-wrapper (phar://, php://, file:// và mọi scheme khác) cùng null byte trong một source dạng đường dẫn file đều bị từ chối trước bất kỳ lời gọi hệ thống tệp nào. Traversal và symlink escape thất bại trước kiểm tra giới hạn theo đường dẫn thực.
Các tool dựa trên sidecar (embed_documents, search_documents, batch_compliance_check, batch_forensic_analyze) lấy client của chúng từ SpectrumClientFactory::create. Factory kiểm chứng một SPECTRUM_URL không phải localhost đối với các dải địa chỉ riêng tư và dành riêng trước khi sử dụng. Localhost tường minh được cho phép cho chế độ sidecar cục bộ.
ai_ready_certify suy ra cấp độ của nó từ bốn tiêu chí: tính toàn vẹn forensic, sự hiện diện của signature, tính hợp lệ LTV và việc không có mã hóa. Cả bốn đều đạt cho ra certified; một tới ba cho ra partial; không có cái nào cho ra not_certified. Tính toàn vẹn forensic là một heuristic cấu trúc trên chuỗi revision, không phải xác minh toàn vẹn byte bằng mật mã. Kiểm tra mã hóa chỉ xem xét vùng trailer.
certify_ai_ready đánh giá ba tiêu chí và gắn một dấu provenance XMP. Byte đã đóng dấu được trả về mã hóa base64 trừ khi return_stamped_pdf là false hoặc cấp độ là not_certified.
compliance_check chấp nhận đúng mười hai key policy: pdfa4, pdfa4e, pdfa4f, pades-baseline, ltv-health, eidas-qualified, zugferd, fda-part11, sec-17a4, sec-17a4-compatible, sec-17a4-structural, sec-17a4-pre-sign. Một key không xác định trả về một kết quả lỗi nêu tên tập hợp được hỗ trợ.
audit_ast_mutations chỉ đọc AstAuditTrailInterface được tiêm. Bản thân nó không ghi gì.

Trường hợp biên và chế độ lỗi

Không cung cấp cả document_id lẫn source: kết quả lỗi chỉ dẫn caller cung cấp một trong hai.
document_id không xác định: kết quả lỗi nêu tên ID và trỏ tới create_pdf.
source hệ thống tệp khi NEXTPDF_MCP_INPUT_DIR chưa đặt: bị từ chối với thông điệp nêu tên các kênh được hỗ trợ.
Đường dẫn source phân giải ra ngoài thư mục đầu vào đã cấu hình, kể cả qua symlink: bị từ chối. So sánh diễn ra trên biên ranh giới dấu phân tách thư mục, nên các thư mục anh em có chung tiền tố tên không thể qua được.
URI data: không có dấu phẩy phân tách, hoặc payload base64 không hợp lệ: kết quả lỗi.
search_documents top_k ngoài 1–100: bị kẹp, không bị từ chối. Một top_k không phải số nguyên rơi về mặc định của pipeline đã cấu hình.
search_documents mode ngoài hybrid, bm25, semantic: kết quả lỗi từ allowlist của pipeline.
Phần tử documents[] của batch_compliance_check thiếu id hoặc path, hoặc mang chuỗi rỗng: kết quả lỗi nêu tên index vi phạm. batch_forensic_analyze chỉ kiểm chứng hình dạng mảng ngoài; khiếm khuyết phần tử nổi lên từ tầng batch.
SpectrumClientFactory::create với một SPECTRUM_URL sai định dạng, hoặc trỏ tới một địa chỉ riêng tư, link-local hay metadata: InvalidArgumentException. Bên trong một execute của tool, điều này nổi lên dưới dạng một kết quả lỗi.
SpectrumClientFactory::createStreamFromFile trên một đường dẫn không đọc được: McpStreamException.
Biến môi trường rỗng được coi như chưa đặt và rơi về mặc định.

Phù hợp tiêu chuẩn

NextPDF không nắm giữ chứng nhận nào và không cấp chứng nhận nào. Các tool MCP báo cáo đánh giá ở cấp khả năng; hỗ trợ không phải là phù hợp tiêu chuẩn, và phù hợp tiêu chuẩn không phải là chứng nhận. Các giá trị certification_level do ai_ready_certify và certify_ai_ready trả về là từ vựng do chính các tool báo cáo. Chúng không cấu thành một chứng thực của bên thứ ba. Phản hồi của compliance_check bao gồm một trường disclaimer do báo cáo bên dưới tạo ra vì cùng lý do đó. Các tham chiếu điều khoản chính sách, chẳng hạn cơ sở chính sách LTV mà source sản phẩm nêu là ISO 32000-2:2020 §12.8.4.3, được mang trong mô tả tool và các trường clause theo từng finding; trang này không thêm tuyên bố tiêu chuẩn độc lập nào. Việc một document đã kiểm tra có thỏa mãn một quy định hay không là điều để nhà vận hành và các bên đánh giá của họ xác định.

Ghi chú phát triển

SpectrumClientFactory::create cache một client cho mỗi tiến trình. Gọi SpectrumClientFactory::reset trong setup test để buộc tạo một client mới.
Việc đọc môi trường tham vấn $_ENV, rồi $_SERVER, rồi getenv, và coi chuỗi rỗng như vắng mặt.
RiskLevel điều khiển cách xử lý phía host trong runtime server: Safe tự động thực thi, Caution trở lên được ghi audit-log, và ApprovalRequired đòi hỏi xác nhận của con người. Không tool MCP Enterprise nào khai báo ApprovalRequired. Override của nhà vận hành có thể nâng một cấp độ đã khai báo, không bao giờ hạ nó xuống.
Các giá trị annotations (readOnlyHint, idempotentHint) là gợi ý cho client MCP, không phải sự thực thi cưỡng chế. Giới hạn và kiểm chứng diễn ra ở phía server bất kể các hint.
Các tool báo cáo giá trị category là document hoặc extraction để lọc tools/list.
AuditAstMutationsTool là tool duy nhất đòi hỏi tiêm qua constructor; hãy đăng ký nó với một triển khai AstAuditTrailInterface cụ thể.

Xem thêm

MCP (trang khả năng)
Accelerator — tài liệu tham chiếu chuyên sâu — bề mặt client của Spectrum sidecar.
Forensics — Tài liệu tham chiếu chuyên sâu — analyzer đứng sau forensic_analyze.
Compliance — Tài liệu tham chiếu chuyên sâu — các chính sách đứng sau compliance_check.
AST — tài liệu tham chiếu chuyên sâu — chunking và nhật ký kiểm toán mutation.
Validation — tài liệu tham chiếu chuyên sâu

Ranh giới xuất bản

Trang này chỉ ghi lại hành vi quan sát được từ bên ngoài và bề mặt public API được hỗ trợ. Các đường dẫn namespace nội bộ, lớp trợ giúp, bảng cơ chế, tên tệp runbook và tiền tố ticket đều nằm ngoài phạm vi.