Bắt đầu nhanh với NextPDF Connect

Tổng quan nhanh

Trang này thực hiện phiên trao đổi hữu ích tối thiểu cho cả hai phương thức truyền tải: Model Context Protocol (MCP) và Representational State Transfer (REST). Mỗi yêu cầu dùng đúng định dạng thông điệp mà máy chủ triển khai. Bạn không cần bộ công cụ phát triển phần mềm (SDK).

Cài đặt

composer require nextpdf/server

Tổng quan khái niệm

Phương thức truyền tải MCP dùng JSON-RPC 2.0 qua đầu vào và đầu ra chuẩn. Bạn phải gửi chuỗi này theo đúng thứ tự. Trước tiên, hãy gửi initialize. Tiếp theo, gửi xác nhận notifications/initialized. Sau đó, gửi tools/list và tools/call. Máy chủ đọc mỗi dòng dưới dạng một thông điệp JSON. Mỗi dòng phải kết thúc bằng một ký tự xuống dòng. Máy chủ ghi mỗi phản hồi trên một dòng.

Phương thức truyền tải REST cung cấp cùng các năng lực của engine dưới dạng các thao tác Hypertext Transfer Protocol (HTTP). Một lần kết xuất phi trạng thái đơn lẻ là một POST /api/v1/render với một mảng operations có thứ tự. Phần thân phản hồi chính là tệp Portable Document Format (PDF).

Mẫu mã — bắt đầu nhanh (MCP qua stdio)

Khởi động máy chủ và truyền phiên bắt tay vào đó. Ba yêu cầu này dùng các tên phương thức đã được xác minh mà trình xử lý giao thức sẽ định tuyến:

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

Phản hồi initialize cho biết phiên bản giao thức 2025-06-18, tên máy chủ NextPDF Connect, và một khối capabilities.nextpdf. Khối đó bao gồm số lượng theo từng cấp đang hoạt động, tool_count tại thời gian chạy, phiên bản mô hình rủi ro, và hitl_enabled: true. Phản hồi tools/list liệt kê chính xác các công cụ đã đăng ký cho bản cài đặt này. Dòng thông báo được thiết kế để không tạo ra phản hồi nào.

Bây giờ, hãy gọi một công cụ an toàn. Công cụ diagnostic.doctor chạy một kiểm tra môi trường chỉ đọc. Công cụ này không cần tài liệu hay xác nhận:

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

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

Khởi động máy chủ REST, rồi kết xuất một PDF bằng một lệnh. Máy chủ yêu cầu một khóa giao diện lập trình ứng dụng (API) trên mọi endpoint không phải kiểm tra tình trạng, vì vậy trước tiên hãy định nghĩa một khóa:

export NEXTPDF_API_KEYS='npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef:demo:core:default'
./vendor/bin/rr serve -c .rr.yaml

Trong một shell thứ hai, hãy gửi một yêu cầu kết xuất. Phần thân là một RenderRequest. Yêu cầu đó chứa một mảng operations có thứ tự gồm các thao tác được định kiểu.

curl -sS -X POST http://localhost:8080/api/v1/render \
  -H 'Authorization: Bearer npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef' \
  -H 'Content-Type: application/json' \
  -d '{
        "page_size": "A4",
        "orientation": "portrait",
        "operations": [
          { "type": "add_text", "text": "Hello from NextPDF Connect" }
        ]
      }' \
  --output hello.pdf

Phần thân phản hồi 200 chính là PDF (Content-Type: application/pdf) được ghi vào hello.pdf. Các phép thăm dò tình trạng không cần khóa:

curl -sS http://localhost:8080/healthz

Các trường hợp đặc biệt và điểm cần lưu ý

Thứ tự bắt tay rất quan trọng. Trình xử lý giao thức coi một thông điệp không có id là một thông báo và không trả về gì. Hãy gửi initialize kèm một id, rồi đến thông báo initialized, rồi đến các yêu cầu có chứa một id.
Một id yêu cầu bị lặp lại sẽ được khử trùng lặp. Trình xử lý lưu các phản hồi gần đây vào một bộ đệm vòng 64 mục. Khi gặp một id trùng lặp, nó trả về phản hồi đã lưu trong bộ đệm mà không chạy lại công cụ. Hãy dùng id mới.
Một công cụ rủi ro cao trả lời bằng một thử thách, chứ không phải một kết quả. Việc gọi output_pdf với một file_path trả về một thử thách xác nhận thay vì thực thi. Hãy gọi lại công cụ với _confirmation_token đã được cấp. Chế độ xuất base64, không có file_path, không yêu cầu xác nhận. Xem /connect/hitl-risk-tiers/.
Một yêu cầu REST không được ủy quyền sẽ nhận 401. Một header Authorization: Bearer bị thiếu hoặc sai định dạng sẽ trả về một phần thân problem-details kèm một header WWW-Authenticate: Bearer. Các phép thăm dò /healthz và /readyz là các endpoint ẩn danh duy nhất.

Hiệu năng

Cả hai lộ trình bắt đầu nhanh đều dùng một yêu cầu duy nhất. Lộ trình REST còn phải chịu chi phí khởi động nguội của nhóm worker RoadRunner ở yêu cầu đầu tiên sau rr serve. Các yêu cầu sau đó sẽ tái sử dụng các worker đã khởi động sẵn.

Lưu ý về bảo mật

Khóa npk_live_ ở trên là một giá trị minh họa dùng một lần rồi bỏ. Hãy tạo các khóa thật với đủ entropy, lưu trữ chúng bên ngoài hệ thống quản lý mã nguồn, và ưu tiên kho khóa dựa trên tệp để xoay vòng khóa. Phương thức truyền tải MCP qua stdio không có khóa API vì đó là một tiến trình con cục bộ được client khởi chạy nó tin cậy theo mô hình truyền tải MCP. Xem /connect/security-and-operations/.

Tuân thủ

Các định dạng thông điệp được trình bày khớp với bản sửa đổi MCP đã triển khai 2025-06-18 và hợp đồng REST OpenAPI 3.1. Các trích dẫn quy chuẩn về giao thức và xác thực được ghim tại /transports/mcp/, /transports/rest/, và /connect/security-and-operations/.

Xem thêm

/transports/mcp/ — tài liệu tham khảo đầy đủ về phương thức truyền tải MCP
/transports/rest/ — tài liệu tham khảo đầy đủ về phương thức truyền tải REST và bản kết xuất OpenAPI
/connect/tool-catalog/ — các công cụ mà tools/list trả về và lý do
/connect/hitl-risk-tiers/ — hình dạng của một thử thách xác nhận
/connect/configuration/ — giới hạn danh mục và tinh chỉnh máy chủ