Pro phiên bản

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

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

Năng lực này xuất xưởng trong NextPDF Pro (nextpdf/pro) và kích hoạt bằng một phong bì giấy phép tier Pro. 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.

Không có cờ giấy phép theo từng tính năng. Phần mã xuất xưởng cùng phiên bản Pro, và tám công cụ đăng ký dưới tier pro khi gói Pro phân giải lúc khởi động cùng với nextpdf/server.

Hợp đồng hành vi

NextPDF Server khám phá các tier lúc khởi động bằng cách thăm dò lớp tool-provider của Pro; nếu nó phân giải được, server đăng ký tám công cụ dưới tier pro. Gói Pro không phải là một phụ thuộc bắt buộc của server, nên các công cụ Pro hoàn toàn là tùy chọn bật bằng cách đồng cài đặt. Việc đăng ký tier là độc lập: một tier bị thiếu hoặc bị chính sách loại trừ không bao giờ chặn các tier khác.
Mỗi công cụ khai báo một trong bốn mức rủi ro (safe, caution, review, approval-required). Một override tùy chọn của người vận hành chỉ có thể nâng mức của một công cụ lên, không bao giờ hạ xuống; server audit-log mọi lần thực thi ở mức caution trở lên. sign_pdf là approval-required.
Đầu vào PDF phân giải theo một thứ tự cố định: document_id từ kho lưu trong bộ nhớ, rồi source dưới dạng một data: URI, đường dẫn hệ thống tệp, hoặc base64 thô. Đầu vào bị thiếu sẽ trả về một lỗi xác thực thay vì xử lý một tài liệu rỗng.
sign_pdf chỉ tạo ra một chữ ký baseline PAdES B-B — không có dấu thời gian, không có xác thực dài hạn. Các thuật toán được hỗ trợ và phong bì key-transport AES-GCM được trình bày chi tiết bên dưới; việc giải mã fail closed và công cụ không bao giờ dùng ciphertext làm vật liệu khóa.
Xem các phần bên dưới để biết toàn bộ chi tiết về khám phá, rủi ro, phân giải nguồn, từng công cụ, và việc ký. Trang này chỉ mô tả hành vi quan sát được từ bên ngoài và hợp đồng công cụ đã công bố.

Phạm vi

Trang này là tài liệu tham chiếu dành cho người vận hành và người tích hợp về tám công cụ MCP của Pro. Nó bao quát mô hình khám phá, ngữ nghĩa risk/HITL mà server áp dụng, các quy tắc phân giải nguồn, phong bì key-transport khi ký, và hành vi khi lỗi của từng công cụ. Nó chỉ mô tả hành vi quan sát được từ bên ngoài và hợp đồng công cụ đã công bố. Để xem danh mục dành cho người dùng, hãy xem trang MCP công khai.

Mô hình khám phá và đăng ký

NextPDF Server khám phá các nhà cung cấp tier lúc khởi động. Nó phát hiện tier Pro bằng cách thăm dò lớp tool-provider của Pro; nếu lớp đó phân giải được, server khởi tạo nhà cung cấp và đăng ký mỗi công cụ mà nó trả về dưới tier pro. Gói Pro được chủ ý không đặt làm phụ thuộc bắt buộc của server — điều này giữ cho server mã nguồn mở vẫn cài đặt được mà không cần gói độc quyền, và biến các công cụ Pro thành hoàn toàn tùy chọn bật bằng cách đồng cài đặt.

Server cô lập việc đăng ký theo từng tier. Nếu gói Pro vắng mặt, các công cụ Core vẫn đăng ký; một nhà cung cấp tier hiện diện không chặn các tier khác. Việc đăng ký công cụ cũng tuân theo danh sách cho phép của chính sách bảo mật của server: một công cụ bị chính sách loại trừ sẽ âm thầm không được đăng ký và không được tính trong bản tóm tắt tier. Server phơi bày một số đếm theo từng tier (core / pro / enterprise) để chẩn đoán và ghi nhật ký.

Nhà cung cấp trả về tám công cụ theo một thứ tự cố định: trích xuất văn bản, phân đoạn, so sánh, che PII, điền biểu mẫu, đọc lại biểu mẫu, phân tích khả năng tiếp cận, ký. Thứ tự ổn định nhưng bên gọi không được phụ thuộc vào nó — hãy phân giải các công cụ theo tên giao thức MCP của chúng.

Mô hình rủi ro và ngữ nghĩa HITL

Mỗi công cụ khai báo một trong bốn mức rủi ro. Server dùng mức đã khai báo để thực thi human-in-the-loop:

Safe — chỉ đọc, không có hiệu ứng phụ. Tự động thực thi.
Caution — tạo hoặc sửa đổi trạng thái trong bộ nhớ. Tự động thực thi kèm một mục audit-log.
Review — tạo ra đầu ra có thể bị lạm dụng. Tự động thực thi, nhưng phần hướng dẫn kỹ năng của agent đánh dấu nó để agent cảnh báo người dùng.
Approval-required — mang tính phá hủy, pháp lý, hoặc quan trọng về quyền riêng tư. Server yêu cầu xác nhận tường minh của con người trước khi thực thi.

Phân loại công cụ Pro: năm công cụ trích xuất/phân tích (extract_text, segment_document, compare_pdfs, extract_form_data, check_accessibility) là safe; redact_pii và fill_form là review; sign_pdf là approval-required.

Mức rủi ro đến từ đúng hai nguồn: chính khai báo của công cụ, và một override tùy chọn của người vận hành lúc chạy. Override chỉ có thể nâng mức rủi ro của một công cụ (siết chặt thực thi); nó không bao giờ có thể hạ xuống. Server audit-log mọi lần thực thi ở mức caution trở lên. Mô hình rủi ro mang theo một phiên bản; server quảng bá phiên bản đó trong phản hồi khởi tạo của nó để các client có thể phát hiện một thay đổi không tương thích.

Thứ tự phân giải nguồn

Mọi công cụ nhận một PDF đều chấp nhận nó qua một trong ba hình thức đầu vào, được phân giải theo thứ tự này:

document_id — server truy xuất các byte từ kho tài liệu trong bộ nhớ của nó. Một id không xác định sẽ thất bại với một lỗi tường minh hướng dẫn bên gọi tạo tài liệu trước.
source dưới dạng một data: URI — công cụ giải mã phần thân base64 sau dấu phẩy.
source dưới dạng một đường dẫn hệ thống tệp — công cụ đọc từ đĩa khi đường dẫn phân giải tới một tệp.
source dưới dạng một chuỗi base64 thô — công cụ chỉ chấp nhận và giải mã đầu vào đủ dài và có dạng base64.

compare_pdfs áp dụng cùng quy tắc phân giải một cách độc lập cho source_a và source_b, và bổ sung chấp nhận một giá trị document_id ở một trong hai khe source. Nếu không có cả document_id lẫn source, công cụ trả về một lỗi xác thực thay vì xử lý một tài liệu rỗng.

Tham chiếu theo từng công cụ

Tool	Risk	Inputs	Result fields	Behavioral boundary
`extract_text`	safe	PDF; tùy chọn `page_start` / `page_end` đánh chỉ số từ 1	text, tổng số trang	Chỉ tầng văn bản; các dải bị giới hạn theo số trang thực; không OCR
`segment_document`	safe	PDF	số đoạn, danh sách đoạn	Các đoạn suy ra từ bố cục; không phải cây cấu trúc PDF được gắn thẻ
`compare_pdfs`	safe	hai PDF	cờ giống hệt, tổng số thay đổi, số trang theo từng tài liệu, các vùng (loại, văn bản, page index, line index, văn bản đối ứng tùy chọn)	So sánh nội dung văn bản; không trực quan hay nhị phân
`redact_pii`	review	PDF; tùy chọn `types` (`email`, `phone`, `ssn`, `credit_card`)	cờ có-PII, số lượng phát hiện, văn bản đã che, các loại đã quét	Phát hiện/che ở tầng văn bản; không phải che trực quan; dựa trên mẫu, không vét cạn
`fill_form`	review	map `fields`; tùy chọn `pdf_filename`	tài liệu XFDF, số trường	Tạo ra XFDF (ISO 19444-1); không ghi giá trị vào một PDF
`extract_form_data`	safe	PDF	số trường, map trường, ghi chú tường minh khi không có	Chỉ đọc XFDF được nhúng
`check_accessibility`	safe	PDF	điểm cấu trúc (0–100), các vấn đề, bản tóm tắt đoạn	Heuristic cấu trúc kèm tham chiếu WCAG; không phải một phán quyết phù hợp
`sign_pdf`	approval-required	PDF; PEM cert + PKCS#8 key; tùy chọn algorithm, signer name, reason, transport envelope	PDF đã ký, số chữ ký, cờ hoàn tất, algorithm, OID, digest	Chỉ baseline PAdES B-B; không dấu thời gian, không LTV

Ký: thuật toán và key transport

sign_pdf tạo ra một chữ ký baseline PAdES B-B. Các thuật toán được hỗ trợ, chấp nhận ở cả cách viết gạch dưới lẫn gạch nối:

RSA với SHA-256 (mặc định).
RSA với SHA-3 256 / 384 / 512 — yêu cầu một bản dựng OpenSSL có hỗ trợ SHA-3.
Ed25519 — yêu cầu phần mở rộng libsodium; khóa phải là một PKCS#8 PEM bọc khóa riêng Ed25519.

Công cụ từ chối các định danh không được hỗ trợ và trả về danh sách các giá trị được chấp nhận.

Phong bì mã hóa transport tùy chọn cho phép một bên gọi tạo đường hầm cho khóa riêng qua một transport vốn không bảo mật đầu-cuối. Phong bì chỉ dùng AES-GCM:

Khóa đối xứng: 16, 24, hoặc 32 byte (AES-128/192/256), mã hóa base64.
Nonce: đúng 12 byte, mã hóa base64.
Dữ liệu xác thực bổ sung tùy chọn, mã hóa base64.
Payload private_key là ciphertext base64 kèm một tag xác thực GCM 16 byte ở cuối.

Việc giải mã fail closed: một sự không khớp tag xác thực hoặc một payload dị dạng sẽ trả về một lỗi giải mã, và công cụ không bao giờ dùng ciphertext làm vật liệu khóa. Công cụ từ chối kích thước khóa hoặc nonce sai trước khi thực hiện bất kỳ thao tác mã hóa nào.

Trường hợp ngoại lệ và chế độ FIPS

extract_text: công cụ giới hạn điểm cuối dải trang vượt quá tài liệu thay vì từ chối nó, và chuẩn hóa một điểm bắt đầu nằm dưới trang đầu tiên về trang đầu tiên.
compare_pdfs: thiếu source_a hoặc source_b sẽ trả về một lỗi xác thực; các tài liệu giống hệt trả về một kết quả giống-hệt tường minh với số thay đổi bằng không.
extract_form_data: các PDF không có một stream XFDF được nhúng sẽ trả về một kết quả không-trường kèm một ghi chú giải thích, không phải một lỗi.
redact_pii: một mục không nhận diện được trong types sẽ bị bỏ qua; một danh sách toàn-không-nhận-diện sẽ cho một lượt quét rỗng thay vì một thất bại.
sign_pdf: thiếu chứng chỉ hoặc khóa riêng sẽ thất bại trước khi có bất kỳ công đoạn ký nào; công cụ kiểm tra các yêu cầu của thuật toán (hỗ trợ SHA-3 của OpenSSL, libsodium cho Ed25519) tại thời điểm ký và phơi bày chúng dưới dạng các lỗi tường minh.
Chế độ FIPS: tính khả dụng của thuật toán tuân theo bản dựng OpenSSL/libsodium của host. Trong một bản dựng bị ràng buộc FIPS, các thuật toán không được phê duyệt sẽ thất bại tại ranh giới mã hóa với một lỗi tường minh thay vì âm thầm hạ cấp. Tầng MCP không thêm hay nới lỏng chính sách mã hóa — nó phơi bày quyết định của nhà cung cấp mã hóa của host.

Ghi chú runbook cho người vận hành

Giữ sign_pdf ở mức approval-required. Hãy xác nhận không có override nào của người vận hành nâng rủi ro trên các công cụ safe một cách ngoài ý muốn — vì các override chỉ siết chặt, nên một override vô tình làm giảm tính sẵn sàng chứ không giảm an toàn.
Lưu giữ audit: mọi lần thực thi ở mức review trở lên đều được server audit-log. Hãy định cỡ việc lưu giữ nhật ký của bạn theo khối lượng các lệnh gọi redact_pii, fill_form, và sign_pdf.
Lựa chọn transport: khi chạy trên một transport vốn không bảo mật đầu-cuối, hãy yêu cầu phong bì key-transport AES-GCM cho sign_pdf và 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ệnh gọi công cụ của agent của bạn.
Số đếm tier: hãy dùng số đếm theo từng tier của server để khẳng định lúc triển khai rằng tier Pro đã đăng ký tám công cụ; một số đếm bằng không cho thấy gói Pro đã không phân giải được.

Ranh giới phiên bản

Tier Pro đóng góp đúng tám công cụ MCP. Phiên bản Enterprise xuất xưởng một tier MCP riêng với các công cụ của riêng nó — tuân thủ, 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/embedding tài liệu. Đầu vào, đầu ra, và phần nội bộ của các công cụ Enterprise nằm ngoài phạm vi ở đây và được mô tả cùng với phiên bản Enterprise. Server khám phá các tier một cách độc lập; một tier bị thiếu không bao giờ vô hiệu hóa một tier khác.

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ộ, các lớp trợ giúp, các bảng cơ chế, tên tệp runbook, và các tiền tố ticket đều nằm ngoài phạm vi.