Pro phiên bản

Công cụ MCP

Tổng quan nhanh

NextPDF Pro bổ sung tám công cụ Model Context Protocol (MCP) cho phép một AI agent chạy các thao tác PDF nâng cao thông qua NextPDF Server. Các công cụ tự động xuất hiện khi cả nextpdf/pro và nextpdf/server đều được cài đặt — không cần bước đăng ký riêng.

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

Năng lực này đi kèm trong NextPDF Pro (nextpdf/pro) và kích hoạt bằng một gói giấy phép bậc Pro. Một triển khai không có quyền hạ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.

Bề mặt MCP cơ sở — tạo tài liệu, văn bản, bảng, chẩn đoán — đi kèm với NextPDF Server mã nguồn mở và không cần giấy phép. Tám công cụ trên trang này cần một giấy phép Pro và chỉ đăng ký khi gói nextpdf/pro được phân giải lúc khởi động. Bậc công cụ pro kiểm soát toàn bộ bộ công cụ: mỗi công cụ khai báo bậc của nó một cách tường minh, và không có cờ theo từng công cụ — cài đặt nextpdf/pro cùng với nextpdf/server sẽ bật cả bộ.

Hợp đồng hành vi

Tám công cụ MCP Pro tự đăng ký khi cả nextpdf/pro và nextpdf/server đều được phân giải lúc khởi động, dưới bậc pro, thông qua luồng MCP tools/list và tools/call tiêu chuẩn. Không có cờ theo từng công cụ và không có thay đổi mã trong ứng dụng tiêu thụ.
Mỗi công cụ nhận một PDF qua một document_id từ một lời gọi create_pdf trước đó, một source nội tuyến (đường dẫn tệp, base64, hoặc URI data:), hoặc — với compare_pdfs — hai nguồn như vậy. Các công cụ trả về JSON có cấu trúc.
Mỗi công cụ khai báo một lớp rủi ro HITL mà máy chủ thực thi: an toàn (tự động thực thi, chỉ đọc), rà soát (kết quả có thể bị lạm dụng), và yêu cầu phê duyệt. sign_pdf thuộc loại yêu cầu phê duyệt và bị giữ lại cho đến khi một con người xác nhận. Một người vận hành chỉ có thể siết chặt lớp rủi ro của một công cụ, không bao giờ nới lỏng.
sign_pdf chỉ tạo ra một chữ ký PAdES B-B (baseline) — không có dấu thời gian tin cậy và không có tài liệu xác thực dài hạn. Các hồ sơ dài hạn (B-LT / B-LTA), giám hộ khóa bằng phần cứng, và ký theo dấu vết kiểm toán thuộc bậc Enterprise và không được các công cụ này cung cấp; B-T (một chữ ký có dấu thời gian) có sẵn từ engine Core khi một nhà cung cấp dấu thời gian được cấu hình.
redact_pii thực hiện phát hiện theo khuôn mẫu và che ở lớp văn bản, không phải xóa che trực quan; check_accessibility là một suy nghiệm cấu trúc, không phải một phán quyết phù hợp PDF/UA hay WCAG. Lược đồ đầu vào/đầu ra có thẩm quyền là phản hồi tools/list trực tiếp của máy chủ, không phải trang này.

Tổng quan khái niệm

NextPDF Server là lớp thực thi MCP có tính tất định cho NextPDF. Nó khám phá các nhà cung cấp công cụ lúc khởi động bằng một phép dò sự tồn tại của lớp, nên gói Pro không cần được liệt kê trong các phần phụ thuộc của máy chủ. Khi gói Pro hiện diện, máy chủ đăng ký tám công cụ của nó dưới bậc pro và phơi bày chúng thông qua luồng MCP tools/list và tools/call tiêu chuẩn trên bất kỳ transport nào bạn đã cấu hình.

Mỗi công cụ Pro nhận một PDF từ một trong ba nguồn: một document_id được trả về bởi một lời gọi create_pdf trước đó, một source nội tuyến (đường dẫn tệp, chuỗi base64, hoặc URI data:), hoặc — với công cụ so sánh — hai nguồn như vậy. Các công cụ trả về kết quả JSON có cấu trúc: văn bản đã trích xuất, các vùng diff, văn bản đã che, cây phân đoạn, các phát hiện về khả năng tiếp cận, hoặc một PDF đã ký.

Mỗi công cụ Pro mang theo một phân loại rủi ro mà máy chủ dùng để thực thi human-in-the-loop (HITL). Các công cụ phân tích chỉ đọc được xếp hạng an toàn và tự động thực thi. Các công cụ tạo ra kết quả mà một bên gọi có thể lạm dụng được xếp hạng cần rà soát. Công cụ ký được xếp hạng yêu cầu phê duyệt, nên máy chủ giữ nó lại cho đến khi một con người xác nhận. Chính công cụ khai báo phân loại này; một người vận hành chỉ có thể siết chặt nó lúc chạy — không bao giờ nới lỏng.

Bề mặt công cụ MCP được tách biệt một cách có chủ đích với engine PDF Pro. Các công cụ là những adapter mỏng: chúng xác thực đầu vào, phân giải PDF, ủy thác cho một thành phần engine Pro, và tuần tự hóa kết quả. Chúng không phải là một API thứ hai cho engine và không thuộc API PHP công khai của Pro — điểm tích hợp được hỗ trợ là giao thức MCP do NextPDF Server phơi bày.

Danh mục công cụ (tám công cụ Pro)

Tám công cụ MCP Pro, theo tên giao thức MCP. Các mức rủi ro theo mô hình HITL của máy chủ: an toàn (tự động thực thi, chỉ đọc), rà soát (tạo ra kết quả có thể bị lạm dụng; được cảnh báo trong hướng dẫn agent), và yêu cầu phê duyệt (phải được một con người xác nhận).

`extract_text`

Mục đích: Trích xuất văn bản. Trích xuất lớp văn bản của một PDF, tùy chọn giới hạn theo một phạm vi trang đánh số từ 1.
Đầu vào: Một PDF (document_id hoặc source); tùy chọn page_start và page_end.
Đầu ra: Văn bản đã trích xuất và tổng số trang.
Rủi ro: An toàn. Chỉ đọc và lũy đẳng.
Ranh giới: Trích xuất lớp văn bản hiện có. Nó không thực hiện OCR trên các trang quét hoặc chỉ có ảnh.

`segment_document`

Mục đích: Phân đoạn cấu trúc. Tách một PDF thành các phần logic — tiêu đề, đầu mục, thân, bảng, hình.
Đầu vào: Một PDF (document_id hoặc source).
Đầu ra: Một số lượng phân đoạn và một danh sách phân đoạn có cấu trúc.
Rủi ro: An toàn. Chỉ đọc và lũy đẳng.
Ranh giới: Phân đoạn cấu trúc dựa trên phân tích bố cục; nó không phải là một dàn ý ngữ nghĩa hay một cây cấu trúc tagged-PDF.

`compare_pdfs`

Mục đích: Diff cấu trúc. So sánh hai PDF và trả về một diff có cấu trúc về nội dung văn bản của chúng.
Đầu vào: Hai PDF (source_a và source_b, mỗi cái là một đường dẫn, base64, data URI, hoặc document_id).
Đầu ra: Một cờ giống hệt, tổng số thay đổi, số trang theo từng tài liệu, và một danh sách các vùng đã thay đổi kèm chỉ số trang và dòng.
Rủi ro: An toàn. Chỉ đọc và lũy đẳng.
Ranh giới: Diff nội dung văn bản. Nó không diff việc kết xuất trực quan, font nhúng, hay cấu trúc nhị phân.

`redact_pii`

Mục đích: Phát hiện và che PII. Phát hiện thông tin định danh cá nhân trong lớp văn bản của một PDF và trả về một khung nhìn đã che của văn bản.
Đầu vào: Một PDF (document_id hoặc source); tùy chọn bộ lọc types (email, phone, ssn, credit_card).
Đầu ra: Một cờ có-PII, số lượng phát hiện, văn bản đã che, và danh sách các loại đã quét.
Rủi ro: Rà soát. Kết quả đã che có thể bị lạm dụng nếu được coi là một tài liệu đã làm sạch.
Ranh giới: Đây là phát hiện theo khuôn mẫu và che ở lớp văn bản, không phải xóa che trực quan. Nó không loại bỏ hay ghi đè các glyph trong PDF được kết xuất, và việc so khớp khuôn mẫu không bảo đảm tìm thấy mọi trường hợp dữ liệu nhạy cảm. Đừng coi kết quả của nó là một bảo đảm loại bỏ hoàn toàn PII. Đối với việc xóa che ở cấp tài liệu để phá hủy nội dung nền, hãy dùng bề mặt xóa che chuyên dụng trong các công cụ máy chủ mã nguồn mở hoặc phiên bản Enterprise.

`fill_form`

Mục đích: Dữ liệu điền AcroForm. Tạo dữ liệu XFDF (ISO 19444-1) điền vào các trường AcroForm của PDF từ một ánh xạ tên trường sang giá trị.
Đầu vào: Một ánh xạ fields từ tên trường sang giá trị chuỗi; tùy chọn pdf_filename được nhúng làm tham chiếu XFDF.
Đầu ra: Tài liệu XFDF đã tạo và số lượng trường.
Rủi ro: Rà soát. Nó tạo ra dữ liệu biểu mẫu dùng để áp dụng vào một tài liệu.
Ranh giới: Nó tạo ra XFDF tuân thủ tiêu chuẩn; bản thân nó không ghi các giá trị trở lại vào một PDF. Hãy áp dụng XFDF bằng bất kỳ trình đọc hay công cụ xử lý tuân thủ nào.

`extract_form_data`

Mục đích: Đọc lại AcroForm. Trích xuất tên trường và giá trị AcroForm từ XFDF được nhúng trong một PDF.
Đầu vào: Một PDF (document_id hoặc source).
Đầu ra: Một số lượng trường và một ánh xạ tên trường sang giá trị; một ghi chú tường minh khi không có dữ liệu biểu mẫu nhúng nào.
Rủi ro: An toàn. Chỉ đọc và lũy đẳng.
Ranh giới: Đọc các stream XFDF (ISO 19444-1) được nhúng. Một PDF chỉ giữ giá trị biểu mẫu trong các đối tượng AcroForm mà không có XFDF nhúng sẽ trả về một kết quả rỗng.

`check_accessibility`

Mục đích: Phân tích khả năng tiếp cận cấu trúc. Phân tích khả năng tiếp cận cấu trúc của một PDF — đầu mục, đoạn văn, bảng, và hình — và báo cáo các vấn đề có khả năng xảy ra kèm tham chiếu WCAG.
Đầu vào: Một PDF (document_id hoặc source).
Đầu ra: Một điểm cấu trúc (0–100), một danh sách vấn đề, và một bản tóm tắt phân đoạn.
Rủi ro: An toàn. Chỉ đọc và lũy đẳng.
Ranh giới: Đây là một suy nghiệm cấu trúc, không phải một phán quyết phù hợp. Việc kiểm thử phù hợp PDF/UA và WCAG đầy đủ — cây tag, thứ tự đọc, độ tương phản màu — cần một engine khả năng tiếp cận chuyên dụng. Một điểm cao không phải là một phát biểu về sự phù hợp PDF/UA.

`sign_pdf`

Mục đích: Chữ ký số PAdES B-B. Áp dụng một chữ ký số PAdES B-B (baseline) vào một PDF bằng một chứng chỉ X.509 cục bộ và khóa riêng.
Đầu vào: Một PDF (document_id hoặc source); một chứng chỉ PEM và khóa riêng PKCS#8; một thuật toán tùy chọn (mặc định RSA-SHA256, RSA + SHA-3 256/384/512, hoặc Ed25519); tùy chọn tên bên ký và lý do; một envelope truyền tải AES-GCM tùy chọn bao quanh payload của khóa riêng.
Đầu ra: PDF đã ký, số lượng chữ ký, cờ hoàn tất, và thuật toán, OID, cùng digest đã dùng.
Rủi ro: Yêu cầu phê duyệt. Việc ký là một thao tác có ý nghĩa pháp lý, mang tính phá hủy; máy chủ yêu cầu con người xác nhận tường minh trước khi nó chạy.
Ranh giới: Công cụ này tạo ra một chữ ký PAdES B-B (baseline) — nó không nhúng một dấu thời gian tin cậy hay tài liệu xác thực dài hạn. Các hồ sơ dài hạn (B-LT / B-LTA), giám hộ khóa bằng phần cứng, và ký theo dấu vết kiểm toán là một phần của phiên bản Enterprise; B-T (một chữ ký có dấu thời gian) có sẵn từ engine Core khi một nhà cung cấp dấu thời gian được cấu hình. Xem bề mặt chữ ký Pro để biết các năng lực ký rộng hơn của gói Pro và phiên bản Enterprise cho B-LT/B-LTA.

Cách các công cụ xuất hiện

composer require nextpdf/pro
composer require nextpdf/server

Khi cả hai gói được cài đặt, hãy khởi động NextPDF Server với transport bạn chọn. Máy chủ khám phá bậc Pro lúc khởi động và tám công cụ xuất hiện trong phản hồi MCP tools/list dưới bậc pro cùng với các công cụ Core mã nguồn mở. Ứng dụng của bạn không cần thay đổi mã — việc khám phá chạy tự động và một bậc bị thiếu không bao giờ chặn các bậc khác nạp.

Lược đồ đầu vào và đầu ra có thẩm quyền cho mọi công cụ là lược đồ mà máy chủ công bố trong phản hồi tools/list của nó. Hãy coi phản hồi đó — không phải trang này — là hợp đồng: danh mục này mô tả ý định và ranh giới; lược đồ trực tiếp mô tả chính xác tên trường và kiểu.

Mẫu mã — Khởi động nhanh

Các công cụ Pro được tiêu thụ qua giao thức MCP, không phải qua một API PHP của Pro. Phần tích hợp phía host là việc khởi động NextPDF Server. Khi nextpdf/pro hiện diện, tám công cụ đăng ký thông qua việc khám phá lúc chạy — không cần đấu nối theo từng công cụ — và host sau đó phục vụ chúng cho các agent.

<?php

declare(strict_types=1);

use NextPDF\Server\Mcp\McpServer;

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

// Runtime discovery registers the Pro tier when nextpdf/pro is installed
// alongside nextpdf/server. The consuming application changes no code.
$server = McpServer::create();

// A Pro tool name resolves only when the Pro package is present.
$signTool = $server->getToolRegistry()->get('sign_pdf');

\fwrite(\STDERR, $signTool !== null
    ? "Pro MCP tools active.\n"
    : "Pro MCP tools unavailable; install nextpdf/pro.\n");

// Serve the MCP protocol over stdio (Claude Desktop, Cursor, local agents).
$server->run();

Mẫu mã — Môi trường sản phẩm

Hãy làm cứng đường khởi động. Nạp một tệp chính sách tường minh, từ chối khởi động khi có một ghi đè mức rủi ro không hợp lệ, và xác nhận bậc Pro đã xuất hiện trước khi phục vụ. Việc đấu nối trong McpServer::create() ném ra InvalidArgumentException khi một khối risk_level_overrides cố làm suy yếu một công cụ yêu cầu phê duyệt như sign_pdf, nên một chính sách cấu hình sai sẽ fail closed trước vòng lặp phục vụ.

<?php

declare(strict_types=1);

use NextPDF\Server\Mcp\McpServer;
use NextPDF\Server\Tools\ToolInterface;

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

// A downgrade of an approval-required tool's HITL gate is rejected at boot,
// never silently applied — the server refuses to start on such a policy.
try {
    $server = McpServer::create(__DIR__ . '/nextpdf-mcp.yaml');
} catch (\InvalidArgumentException $e) {
    \fwrite(\STDERR, 'Refusing to start: invalid MCP policy. ' . $e->getMessage() . "\n");
    exit(1);
}

// Confirm the Pro tier surfaced before advertising it to agents.
$signTool = $server->getToolRegistry()->get('sign_pdf');

if (!$signTool instanceof ToolInterface) {
    \fwrite(\STDERR, "nextpdf/pro is not resolving; Pro MCP tools are unavailable.\n");
    exit(1);
}

// sign_pdf is approval-required; the server holds it for human confirmation.
$risk = $signTool->riskLevel()->label();
\fwrite(\STDERR, "Pro MCP tools ready. sign_pdf risk: {$risk}.\n");

$server->run();

Hướng dẫn cho môi trường sản phẩm

Kiểm soát HITL. Giữ sign_pdf phía sau xác nhận của con người. Máy chủ thực thi điều này từ mức rủi ro được khai báo của công cụ; đừng cấu hình agent của bạn để bỏ qua nó. Một người vận hành chỉ có thể siết chặt mức rủi ro của một công cụ, không bao giờ nới lỏng.
Xử lý nguồn. Ưu tiên document_id cho các tài liệu đã có trong phiên. Đối với dữ liệu nội tuyến, các công cụ chấp nhận base64 và URI data:; các payload nội tuyến rất lớn chạy chậm hơn một tài liệu được tham chiếu.
Kỳ vọng về PII. Hãy đặt kỳ vọng cho bên gọi một cách rõ ràng: redact_pii là một trợ giúp phát hiện và che, không phải một bảo đảm làm sạch. Đối với việc loại bỏ không thể đảo ngược, hãy định tuyến đến một bề mặt xóa che chuyên dụng.
Khóa ký. Cung cấp khóa qua envelope mã hóa truyền tải khi transport không bảo mật đầu cuối. Hãy coi vật liệu khóa riêng là một bí mật trong chính sách ghi nhật ký lời gọi công cụ của agent của bạn.
Ghi nhật ký kiểm toán. Các công cụ trên mức an toàn được máy chủ ghi nhật ký kiểm toán. Hãy bảo đảm triển khai của bạn lưu giữ các nhật ký đó theo các yêu cầu tuân thủ của bạn.

Trường hợp ngoại lệ

Phạm vi trang của extract_text đánh số từ 1 và được kẹp về số trang thực của tài liệu; một điểm kết thúc ngoài phạm vi không gây lỗi.
compare_pdfs cần cả hai nguồn; truyền vào một nguồn sẽ trả về một lỗi xác thực rõ ràng thay vì một diff một phần.
extract_form_data trả về một kết quả “không có dữ liệu biểu mẫu nhúng” đã được điền và tường minh thay vì một lỗi cho các PDF không có XFDF nhúng.
sign_pdf từ chối các định danh thuật toán không được hỗ trợ kèm danh sách các giá trị được hỗ trợ; Ed25519 cần phần mở rộng libsodium và các biến thể SHA-3 cần một bản dựng OpenSSL có hỗ trợ SHA-3.
check_accessibility chấm điểm thấp cho các PDF chỉ có ảnh theo thiết kế — nó gắn cờ sự vắng mặt của một lớp văn bản có thể đọc được thay vì thất bại.

Lưu ý bảo mật

Công cụ ký là công cụ duy nhất yêu cầu phê duyệt; máy chủ sẽ không tự động thực thi nó.
Envelope AES-GCM tùy chọn bao quanh khóa riêng xác thực payload; một tag không khớp sẽ fail closed với một lỗi giải mã và không bao giờ quay lại dùng ciphertext.
redact_pii không làm thay đổi PDF nguồn; nó trả về một biểu diễn văn bản đã che. Nó không phải là một thứ thay thế cho việc phá hủy nội dung.
Công cụ xác thực đầu vào trước bất kỳ công việc engine nào; nó từ chối các nguồn dị dạng, data URI, và payload base64 kèm các lỗi tường minh.

Tính phù hợp

Các công cụ biểu mẫu tạo ra và tiêu thụ XFDF theo ISO 19444-1:2019 (XML Forms Data Format).
sign_pdf tạo ra một chữ ký PAdES baseline (B-B) căn chỉnh theo họ PAdES ETSI EN 319 142; các hồ sơ dài hạn là một năng lực Enterprise, và B-T có sẵn từ engine Core khi một nhà cung cấp dấu thời gian được cấu hình.
check_accessibility báo cáo các phát hiện kèm tham chiếu tiêu chí thành công WCAG (ví dụ 1.1.1, 1.3.1, 2.4.6) như hướng dẫn suy nghiệm, không phải một chứng thực phù hợp.

Ranh giới phiên bản

NextPDF Pro đóng góp chính xác tám công cụ MCP, tất cả ở bậc pro. Phiên bản Enterprise đi kèm bộ công cụ MCP riêng của nó ở bậc enterprise — bao gồm kiểm tra tuân thủ, phân tích pháp chứng, tình trạng xác thực dài hạn, chứng nhận sẵn sàng cho AI, và tìm kiếm cùng nhúng tài liệu. Các công cụ đó, đầu vào của chúng, và phần nội bộ của chúng nằm ngoài phạm vi của trang này; xem Công cụ MCP Enterprise. Tài liệu riêng của máy chủ bao quát các công cụ Core (mã nguồn mở) đi kèm với nó. Máy chủ khám phá ba bậc một cách độc lập, và một bậc bị thiếu không bao giờ vô hiệu hóa các bậc khác.

Lưu ý ranh giới Enterprise

Pro đóng góp chính xác tám công cụ MCP ở bậc pro. Phiên bản Enterprise đi kèm một bộ công cụ MCP riêng ở bậc enterprise (kiểm tra tuân thủ, phân tích pháp chứng, tình trạng xác thực dài hạn, chứng nhận sẵn sàng cho AI, tìm kiếm và nhúng tài liệu) cùng các hồ sơ chữ ký có dấu thời gian/dài hạn; những thứ đó không được bậc Pro cung cấp. Xem mục Ranh giới phiên bản ở trên để biết phân tách bậc đầy đủ.

Phương án dự phòng / thay thế ở Core

NextPDF Server mã nguồn mở cung cấp cho bất kỳ AI agent nào một bộ công cụ PDF Core có tính tất định (tạo tài liệu, văn bản, bảng, chẩn đoán) mà không cần giấy phép. Tám công cụ nâng cao trên trang này là các bổ sung của Pro. Xem /connect/tools/.

Ranh giới công bố

Trang này chỉ ghi lại hành vi quan sát được từ bên ngoài và bề mặt API công khai đượ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 nằm ngoài phạm vi.