Tài liệu tham chiếu API NextPDF Connect
Tổng quan nhanh
Phần tiêu đề “Tổng quan nhanh”Trang này là tài liệu tham chiếu cấp ký hiệu cho NextPDF Connect server (nextpdf/server). Trang liệt kê từng tool theo tên tool đã đăng ký và lớp triển khai, đồng thời mô tả dịch vụ gRPC NextPDFConnect, bao gồm các phương thức Remote Procedure Call (RPC) cùng thông điệp yêu cầu và phản hồi. Trang cũng định nghĩa hợp đồng xác thực, lỗi và giới hạn tốc độ dùng chung cho mọi transport.
Server cung cấp một registry tool duy nhất qua ba transport: Model Context Protocol (MCP) qua đầu vào và đầu ra chuẩn, một Application Programming Interface (API) theo kiểu Representational State Transfer (REST), và gRPC. Mỗi transport có trang riêng mô tả chi tiết wire của mình: xem MCP transport, REST transport, và gRPC transport. Trang này tổng hợp các ký hiệu mà những transport đó mang theo.
Tên tool, lớp và bậc rủi ro được đọc từ phần triển khai tool trong src/Tools/. Số lượng tool mà một lần triển khai cung cấp là thuộc tính tại thời điểm chạy; xem Tool catalog. Boot and discovery giải thích cách phân giải bậc.
Khả dụng của transport
Phần tiêu đề “Khả dụng của transport”Một tool khả dụng trên từng transport đang chạy trong lần triển khai. Các transport chạy như những tiến trình độc lập; khởi động một transport không khởi động các transport còn lại.
| Transport | Điểm vào | Định dạng wire | Xác thực |
|---|---|---|---|
| MCP | bin/nextpdf-mcp | JavaScript Object Notation Remote Procedure Call (JSON-RPC) 2.0 qua stdio | Ranh giới tiến trình hệ điều hành (không có API key) |
| REST | bin/nextpdf-server | HTTP, OpenAPI 3.1 | Bearer API key trong Authorization header |
| gRPC | bin/nextpdf-grpc | Protocol Buffers, gói nextpdf.connect.v1 | Bearer token trong authorization call metadata |
Qua MCP, bạn gọi một tool bằng tools/call và tên tool đã đăng ký. Qua REST và gRPC, bạn truy cập cùng các khả năng của engine thông qua các bề mặt render, operation và capability; xem bảng tuyến đường của REST transport và bảng RPC của gRPC transport.
Xác thực và bậc rủi ro
Phần tiêu đề “Xác thực và bậc rủi ro”Xác thực bằng API key
Phần tiêu đề “Xác thực bằng API key”Các transport REST và gRPC yêu cầu một bearer API key trên mọi yêu cầu, ngoại trừ các health probe không cần xác thực. Một key có dạng npk_live_{kid}_{secret}: kid là định danh tám ký tự dùng để tra cứu bản ghi, còn phần secret mang entropy. Server chỉ lưu bản tóm tắt SHA-256 của key và so sánh token được gửi ở thời gian hằng định, nên key không hợp lệ không tiết lộ gì qua thời gian xử lý. REST đọc token từ header Authorization: Bearer …; gRPC đọc cùng token đó từ call metadata authorization. Transport MCP stdio không có API key vì đây là tiến trình con cục bộ do client đáng tin cậy khởi chạy. Security and operations mô tả mô hình xác thực đầy đủ.
Bốn bậc rủi ro
Phần tiêu đề “Bốn bậc rủi ro”Mỗi tool khai báo một trong bốn mức rủi ro có thứ tự, được định nghĩa bởi enum RiskLevel trong src/Config/RiskLevel.php.
| Bậc | Trường hợp enum | Giá trị | Hiệu lực |
|---|---|---|---|
| Safe | RiskLevel::Safe | 0 | Chỉ đọc, không có tác dụng phụ. Tự động thực thi. |
| Caution | RiskLevel::Caution | 1 | Tạo hoặc sửa đổi trạng thái trong bộ nhớ. Tự động thực thi, có ghi nhật ký kiểm toán. |
| Review | RiskLevel::Review | 2 | Tạo ra kết quả có thể bị lạm dụng. Tự động thực thi, có ghi nhật ký kiểm toán. |
| ApprovalRequired | RiskLevel::ApprovalRequired | 3 | Mang tính phá hủy, pháp lý hoặc nhạy cảm về quyền riêng tư. Yêu cầu xác nhận của con người. |
Rủi ro hiệu dụng của một tool chỉ đến từ hai nguồn: chính khai báo riskLevel() của tool và cấu hình ghi đè tùy chọn của người vận hành; cấu hình này chỉ có thể tăng rủi ro, không bao giờ hạ thấp một tool ApprovalRequired. Xem HITL risk tiers và Configuration.
Cách luồng token phê duyệt hoạt động
Phần tiêu đề “Cách luồng token phê duyệt hoạt động”Khi bạn gọi một tool ApprovalRequired mà không có token hợp lệ, ConfirmationGate (src/Mcp/ConfirmationGate.php) trả về một challenge token dùng một lần thay vì chạy tool. Agent chuyển challenge đó cho một con người, rồi gọi lại chính tool đó bằng token được cấp trong đối số _confirmation_token. Token gắn với tên tool, một nonce ngẫu nhiên và thời gian sống (TTL) 300 giây. Token không gắn với các đối số và không phải là thông tin xác thực. Trên REST, bearer API key vẫn xác thực yêu cầu, và cùng cổng đó chạy trong tool executor dùng chung trước thao tác được kiểm soát. Trên gRPC, cùng cổng đó chạy trước thao tác được điều phối. Cơ chế challenge và token giống nhau trên các transport.
Tool và endpoint
Phần tiêu đề “Tool và endpoint”Bảng mô tả từng tool theo tên tool đã đăng ký (cột Ký hiệu) và lớp triển khai. Các tool được nhóm theo bậc và danh mục. Tất cả các lớp Abstract Syntax Tree (AST) và lớp mutation nằm trong src/Tools/Ast và src/Tools/Ast/Mutation; lớp extraction nằm trong src/Tools/Extraction; các lớp còn lại nằm trong src/Tools/Core.
Tool tài liệu cốt lõi
Phần tiêu đề “Tool tài liệu cốt lõi”| Ký hiệu | Tham số | Hành vi mặc định | Trả về | Ném ra hoặc thất bại với | Ghi chú |
|---|---|---|---|---|---|
create_pdf | page_size (mặc định A4), orientation (portrait/landscape), title, author; không trường nào bắt buộc. | Tạo một tài liệu trong bộ nhớ và một trang; đặt metadata khi được cung cấp. | JSON với document_id, page_count, page_size, orientation. | Trả về kết quả lỗi kèm thông điệp của engine khi thất bại. | Lớp CreatePdfTool. Rủi ro RiskLevel::Caution. Bậc core. document_id được trả về sẽ là đầu vào cho mọi thao tác tiếp theo. |
add_page | document_id (bắt buộc), kích thước trang và hướng tùy chọn. | Thêm một trang vào tài liệu. | JSON với số trang mới. | Kết quả lỗi khi document_id không xác định. | Lớp AddPageTool. Rủi ro RiskLevel::Caution. Bậc core. |
add_text | document_id (bắt buộc), text (bắt buộc), vị trí và kiểu dáng tùy chọn. | Thêm văn bản vào tài liệu. | Bản tóm tắt trạng thái tài liệu dạng JSON. | Kết quả lỗi khi document_id không xác định. | Lớp AddTextTool. Rủi ro RiskLevel::Caution. Bậc core. |
add_image | document_id (bắt buộc), source (bắt buộc: đường dẫn tệp hoặc base64), vị trí đặt tùy chọn. | Thêm hình ảnh từ đường dẫn hoặc dữ liệu base64. | Bản tóm tắt trạng thái tài liệu dạng JSON. | Kết quả lỗi khi nguồn không đọc được hoặc document_id không xác định. | Lớp AddImageTool. Rủi ro RiskLevel::Caution. Bậc core. |
add_table | document_id (bắt buộc), html (bắt buộc). | Kết xuất một bảng Hypertext Markup Language (HTML) vào tài liệu. | Bản tóm tắt trạng thái tài liệu dạng JSON. | Kết quả lỗi khi markup không hợp lệ hoặc document_id không xác định. | Lớp AddTableTool. Rủi ro RiskLevel::Caution. Bậc core. |
set_font | document_id (bắt buộc), family (bắt buộc), kích thước và kiểu dáng tùy chọn. | Đặt phông chữ cho các thao tác văn bản tiếp theo. | JSON xác nhận phông chữ đang hoạt động. | Kết quả lỗi khi phông chữ không xác định hoặc document_id không xác định. | Lớp SetFontTool. Rủi ro RiskLevel::Caution. Bậc core. |
output_pdf | document_id (bắt buộc), file_path (tùy chọn), destroy (mặc định true). | Hoàn tất tài liệu; ghi vào file_path, hoặc trả về base64 khi bỏ qua; mặc định hủy tài liệu. | JSON với file_path và file_size, hoặc base64 và file_size. | Kết quả lỗi khi document_id không xác định; lỗi kiểm soát đường dẫn khi ghi ra ngoài thư mục cơ sở. | Lớp OutputPdfTool. Rủi ro RiskLevel::ApprovalRequired. Bậc core. Việc ghi một tệp đi qua cổng xác nhận; chế độ base64 thì không cần. |
preview_layout | document_id (bắt buộc). | Trả về một bản tóm tắt bố cục mà không kết xuất PDF cuối cùng. | Bản tóm tắt bố cục dạng JSON. | Kết quả lỗi khi document_id không xác định. | Lớp PreviewLayoutTool. Rủi ro RiskLevel::Safe. Bậc core. |
parse_pdf | document_id (bắt buộc). | Kiểm tra metadata cấu trúc: số trang, phông chữ, hình ảnh, mã hóa và Info Dictionary. | Metadata cấu trúc dạng JSON. | Kết quả lỗi với một tài liệu sai định dạng. | Lớp ParsePdfTool. Rủi ro RiskLevel::Safe. Bậc core. Chỉ đăng ký khi NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED là true hoặc 1. |
Tool chẩn đoán cốt lõi
Phần tiêu đề “Tool chẩn đoán cốt lõi”| Ký hiệu | Tham số | Hành vi mặc định | Trả về | Ném ra hoặc thất bại với | Ghi chú |
|---|---|---|---|---|---|
diagnostic.doctor | không có. | Chạy một lần kiểm tra tình trạng và trả về chẩn đoán môi trường có cấu trúc. | Báo cáo môi trường dạng JSON. | Kết quả lỗi khi một lần kiểm tra nội bộ thất bại. | Lớp DiagnosticDoctorTool. Rủi ro RiskLevel::Safe. Bậc core. Không cần tài liệu và không cần xác nhận. |
diagnostic.capabilities | không có. | Liệt kê các khả năng kèm thông tin về bậc và trạng thái. | Danh sách khả năng dạng JSON. | Kết quả lỗi khi xảy ra thất bại nội bộ. | Lớp DiagnosticCapabilitiesTool. Rủi ro RiskLevel::Safe. Bậc core. |
diagnostic.inspect | document_id (bắt buộc). | Kiểm tra một PDF và trả về metadata cấu trúc. | Metadata cấu trúc dạng JSON. | Kết quả lỗi khi document_id không xác định. | Lớp DiagnosticInspectTool. Rủi ro RiskLevel::Safe. Bậc core. |
diagnostic.verify | document_id (bắt buộc), profile PDF/A hoặc PDF/UA tùy chọn. | Xác minh tính toàn vẹn cấu trúc; tùy chọn xác thực PDF/A hoặc PDF/UA bằng cách khởi chạy một tiến trình con VeraPDF. | Báo cáo xác minh dạng JSON. | Kết quả lỗi khi tiến trình con thất bại, hết thời gian chờ, hoặc đầu vào quá lớn. | Lớp DiagnosticVerifyTool. Rủi ro RiskLevel::Caution. Bậc core. Đầu vào bị giới hạn ở 50 mebibyte (MiB). |
Tool mã vạch cốt lõi
Phần tiêu đề “Tool mã vạch cốt lõi”| Ký hiệu | Tham số | Hành vi mặc định | Trả về | Ném ra hoặc thất bại với | Ghi chú |
|---|---|---|---|---|---|
generate_barcode | payload (bắt buộc), format (ví dụ QR Code, DataMatrix). | Tạo ma trận module mã vạch hai chiều cho payload. | Ma trận module dạng JSON. | Kết quả lỗi khi format không được hỗ trợ hoặc payload không hợp lệ. | Lớp BarcodeTool. Rủi ro RiskLevel::Caution. Bậc core. BarcodeTool chỉ đăng ký khi registry encoder barcode của core có mặt trong bản cài nextpdf/core; tên tool đã đăng ký là generate_barcode. |
Tool quyền riêng tư Enterprise
Phần tiêu đề “Tool quyền riêng tư Enterprise”Những tool này bao bọc các lớp quyền riêng tư của Enterprise và chỉ được đăng ký dưới bậc Enterprise khi các lớp đó có thể được autoload. Chúng hoạt động trên nội dung văn bản thuần.
| Ký hiệu | Tham số | Hành vi mặc định | Trả về | Ném ra hoặc thất bại với | Ghi chú |
|---|---|---|---|---|---|
redact_pdf | content (bắt buộc), các tùy chọn phát hiện tùy chọn. | Bôi đen phá hủy thông tin nhận dạng cá nhân (PII) trong nội dung văn bản thuần bằng engine bôi đen của Enterprise. | JSON với nội dung đã bôi đen và một hash SHA-256. | Kết quả lỗi khi các lớp Enterprise vắng mặt hoặc việc phát hiện thất bại. | Lớp RedactPdfTool. Rủi ro RiskLevel::Review. Bậc enterprise. |
deidentify_pdf | content (bắt buộc), strategy (bôi đen hoặc loại bỏ). | Áp dụng chiến lược khử nhận dạng có hệ thống lên nội dung văn bản thuần bằng bộ khử nhận dạng của Enterprise. | JSON với nội dung đã khử nhận dạng. | Kết quả lỗi khi các lớp Enterprise vắng mặt. | Lớp DeIdentifyPdfTool. Rủi ro RiskLevel::Review. Bậc enterprise. |
zone_redact_pdf | content (bắt buộc), zones (trang cùng danh sách hình chữ nhật đã chuẩn hóa). | Áp dụng các lần bôi đen vùng dựa trên tọa độ bằng engine bôi đen của Enterprise. | JSON với nội dung đã bôi đen. | Kết quả lỗi khi vùng không hợp lệ hoặc các lớp Enterprise vắng mặt. | Lớp ZoneRedactionTool. Rủi ro RiskLevel::Review. Bậc enterprise. |
Tool đọc cây cú pháp trừu tượng (AST)
Phần tiêu đề “Tool đọc cây cú pháp trừu tượng (AST)”Những tool này được phân phối kèm server, được đăng ký dưới bậc Pro, và được kiểm soát bởi NEXTPDF_AST_TOOLS_ENABLED (bật theo mặc định). Chúng chỉ đọc.
| Ký hiệu | Tham số | Hành vi mặc định | Trả về | Ném ra hoặc thất bại với | Ghi chú |
|---|---|---|---|---|---|
get_document_ast | pdf_data (bắt buộc). | Xây dựng một AST ngữ nghĩa: một cây node đầy đủ với neo trích dẫn cho mọi phần tử cấu trúc. | Cây node dạng JSON kèm một ETag để kiểm soát đồng thời. | Kết quả lỗi với một tài liệu sai định dạng. | Lớp GetDocumentAstTool. Rủi ro RiskLevel::Safe. Bậc pro. |
get_ast_node | pdf_data (bắt buộc), node_id (bắt buộc). | Lấy một node AST đơn lẻ và tất cả con của nó. | Node dạng JSON kèm các node con. | Kết quả lỗi với một node_id không xác định. | Lớp GetAstNodeTool. Rủi ro RiskLevel::Safe. Bậc pro. |
get_ast_diff | original_pdf_data (bắt buộc), modified_pdf_data (bắt buộc). | So sánh cấu trúc hai tài liệu bằng cách đối chiếu AST ngữ nghĩa của chúng. | JSON gồm các node được thêm, bị xóa và bị thay đổi. | Kết quả lỗi với một tài liệu đầu vào sai định dạng. | Lớp GetAstDiffTool. Rủi ro RiskLevel::Safe. Bậc pro. |
search_ast_nodes | pdf_data (bắt buộc), tùy chọn lọc theo loại, chỉ số trang và văn bản. | Tìm kiếm node AST theo loại, chỉ số trang hoặc nội dung văn bản. | Danh sách phẳng dạng JSON gồm các node khớp kèm các node con ở mức nông. | Kết quả lỗi với một tài liệu sai định dạng. | Lớp SearchAstNodesTool. Rủi ro RiskLevel::Safe. Bậc pro. |
extract_cited_text | pdf_data (bắt buộc), headings_only tùy chọn. | Trích xuất các khối văn bản với neo trích dẫn (trang, hộp bao, độ tin cậy). | Các khối văn bản đã trích dẫn dạng JSON. | Kết quả lỗi với một tài liệu sai định dạng. | Lớp ExtractCitedTextTool. Rủi ro RiskLevel::Safe. Bậc pro. Danh mục ast. |
extract_cited_tables | pdf_data (bắt buộc). | Trích xuất các khối bảng với neo trích dẫn; trả về một ma trận ô theo hàng cho mỗi node Table. | Các ma trận bảng dạng JSON kèm neo. | Kết quả lỗi với một tài liệu sai định dạng. | Lớp ExtractCitedTablesTool. Rủi ro RiskLevel::Safe. Bậc pro. Danh mục extraction. |
Tool mutation AST
Phần tiêu đề “Tool mutation AST”Những tool này được phân phối kèm server, được đăng ký dưới bậc Pro, và được kiểm soát bởi NEXTPDF_MUTATION_TOOLS_ENABLED (bật theo mặc định). Cả bốn đều là ApprovalRequired và dùng kiểm soát đồng thời lạc quan (OCC) thông qua một ETag.
| Ký hiệu | Tham số | Hành vi mặc định | Trả về | Ném ra hoặc thất bại với | Ghi chú |
|---|---|---|---|---|---|
apply_ast_mutations | pdf_data, etag, idempotency_key, mutations (tất cả đều bắt buộc). | Áp dụng một lô mutation một cách nguyên tử; phát lại kết quả đã lưu cache khi gặp lại cùng idempotency_key. | JSON với PDF sau mutation và một ETag mới. | Xung đột OCC khi ETag đã cũ; lỗi xác thực với một mutation sai định dạng. | Lớp ApplyAstMutationsTool. Rủi ro RiskLevel::ApprovalRequired. Bậc pro. |
delete_ast_node | pdf_data, node_id, etag (tất cả đều bắt buộc). | Loại bỏ một node ở chế độ overlay (nội dung gốc bị che phủ, không bị xóa vật lý). | JSON với PDF đã sửa đổi và một ETag mới. | Xung đột OCC khi ETag đã cũ; lỗi với một node_id không xác định. | Lớp DeleteAstNodeTool. Rủi ro RiskLevel::ApprovalRequired. Bậc pro. |
insert_ast_node | pdf_data, parent_node_id, position, etag, node (tất cả đều bắt buộc). | Chèn một node mới làm con của node cha tại vị trí được chỉ định. | JSON với PDF đã sửa đổi và một ETag mới. | Xung đột OCC khi ETag đã cũ; lỗi xác thực với một node sai định dạng. | Lớp InsertAstNodeTool. Rủi ro RiskLevel::ApprovalRequired. Bậc pro. |
update_ast_node | pdf_data, node_id, etag, updates (tất cả đều bắt buộc). | Cập nhật nội dung văn bản của một node. | JSON với PDF đã sửa đổi và một ETag mới. | Xung đột OCC khi ETag đã cũ; lỗi với một node_id không xác định. | Lớp UpdateAstNodeTool. Rủi ro RiskLevel::ApprovalRequired. Bậc pro. |
Lược đồ yêu cầu và phản hồi
Phần tiêu đề “Lược đồ yêu cầu và phản hồi”Transport gRPC định nghĩa lược đồ có kiểu cho server trong gói Protocol Buffers nextpdf.connect.v1, trong proto/nextpdf/connect/v1/*.proto. Dịch vụ và các thông điệp của nó là các ký hiệu lược đồ chính tắc.
Dịch vụ NextPDFConnect
Phần tiêu đề “Dịch vụ NextPDFConnect”Dịch vụ NextPDFConnect cung cấp các RPC unary và server-streaming. Các ký hiệu lược đồ là tên các phương thức RPC cùng các thông điệp yêu cầu và phản hồi mà chúng mang theo.
| RPC | Thông điệp yêu cầu | Thông điệp phản hồi | Hình thái |
|---|---|---|---|
Render | RenderRequest | RenderResponse | Unary. Render đồng bộ không trạng thái. |
RenderStream | RenderRequest | RenderChunk (stream) | Server-streaming. Render được phân phối thành các chunk có thứ tự. |
SubmitJob | SubmitJobRequest | JobResponse | Unary. Gửi một job render bất đồng bộ. |
GetJobStatus | GetJobStatusRequest | JobResponse | Unary. Thăm dò trạng thái job. |
GetJobResult | GetJobResultRequest | RenderResponse | Unary. Tải xuống một kết quả đã hoàn tất. |
GetJobResultStream | GetJobResultRequest | RenderChunk (stream) | Server-streaming. Tải xuống một kết quả đã hoàn tất dưới dạng các chunk. |
CancelJob | CancelJobRequest | JobResponse | Unary. Hủy hoặc xóa một job. |
CreateSession | CreateSessionRequest | SessionResponse | Unary. Tạo một session dựng tài liệu. |
GetSession | GetSessionRequest | SessionResponse | Unary. Lấy metadata session. |
DestroySession | DestroySessionRequest | DestroySessionResponse | Unary. Hủy một session và tài liệu của nó. |
SessionOperation | SessionOperationRequest | SessionResponse | Unary. Thực thi một thao tác trên một tài liệu session. |
SessionRender | SessionRenderRequest | RenderResponse | Unary. Render một tài liệu session thành PDF. |
SessionRenderStream | SessionRenderRequest | RenderChunk (stream) | Server-streaming. Render một tài liệu session dưới dạng các chunk. |
ExecuteCapability | CapabilityRequest | CapabilityResponse | Unary. Thực thi một thao tác capability được kiểm soát theo bậc. |
GetCapabilities | GetCapabilitiesRequest | GetCapabilitiesResponse | Unary. Liệt kê các khả năng cho client đã xác thực. |
HealthCheck | HealthCheckRequest | HealthCheckResponse | Unary. Thăm dò tình trạng sống (liveness). |
ReadinessCheck | ReadinessCheckRequest | ReadinessCheckResponse | Unary. Thăm dò tình trạng sẵn sàng (readiness). |
Ký hiệu thông điệp
Phần tiêu đề “Ký hiệu thông điệp”Các thông điệp yêu cầu và phản hồi là các ký hiệu cấu trúc của lược đồ. Các thông điệp render, RenderRequest, RenderResponse, và RenderChunk dạng streaming, mang theo kích thước trang, hướng, các thao tác có thứ tự, và byte PDF kết quả. Các thông điệp job, SubmitJobRequest, GetJobStatusRequest, GetJobResultRequest, CancelJobRequest, và JobResponse, mô hình hóa vòng đời job bất đồng bộ, với metadata job được giữ trong thông điệp JobData. Các thông điệp session, CreateSessionRequest, SessionResponse, GetSessionRequest, DestroySessionRequest, DestroySessionResponse, SessionOperationRequest, và SessionRenderRequest, mô hình hóa vòng đời session có trạng thái, với metadata session được giữ trong thông điệp SessionData. Các thông điệp capability, CapabilityRequest, CapabilityResponse, GetCapabilitiesRequest, và GetCapabilitiesResponse, mang theo điều phối thao tác được kiểm soát theo bậc và tra cứu nội tại. Các thông điệp hệ thống, HealthCheckRequest, HealthCheckResponse, ReadinessCheckRequest, và ReadinessCheckResponse, mang theo trạng thái sống và sẵn sàng.
Các tệp .proto được phân phối là hợp đồng wire chính thức; xem tài liệu tham chiếu gRPC transport trên gRPC transport.
Mô hình lỗi
Phần tiêu đề “Mô hình lỗi”Server báo cáo các thất bại bằng cơ chế lỗi gốc của từng transport. Mỗi transport giữ nguyên cùng một điều kiện logic; chỉ cách mã hóa khác nhau.
Lỗi MCP là các đối tượng lỗi JSON-RPC 2.0. Một phương thức không xác định trả về method-not-found (-32601); một thông điệp không phải JSON-RPC hợp lệ trả về invalid-request (-32600); đầu vào không thể phân tích trả về parse-error (-32700). Khi một tool thất bại, MCP trả về phản hồi JSON-RPC thành công nhưng nội dung đánh dấu lỗi, thay vì lỗi ở cấp transport, để agent có thể đọc thông điệp. Challenge xác nhận cho một tool ApprovalRequired cũng là phản hồi thành công, không phải lỗi.
REST dùng các mã trạng thái Hypertext Transfer Protocol (HTTP) với ngữ nghĩa được định nghĩa bởi RFC 9110. Một 200 mang theo kết quả; một 400 được trả về khi một trường của yêu cầu không qua được xác thực định dạng; một 401 được trả về khi không gửi API key hợp lệ và mang theo header challenge WWW-Authenticate: Bearer; một 403 được trả về khi bậc của một key hợp lệ không được phép thực hiện thao tác; một 404 được trả về khi một tuyến đường được kiểm soát theo bậc không được đăng ký vì gói của nó vắng mặt. Các thân lỗi máy có thể đọc được là tài liệu Problem Details theo RFC 9457, được phục vụ với kiểu media application/problem+json và một type Uniform Resource Identifier (URI) ổn định cho mỗi điều kiện. Các lỗi xác thực cấp trường được liệt kê trong thân. Như một biện pháp gia cố chống path-traversal, một document_id không khớp mẫu doc_[a-f0-9]{24} bị từ chối với 400 trước khi tool chạy. REST transport mô tả đường ống middleware REST và bảng tuyến đường.
gRPC dùng các mã trạng thái gRPC chuẩn. Token thiếu, sai định dạng, không xác định, bị vô hiệu hóa hoặc hết hạn sẽ khiến cuộc gọi thất bại với UNAUTHENTICATED thay vì một trạng thái HTTP. Chi tiết lỗi giàu ngữ cảnh phản ánh hình dạng Problem Details của REST và được mang theo trong status details của gRPC, nên type URI của lỗi nhất quán trên các transport.
Xem thêm RFC 9110 (HTTP Semantics) về ngữ nghĩa mã trạng thái và RFC 9457 (Problem Details for HTTP APIs) về định dạng thân lỗi.
- RFC 9110: https://www.rfc-editor.org/rfc/rfc9110
- RFC 9457: https://www.rfc-editor.org/rfc/rfc9457
Giới hạn tốc độ và hạn mức
Phần tiêu đề “Giới hạn tốc độ và hạn mức”Transport REST áp dụng giới hạn tốc độ theo từng địa chỉ Internet Protocol (IP) và theo từng client trong đường ống middleware của nó, cùng với giới hạn kích thước thân, giới hạn payload theo bậc và thời gian chờ trên mỗi yêu cầu. Những trần này là các giá trị cấu hình, không phải hằng số mã cứng:
- Các trần payload theo từng bậc (
corePayloadLimit,proPayloadLimit,enterprisePayloadLimit) cùng thời gian chờ tương ứng được áp dụng trên REST theo bậc của key đã xác thực. Xem Configuration. - Kho tài liệu trong bộ nhớ bị giới hạn bởi
max_documents(mặc định 50) vàdocument_ttl(mặc định 1800 giây). - Trạng thái giới hạn tốc độ và idempotency là theo từng worker, trừ khi
NEXTPDF_REDIS_HOSTđược cấu hình cho một kho dùng chung. Xem Deployment.
Khi các kho giới hạn tốc độ và idempotency được dùng chung, các lần gửi job bất đồng bộ giống hệt nhau khi lặp lại sẽ được khử trùng lặp theo idempotency_key. Transport MCP xử lý mỗi lần một yêu cầu qua các pipe và khử trùng lặp id yêu cầu lặp lại từ bộ đệm 64 mục thay vì áp dụng giới hạn tốc độ mạng.
Ghi chú phát triển
Phần tiêu đề “Ghi chú phát triển”- Đọc tên tool, lớp và bậc rủi ro từ mã nguồn trong
src/Tools/; đừng giả định một tổng số cố định. Truy vấn server đang chạy để lấy số lượng chính thức, như được trình bày trên Tool catalog. - Sinh lại các stub client gRPC từ các tệp
proto/nextpdf/connect/v1/*.protođược phân phối; gói và namespace lànextpdf.connect.v1. Đừng chỉnh tay các lớp thông điệp được sinh ra. - Một tool
ApprovalRequiredphản hồi bằng challenge xác nhận ở lần gọi đầu tiên. Hãy xây dựng luồng thử lại — chuyển challenge, rồi gọi lại với_confirmation_token— trước khi phát hành tích hợp điều khiểnoutput_pdfhoặc bất kỳ tool mutation nào. - Một tuyến đường hoặc capability được kiểm soát theo bậc mà chưa được cài không phải là một thất bại xác thực: REST trả về
404cho một tuyến đường vắng mặt, vàExecuteCapabilitycủa gRPC báo cáo thao tác là không khả dụng. Hãy coi việc thiếu bậc Pro hoặc Enterprise là hành vi vận hành đúng mong đợi, không phải lỗi. - Giữ API key ngoài kiểm soát mã nguồn; gắn chúng từ tệp secret và ưu tiên kho key tệp có thể hot-reload để việc xoay vòng không cần khởi động lại. Xem Security and operations.
Xem thêm
Phần tiêu đề “Xem thêm”- Developer guide — kiến trúc, vòng đời, điểm mở rộng, và checklist kiểm thử
- Tool catalog — tập tool cốt lõi đã kiểm chứng và số lượng tại thời điểm chạy
- HITL risk tiers — mô hình rủi ro và challenge xác nhận
- MCP transport · REST transport · gRPC transport — chi tiết wire theo từng transport
- Security and operations — xác thực, bảo mật transport, và mô hình mối đe dọa