NextPDF Connect — phương tiện truyền tải MCP

Tổng quan nhanh

Phương tiện truyền tải Model Context Protocol (MCP) chạy bin/nextpdf-mcp dưới dạng một tiến trình con cục bộ. Nó giao tiếp bằng JSON-RPC 2.0 qua đầu vào và đầu ra tiêu chuẩn. Máy chủ triển khai bản sửa đổi MCP được đánh phiên bản theo ngày 2025-06-18.

Cài đặt

composer require nextpdf/server

Tổng quan khái niệm

Trong mô hình stdio của MCP, ứng dụng khách khởi chạy máy chủ dưới dạng một tiến trình con. Ứng dụng khách trao đổi các thông điệp JSON-RPC được phân tách bằng ký tự xuống dòng: mỗi dòng là một thông điệp, không có ký tự xuống dòng bên trong, UTF-8. Máy chủ chỉ ghi các thông điệp MCP hợp lệ ra đầu ra tiêu chuẩn và gửi nhật ký đến lỗi tiêu chuẩn. Bản triển khai định tuyến trình ghi nhật ký kiểm toán đến lỗi tiêu chuẩn để các dòng nhật ký không bao giờ làm hỏng luồng giao thức. Đặc tả MCP chính thức, bản sửa đổi 2025-06-18, định nghĩa cách đóng khung này. Đặc tả đó không thuộc bộ ngữ liệu tiêu chuẩn được kiểm soát, nên được trích dẫn bằng URL: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports.

NextPDF Connect triển khai phương tiện truyền tải stdio. Đặc tả MCP cũng định nghĩa một phương tiện truyền tải Streamable HTTP. Đặc tả nêu rằng ứng dụng khách nên hỗ trợ stdio bất cứ khi nào có thể, và máy chủ có thể chỉ triển khai stdio. Để truy cập các công cụ này qua mạng, hãy dùng phương tiện truyền tải REST hoặc gRPC; xem /transports/rest/ và /transports/grpc/.

Bề mặt API

Phương thức

Phương thức	Hành vi
`initialize`	Trả về phiên bản giao thức, các khả năng và thông tin máy chủ
`notifications/initialized`	Một thông báo (không có `id`); được chấp nhận mà không có phản hồi
`tools/list`	Liệt kê các công cụ đã đăng ký với bộ lọc `params.category` tùy chọn
`tools/call`	Thực thi một công cụ theo `params.name` với `params.arguments`

Mọi phương thức khác trả về method-not-found (-32601). Thông điệp không phải JSON-RPC 2.0 hợp lệ sẽ trả về invalid-request (-32600); đầu vào không phân tích cú pháp được sẽ trả về parse-error (-32700). id yêu cầu bị trùng lặp sẽ trả về phản hồi trước đó được lưu trong bộ đệm 64 mục mà không thực thi lại.

Phản hồi initialize

Kết quả initialize trả về protocolVersion 2025-06-18, serverInfo.name: NextPDF Connect và một đối tượng capabilities. Ngoài khả năng tools tiêu chuẩn, máy chủ còn bổ sung một khối capabilities.nextpdf:

tiers — số lượng công cụ đã đăng ký theo thời gian thực, phân theo bậc (core / pro / enterprise).
tool_count — tổng số công cụ đã đăng ký, tính tại thời điểm chạy.
risk_model_version — phiên bản mô hình rủi ro mà máy chủ thực thi.
hitl_enabled — true; cổng xác nhận đang hoạt động.

tool_count là con số chính thức cho lần triển khai này. Đây là số đếm tại thời điểm chạy, không phải hằng số được ghi trong tài liệu; xem /connect/tool-catalog/.

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

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"client","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
EOF

Mã mẫu — môi trường sản xuất

Bộ lọc danh mục thu hẹp danh mục công cụ theo một miền:

./vendor/bin/nextpdf-mcp --config=/etc/nextpdf/nextpdf-mcp.yaml <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"client","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{"category":"diagnostic"}}
EOF

Giá trị danh mục lấy từ danh mục được khai báo của từng công cụ (ví dụ document, diagnostic).

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

Không có khóa API. Phương tiện truyền tải stdio không có trình lắng nghe mạng và không có bearer token. Hãy coi ranh giới tiến trình của hệ điều hành là ranh giới tin cậy, theo mô hình stdio của MCP. Đừng bắc cầu nó ra mạng.
Các yêu cầu xác nhận diễn ra trong luồng (in-band). Một công cụ ApprovalRequired trả về một phản hồi JSON-RPC thành công. Nội dung phản hồi là văn bản yêu cầu xác nhận và một token dùng một lần, không phải lỗi. Xem /connect/hitl-risk-tiers/.
Thông báo diễn ra im lặng. Một thông điệp không có id sẽ không tạo ra phản hồi. Quá trình bắt tay là initialize (có id), sau đó là thông báo initialized, rồi đến các lệnh gọi có id.

Hiệu năng

Máy chủ MCP chạy như một tiến trình duy nhất và xử lý từng yêu cầu một qua các pipe. Không có vòng truyền qua mạng; độ trễ chủ yếu do thao tác của engine bên dưới quyết định.

Lưu ý bảo mật

Phương tiện truyền tải kế thừa mức độ tin cậy của ứng dụng khách đã khởi chạy nó. Hãy giữ tiến trình con ở cục bộ. Các công cụ rủi ro cao vẫn yêu cầu con người xác nhận ngay cả khi không có khóa API. Xem /connect/security-and-operations/.

Tuân thủ

Cách đóng khung stdio và hành vi initialize/lifecycle tuân thủ đặc tả Model Context Protocol chính thức, bản sửa đổi 2025-06-18:

Phương tiện truyền tải: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports
Vòng đời: https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle

Đặc tả MCP không thuộc bộ ngữ liệu tiêu chuẩn được kiểm soát, nên không có reference_id; các URL chính thức ở trên là trích dẫn chính thức.

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

tools/list chỉ trả về các công cụ Pro và Enterprise khi nextpdf/premium được cài đặt cùng với máy chủ. Bản thân phương tiện truyền tải vẫn như nhau bất kể các bậc đã cài đặt.

Xem thêm

/connect/quickstart/ — quá trình bắt tay có thể chạy được
/connect/tool-catalog/ — tools/list trả về gì và vì sao số lượng có thể khác nhau
/connect/hitl-risk-tiers/ — định dạng yêu cầu xác nhận
/transports/rest/ · /transports/grpc/ — các lựa chọn thay thế qua mạng
/connect/migrating-to-multi-transport/ — chuyển một tích hợp chỉ dùng MCP sang REST/gRPC