Tổng quan về máy chủ NextPDF Connect

Tổng quan nhanh

NextPDF Connect là gói nextpdf/server: một dịch vụ chạy lâu dài, đưa engine PDF 2.0 của NextPDF đến các AI agent và client HTTP. Dịch vụ hỗ trợ ba giao thức truyền tải: Model Context Protocol (MCP) qua stdio, API REST và gRPC. Cả ba giao thức truyền tải đều dùng chung một sổ đăng ký công cụ và một cổng xác nhận có con người tham gia (HITL).

Cài đặt

composer require nextpdf/server

Ràng buộc Composer là nextpdf/core: ^3.0 với php: >=8.4 <9.0. Để biết quy trình đầy đủ, xem /connect/install/. Trang đó cũng nêu hai thành phần bổ sung tùy chọn: tiện ích mở rộng ext-redis và gói nextpdf/premium.

Tổng quan khái niệm

nextpdf/server chuyển phần lõi NextPDF độc lập với framework thành một bề mặt dịch vụ. Gói này không xây dựng lại phần tạo PDF. Thay vào đó, nó bọc từng khả năng của engine thành một công cụ có tên và schema riêng, rồi cung cấp danh mục đó qua nhiều giao thức truyền tải.

Ba khái niệm chi phối toàn bộ thiết kế:

Sổ đăng ký công cụ. NextPDF\Server\ToolRegistry phát hiện và đăng ký các công cụ khi khởi động. Một tập lõi đi kèm với gói và luôn có sẵn. Các provider Pro và Enterprise đăng ký thêm công cụ, nhưng chỉ khi các gói tương ứng đã được cài đặt. Số lượng công cụ được cung cấp là một thuộc tính lúc chạy của bản triển khai, không phải một hằng số cố định. Xem /connect/tool-catalog/.
Các giao thức truyền tải. Cùng một sổ đăng ký được cung cấp theo ba cách. MCP chạy qua stdio cho các AI client cục bộ. REST chạy qua pipeline middleware PSR-15 trên một nhóm worker RoadRunner cho các client trên mạng. gRPC chạy trên một worker gRPC Spiral RoadRunner cho các client có định nghĩa kiểu và truyền theo luồng. Mỗi giao thức truyền tải là một tiến trình riêng, có điểm vào riêng. Xem /transports/mcp/, /transports/rest/ và /transports/grpc/.
Cổng xác nhận. Mỗi công cụ khai báo một mức rủi ro. Công cụ ở mức cao nhất yêu cầu con người xác nhận rõ ràng trước khi chạy. Cổng phát hành một token thử thách dùng một lần. Agent phải chuyển token đó cho con người, rồi gọi lại công cụ kèm token. Xem /connect/hitl-risk-tiers/.

Sơ đồ dưới đây cho thấy cách một sổ đăng ký phục vụ ba giao thức truyền tải. Nó cũng chỉ ra vị trí của cổng xác nhận trên đường đi của yêu cầu.

NextPDF Connect component architecture

Gói này được cấp phép theo Apache-2.0, khớp với nextpdf/core. Phiên bản giao thức MCP được triển khai là bản chỉnh sửa 2025-06-18, được đánh phiên bản theo ngày. Tài liệu OpenAPI 3.1 mô tả bề mặt REST. Gói Protocol Buffers nextpdf.connect.v1 mô tả bề mặt gRPC.

Bề mặt API

Ba lớp máy chủ là các điểm vào công khai. Mỗi lớp có một trình bao bọc giao diện dòng lệnh (CLI):

Điểm vào	Lớp	Giao thức truyền tải
`bin/nextpdf-mcp`	`NextPDF\Server\Mcp\McpServer`	MCP qua stdio
`bin/nextpdf-server`	`NextPDF\Server\Http\HttpServer`	REST qua RoadRunner HTTP
`bin/nextpdf-grpc`	`NextPDF\Server\Grpc\GrpcServer`	gRPC qua RoadRunner gRPC
`bin/generate-skills`	`NextPDF\Server\Skills\SkillsDumper`	Xuất danh mục công cụ

McpServer::create(), HttpServer::create() và GrpcServer::create() đều dựng một máy chủ được cấu hình đầy đủ từ môi trường và cấu hình đầu vào. Sổ đăng ký, kho lưu trữ tài liệu, chính sách bảo mật và cổng xác nhận là các khái niệm dùng chung trên cả ba máy chủ.

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

Máy chủ MCP tối thiểu chỉ cần một lệnh; bạn không phải viết mã PHP kết nối nào:

./vendor/bin/nextpdf-mcp

Máy chủ đọc các yêu cầu JSON-RPC từ đầu vào chuẩn và ghi phản hồi ra đầu ra chuẩn. Để xem một phiên trao đổi initialize và tools/list chạy được cùng yêu cầu REST tương ứng, xem /connect/quickstart/.

Trường hợp đặc biệt và điều cần lưu ý

Số lượng công cụ không phải là 33 hay bất kỳ con số cố định nào khác. Máy chủ đếm các công cụ lúc chạy bằng count(ToolRegistry::all()), sau khi lọc theo chính sách và phát hiện cấp. Bất kỳ tài liệu nào nêu một tổng số cố định đều đã lỗi thời. Để lấy số lượng có thẩm quyền, hãy truy vấn máy chủ đang chạy. Dùng phản hồi initialize của MCP hoặc endpoint REST /api/v1/capabilities.

Số lượng công cụ được cung cấp phụ thuộc vào các gói đã cài đặt và chính sách đang hoạt động. Hãy đọc giá trị này từ máy chủ đang chạy tại thời điểm chạy. Một con số cố định trong mã hoặc tài liệu của bạn sẽ trở nên lỗi thời.
Việc thiếu một gói Pro hoặc Enterprise không phải là lỗi. Sổ đăng ký kiểm tra các lớp provider bằng class_exists(), rồi lặng lẽ bỏ qua bất kỳ cấp nào không có mặt. Một bản triển khai chỉ dùng mã nguồn mở vẫn khởi động và phục vụ danh mục lõi bình thường.
Ba giao thức truyền tải không dùng chung một tiến trình. Chạy máy chủ MCP không khởi động máy chủ REST hay máy chủ gRPC. Điều ngược lại cũng đúng. Một bản triển khai kết hợp chạy trình giám sát RoadRunner với cấu hình khởi động cả hai nhóm worker: nhóm HTTP và nhóm gRPC. Xem /connect/deployment/.

Hiệu năng

Mỗi giao thức truyền tải dựa trên worker. Một worker xử lý một yêu cầu tại một thời điểm. Các máy chủ REST và gRPC chạy trên các nhóm worker RoadRunner; cấu hình quyết định kích thước nhóm. Mặc định là bốn worker HTTP. Trình giám sát RoadRunner giới hạn bộ nhớ của từng worker. Phần frontmatter performance_budget trên trang này mô tả một khung ngân sách cho khởi động nguội và khám phá. Nó không phải là mục tiêu cho từng yêu cầu. Thao tác engine bên dưới chi phối phần lớn chi phí của một yêu cầu.

Lưu ý bảo mật

Mọi giao thức truyền tải trên mạng đều xác thực bằng token bearer đóng vai trò là khóa giao diện lập trình ứng dụng (API). Giao thức truyền tải MCP qua stdio là một tiến trình con cục bộ do client đáng tin cậy khởi chạy, theo mô hình truyền tải của MCP. Các công cụ rủi ro cao luôn được đặt sau bước xác nhận của con người trên mọi giao thức truyền tải. Để biết toàn bộ mô hình mối đe dọa, mô hình xác thực và cấu hình bảo mật truyền tải, xem /connect/security-and-operations/.

Tính tuân thủ

Trang này chỉ đưa ra các tuyên bố về kiến trúc. Các trích dẫn quy phạm về giao thức và bảo mật được ghim trên những trang quy định hành vi đó: /connect/security-and-operations/, /transports/mcp/, /transports/rest/ và /transports/grpc/. Tài liệu tham chiếu vòng đời MCP là đặc tả chính thức tại modelcontextprotocol.io (bản chỉnh sửa 2025-06-18). Các trang giao thức truyền tải ghi lại tham chiếu đó kèm URL, vì đặc tả MCP không thuộc kho tiêu chuẩn được kiểm soát.

Bối cảnh thương mại

Danh mục lõi đã đủ cho việc tạo, kiểm tra và chẩn đoán tài liệu. Các công cụ ký, biên tập che, chứng nhận tuân thủ và phân tích pháp y chỉ xuất hiện khi nextpdf/premium được cài đặt cùng với máy chủ. Đây là ranh giới đóng gói, không phải lời mời nâng cấp lúc chạy. Máy chủ không bao giờ phát ra nội dung tiếp thị.

Xem thêm

/connect/install/ — cài đặt và các gói tùy chọn
/connect/quickstart/ — phiên trao đổi MCP và yêu cầu REST đầu tiên chạy được
/connect/tool-catalog/ — tập công cụ lõi đã xác minh và cách số lượng phụ thuộc vào lúc chạy
/connect/hitl-risk-tiers/ — cổng xác nhận và mô hình rủi ro
/transports/mcp/, /transports/rest/, /transports/grpc/ — thiết lập theo từng giao thức truyền tải
/connect/security-and-operations/ — xác thực, bảo mật truyền tải, mô hình mối đe dọa
/connect/deployment/ — RoadRunner, Docker và triển khai truyền tải kết hợp