Enterprise phiên bản

Công cụ MCP

Tổng quan nhanh

NextPDF Enterprise bổ sung mười một công cụ MCP vào máy chủ NextPDF Connect. Chúng cho trợ lý AI và các framework agent quyền truy cập trực tiếp, có kiểu, vào engine Enterprise: kiểm tra chính sách tuân thủ, forensic PDF, kiểm tra tình trạng LTV, đóng dấu sẵn sàng cho AI, phân đoạn theo AST, cùng nạp và tìm kiếm RAG. Mỗi công cụ khai báo mức rủi ro và tư thế read-only riêng, nên MCP host của bạn có thể kiểm soát, ghi log và kiểm toán hoạt động của agent một cách tin cậy. Lỗi không bao giờ hiện ra dưới dạng exception; agent luôn nhận được kết quả có cấu trúc, phân tích được.

Khả dụng & cấp phép

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

Cài đặt

composer require nextpdf/enterprise:^3

Bản thân MCP host là NextPDF Connect, cung cấp trong package nextpdf/server; xem Cài đặt Connect. Khi cả hai package đều hiện diện, tool registry của máy chủ tự động phát hiện NextPDF\Enterprise\McpToolProvider và đăng ký mười một công cụ Enterprise. Không cần mã kết nối nào. Nếu thiếu nextpdf/server, tệp provider trả về sớm và không nạp gì cả.

Các công cụ batch và RAG còn cần thêm Spectrum sidecar. Cấu hình nó qua các biến môi trường được đọc bởi NextPDF\Enterprise\Mcp\SpectrumClientFactory: SPECTRUM_URL (mặc định http://127.0.0.1:7800), SPECTRUM_TIMEOUT (mặc định 30.0 giây), SPECTRUM_AUTH_TOKEN, và SPECTRUM_APP_SECRET.

Tổng quan khái niệm

Model Context Protocol (MCP) là một giao thức mở cho phép trợ lý AI và các framework agent gọi các công cụ có kiểu do một máy chủ phơi bày. Thay vì dán các byte PDF vào prompt rồi hy vọng, một agent gọi công cụ được đặt tên với payload đã được validate theo JSON-schema và nhận về kết quả có cấu trúc, xác định. NextPDF Connect là máy chủ đó cho PDF; package Enterprise mở rộng danh mục của nó với các công cụ bên dưới. Mỗi công cụ là một lớp bọc mỏng trên chính các API Enterprise mà mã PHP của bạn gọi trực tiếp, nên một kiểm tra do agent chạy và một kiểm tra do mã chạy cho ra cùng một phán quyết.

Danh mục công cụ

Công cụ MCP	Lớp	Chức năng	Rủi ro	Read-only
`compliance_check`	`ComplianceCheckTool`	Validate một PDF theo một chính sách được đặt tên: `pdfa4`, `pdfa4e`, `pdfa4f`, `pades-baseline`, `ltv-health`, `eidas-qualified`, `zugferd`, `fda-part11`, và bốn biến thể `sec-17a4`.	Review	có
`batch_compliance_check`	`BatchComplianceCheckTool`	Kiểm tra nhiều PDF theo chính sách `pdfa`, `pades`, hoặc `zugferd` trong một batch Spectrum sidecar.	Safe	có
`forensic_analyze`	`ForensicAnalyzeTool`	Báo cáo lịch sử revision, các cập nhật gia tăng, và sự kiện sửa đổi để phát hiện giả mạo.	Safe	có
`batch_forensic_analyze`	`BatchForensicAnalyzeTool`	Chạy phân tích forensic trên nhiều PDF trong một batch sidecar.	Safe	có
`ltv_health_check`	`LtvHealthCheckTool`	Kiểm tra một PDF đã ký để tìm vật liệu validation dài hạn: từ điển DSS, phản hồi OCSP, mục CRL, mục VRI, và kho chứng chỉ.	Safe	có
`ai_ready_certify`	`AiReadyCertifyTool`	Phán quyết sẵn sàng cho AI do sản phẩm định nghĩa, read-only, trên bốn tiêu chí: tính toàn vẹn forensic, có chữ ký, LTV hợp lệ, không mã hóa.	Review	có
`certify_ai_ready`	`CertifyAiReadyTool`	Phán quyết sẵn sàng do sản phẩm định nghĩa trên ba tiêu chí (bốn tiêu chí của công cụ read-only trừ tính toàn vẹn forensic - theo thiết kế, vì công cụ này ghi lại tệp mà nó đóng dấu) và gắn thêm một dấu provenance XMP; trả về PDF đã đóng dấu dưới dạng base64.	Review	không
`ast_aware_chunk`	`AstAwareChunkTool`	Chia một PDF thành các chunk neo trích dẫn dọc theo ranh giới tiêu đề, mỗi chunk có node ID, chỉ số trang, và bounding box.	Review	có
`audit_ast_mutations`	`AuditAstMutationsTool`	Lấy dấu vết kiểm toán biến đổi AST cho một tài liệu theo source hash SHA-256.	Review	có
`embed_documents`	`EmbedDocumentsTool`	Nạp các PDF vào một RAG collection: parse, chunk, embed, index. Thay đổi trạng thái collection.	Caution	không
`search_documents`	`SearchDocumentsTool`	Truy xuất lai (từ khóa BM25 cộng ngữ nghĩa) trên một collection đã nạp, với các chunk được xếp hạng và tính điểm.	Safe	có

Các công cụ “certify” đưa ra một phán quyết sẵn sàng do sản phẩm định nghĩa (certified, partial, hoặc not_certified). Phán quyết đó là kết quả kiểm tra kỹ thuật, không phải chứng nhận bởi bất kỳ tổ chức kiểm định nào.

Kiểm soát phê duyệt và tư thế kiểm toán

Mỗi công cụ khai báo một mức rủi ro từ mô hình Connect bốn tầng. Công cụ Safe tự động thực thi. Công cụ Caution tự động thực thi kèm một mục audit-log. Công cụ Review mang một cảnh báo cho hướng dẫn của agent gọi. Công cụ ApprovalRequired đòi hỏi xác nhận của con người; hiện không công cụ MCP Enterprise nào khai báo mức này, vì không công cụ nào có tính phá hủy. Cấu hình runtime chỉ có thể nâng mức rủi ro của một công cụ, không bao giờ hạ. Các công cụ cũng công bố các chú thích hành vi MCP (readOnlyHint, idempotentHint), nên một client tuân thủ có thể áp dụng kiểm soát riêng bên trên. Xem Các tầng rủi ro HITL để có mô hình đầy đủ.

Vì sao nó hoạt động như vậy

Quyết định chịu tải là các công cụ là lớp bọc mỏng, xác định, với quản trị tự khai báo: mỗi công cụ nêu mức rủi ro và tầng của riêng nó như một bất biến miền, không bao giờ suy ra từ namespace hay đóng gói. Điều này giữ cho quyết định kiểm soát kiểm toán được tại host mà không cần tin tưởng lớp truyền tải. Các công cụ không chứa trí tuệ tài liệu của riêng chúng; chúng ủy thác cho chính các API Enterprise mà mã của bạn gọi, nên chỉ có đúng một hành vi để kiểm thử và một phán quyết để tin cậy. Lỗi trả về trên kênh lỗi MCP thay vì thoát ra dưới dạng exception, vì một agent không thể bắt một exception PHP nhưng luôn có thể rẽ nhánh theo isError. Đầu vào có thể chạm tới hệ thống tệp mặc định fail-closed, vì theo định nghĩa các đối số MCP có thể bị kẻ tấn công tiếp cận.

Bối cảnh thiết kế: Một API từ chối đoán mò.

Bề mặt API

Cả mười một công cụ đều triển khai hợp đồng NextPDF\Server\Tools\ToolInterface từ nextpdf/server và dùng chung một bề mặt công khai. Các chữ ký bên dưới được hiển thị một lần trên NextPDF\Enterprise\Mcp\ComplianceCheckTool làm đại diện:

public function name(): string
public function description(): string
public function inputSchema(): array
public function annotations(): array
public function riskLevel(): RiskLevel
public function tier(): ToolTier
public function category(): string
public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

Ném hoặc thất bại với: execute() không bao giờ ném. Nó bắt Throwable nội bộ và trả về ToolResult::error() với isError = true. Đối số không hợp lệ (thiếu workspace_token, các mục documents sai định dạng, document_id không rõ, source không an toàn) hiện ra dưới dạng thông điệp InvalidArgumentException trên kênh lỗi đó.

Công cụ dấu vết kiểm toán nhận backend lưu trữ của nó qua constructor injection:

public function __construct(private readonly AstAuditTrailInterface $auditTrail)

Provider đăng ký danh mục:

public function getTier(): string
public function getTools(): array

getTier() trả về 'enterprise'. getTools() trả về mười một instance công cụ; audit_ast_mutations được nối với NextPDF\Enterprise\Ast\InMemoryAstAuditTrail mặc định.

Factory client Spectrum sidecar, đồng thời cũng là một PSR-17 request và stream factory:

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

Ném hoặc thất bại với: create() ném InvalidArgumentException khi SPECTRUM_URL sai định dạng hoặc khi endpoint được cấu hình nhắm tới một địa chỉ private hoặc reserved đã biết (trừ localhost). Đây là một cổng ở thời điểm cấu hình, không phải kiểm soát ở lớp mạng: vẫn phải thực thi chính sách egress, xử lý redirect, và DNS pinning trong môi trường host. createStreamFromFile() ném NextPDF\Enterprise\Mcp\McpStreamException (một lớp con của RuntimeException, theo hợp đồng PSR-17) khi không mở được tệp.

Mẫu mã — Bắt đầu nhanh

Chạy một kiểm tra tuân thủ PDF/A-4 đúng như cách một agent sẽ làm, dùng kênh URI data: trong bộ nhớ:

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Enterprise\Mcp\ComplianceCheckTool;
use NextPDF\Enterprise\Mcp\McpStreamException;
use NextPDF\Enterprise\Mcp\SpectrumClientFactory;
use NextPDF\Server\Document\InMemoryDocumentStore;

$streams = new SpectrumClientFactory(); // PSR-17 stream factory from this module

try {
    $pdfBytes = (string) $streams->createStreamFromFile(__DIR__ . '/invoice.pdf');
} catch (McpStreamException $e) {
    fwrite(STDERR, 'Cannot read PDF: ' . $e->getMessage() . PHP_EOL);
    exit(1);
}

$tool   = new ComplianceCheckTool();
$result = $tool->execute(
    [
        'source' => 'data:application/pdf;base64,' . base64_encode($pdfBytes),
        'policy' => 'pdfa4',
    ],
    new InMemoryDocumentStore(),
);

// Tool failures arrive on the MCP error channel, never as exceptions.
if ($result->isError) {
    fwrite(STDERR, $result->content[0]['text'] . PHP_EOL);
    exit(1);
}

echo $result->content[0]['text'] . PHP_EOL;

Đầu ra mong đợi cho một tệp tuân thủ (số lượng finding thay đổi theo từng tài liệu):

Compliance check (PDF/A-4): PASS — 0 finding(s)

Báo cáo đầy đủ, đọc được bằng máy, bao gồm mức độ nghiêm trọng của từng finding, rule ID, clause, và gợi ý, có sẵn trên $result->structured.

Mẫu mã — Production

Preflight sidecar, thực thi tư thế rủi ro đã khai báo, rồi chạy một kiểm tra tuân thủ batch:

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Enterprise\Mcp\BatchComplianceCheckTool;
use NextPDF\Enterprise\Mcp\SpectrumClientFactory;
use NextPDF\Server\Document\InMemoryDocumentStore;

// 1. Fail fast on sidecar misconfiguration before accepting agent traffic.
//    The factory validates SPECTRUM_URL and rejects private/reserved targets.
try {
    SpectrumClientFactory::create();
} catch (InvalidArgumentException $e) {
    fwrite(STDERR, 'Spectrum sidecar rejected: ' . $e->getMessage() . PHP_EOL);
    exit(1);
}

$tool = new BatchComplianceCheckTool();
$risk = $tool->riskLevel();

// 2. Enforce the declared risk posture before execution.
if ($risk->requiresHumanConfirmation()) {
    // Route to your approval queue instead of executing.
    exit(0);
}

if ($risk->requiresAuditLog()) {
    error_log(sprintf('[mcp-audit] tool=%s risk=%s', $tool->name(), $risk->label()));
}

// 3. Execute the batch.
$result = $tool->execute(
    [
        'workspace_token' => (string) getenv('SPECTRUM_WORKSPACE_TOKEN'),
        'documents'       => [
            ['id' => 'contract-001', 'path' => '/var/pdf-inbox/contract-001.pdf'],
            ['id' => 'contract-002', 'path' => '/var/pdf-inbox/contract-002.pdf'],
        ],
        'policies'        => ['pdfa', 'pades'],
    ],
    new InMemoryDocumentStore(),
);

echo $result->content[0]['text'] . PHP_EOL;

Đầu ra mong đợi (số lượng phản ánh tài liệu của bạn):

Batch compliance check complete: 1 compliant, 1 non-compliant

Trường hợp biên & điểm cần lưu ý

Đường dẫn source dạng hệ thống tệp bị tắt mặc định. Không có biến môi trường NEXTPDF_MCP_INPUT_DIR, một source dạng đường dẫn bị từ chối với một kết quả lỗi. Hãy dùng document_id, một URI data:, hoặc base64 thô để thay thế.
Base64 thô chỉ được nhận diện khi trên 256 ký tự. Một blob base64 ngắn hơn bị coi là một đường dẫn tệp và bị từ chối. Hãy bọc payload nhỏ trong một URI data:application/pdf;base64,.
Giá trị document_id không rõ thất bại kèm hướng dẫn. Văn bản lỗi là Unknown document_id: ... Call create_pdf first. Tài liệu trong store bộ nhớ cũng hết hạn theo TTL của store, nên một ID cũ thất bại theo cùng cách.
compliance_check từ chối các khóa chính sách không rõ và liệt kê tập được hỗ trợ trong thông điệp lỗi.
Các công cụ batch và RAG cần sidecar. batch_compliance_check, batch_forensic_analyze, embed_documents, và search_documents cần một endpoint Spectrum truy cập được và một workspace_token. Factory cache một client cho mỗi tiến trình; hãy gọi SpectrumClientFactory::reset() trong test.
search_documents kẹp top_k vào 1–100; các giá trị không phải số nguyên rơi về mặc định của máy chủ là 10.
Mặc định của ast_aware_chunk là 1500 ký tự mỗi chunk với 150 ký tự chồng lấn.
certify_ai_ready bỏ các byte đã đóng dấu khi return_stamped_pdf là false hoặc phán quyết là not_certified. Khi có mặt, payload base64 lớn hơn chính PDF khoảng một phần ba.
Dấu vết kiểm toán AST mặc định nằm trong bộ nhớ. Các mục được ghi qua wiring provider mặc định không tồn tại qua các tiến trình; hãy inject một triển khai AstAuditTrailInterface bền vững để có dấu vết kiểm toán lâu dài.

Ghi chú bảo mật

Phân giải source fail-closed. Người gọi MCP kiểm soát hoàn toàn các đối số công cụ, nên bộ phân giải coi chúng là thù địch. Các stream wrapper (phar://, php://, file://, và bất kỳ scheme nào) và null byte bị từ chối trước bất kỳ lời gọi hệ thống tệp nào. Path traversal bị từ chối. Đường dẫn tệp thô chỉ hoạt động khi NEXTPDF_MCP_INPUT_DIR được đặt, và mục tiêu đã được realpath chuẩn hóa phải phân giải nghiêm ngặt bên trong thư mục đó, so sánh trên ranh giới dấu phân cách để chặn các thoát ly nhầm lẫn tiền tố.
Bảo vệ SSRF trên endpoint sidecar. SpectrumClientFactory cho phép localhost cho chế độ local-sidecar và validate mọi SPECTRUM_URL khác đối chiếu với các dải private, reserved, link-local, và cloud-metadata, ném InvalidArgumentException trên một địa chỉ bị chặn. Đây là một cổng ở thời điểm cấu hình trên endpoint được cấu hình, không phải kiểm soát ở lớp mạng - hãy giữ chính sách egress, xử lý redirect, và DNS pinning trong môi trường host.
Bí mật ở lại trong môi trường. Token bearer của sidecar (SPECTRUM_AUTH_TOKEN) và bí mật ký HMAC (SPECTRUM_APP_SECRET) được đọc từ biến môi trường và không bao giờ xuất hiện trong payload hay kết quả của công cụ.
Lỗi không phản chiếu. Thông điệp từ chối đường dẫn là generic theo thiết kế (Source path is not permitted.), nên một người gọi dò xét không học được gì về hệ thống tệp host.
Ghi đè rủi ro chỉ đi lên. Cấu hình của người vận hành có thể nâng mức rủi ro đã khai báo của một công cụ nhưng không bao giờ hạ nó xuống dưới khai báo của chính công cụ.

Tuân thủ

Hỗ trợ không phải tuân thủ, và tuân thủ không phải chứng nhậ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 công cụ tuân thủ kiểm tra cấu trúc tài liệu đối chiếu với các profile chính sách được đặt tên và báo cáo các finding kèm tham chiếu clause; báo cáo compliance_check còn mang thêm tuyên bố miễn trừ của chính engine rằng đó là một kiểm tra cấu trúc kỹ thuật để tham khảo, không phải tư vấn pháp lý hay chứng thực tuân thủ. Các phán quyết ai_ready_certify và certify_ai_ready là các mức sẵn sàng do sản phẩm định nghĩa, không phải một chứng thực bởi bất kỳ tổ chức tiêu chuẩn nào. MCP là một giao thức mở do đơn vị quản lý của nó công bố, không phải một tiêu chuẩn SDO; trang này ghi lại hành vi triển khai của NextPDF và không đưa ra tuyên bố độc lập nào về tuân thủ giao thức hay chứng nhận.

Hợp đồng hành vi

Lỗi công cụ được trả về dưới dạng kết quả lỗi (isError = true kèm một thông điệp); exception không bao giờ vượt qua ranh giới MCP.
Kết quả thành công mang một tóm tắt một dòng đọc được bởi con người cùng một payload JSON có cấu trúc với tập trường ổn định, được ghi tài liệu cho mỗi công cụ.
Mỗi công cụ báo cáo tier() = ToolTier::Enterprise và một RiskLevel đã khai báo; rủi ro không thể hạ ở runtime.
Các công cụ read-only khai báo readOnlyHint: true và không sửa document store, PDF nguồn, hay bất kỳ collection nào.
certify_ai_ready không bao giờ thay đổi tài liệu đầu vào tại chỗ; dấu được áp lên một bản sao trả về.
Báo cáo tuân thủ và LTV bao gồm một dấu thời gian validation và số lượng finding theo mức độ nghiêm trọng; payload compliance_check còn bao gồm chuỗi tuyên bố miễn trừ pháp lý của engine.

Phương án dự phòng Core

Bản thân MCP host không đòi hỏi Enterprise. NextPDF Connect (nextpdf/server, Apache-2.0) chạy với engine Core mở và phục vụ danh mục công cụ hạng core của nó: tạo tài liệu, các thao tác văn bản và nội dung, và trích xuất. Xem danh mục công cụ. Riêng Core không cung cấp kiểm tra chính sách tuân thủ, phân tích forensic, kiểm tra tình trạng LTV, đóng dấu sẵn sàng cho AI, phân đoạn theo AST, dấu vết kiểm toán biến đổi, hay các công cụ batch và RAG; mười một công cụ đó chỉ đăng ký khi nextpdf/enterprise được cài đặt và cấp phép.

Ranh giới công bố

Trang này ghi lại chỉ 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 helper, bảng cơ chế, tên tệp runbook, và tiền tố ticket nằm ngoài phạm vi.