Danh mục công cụ NextPDF Connect

Tổng quan nhanh

NextPDF Connect không cung cấp số lượng công cụ cố định. Máy chủ tính con số này trong thời gian chạy dựa trên các gói đã cài đặt, allowlist cấu hình và các cổng môi trường. Trang này ghi lại bộ công cụ core đã được kiểm chứng và cách xác định tổng số.

Cài đặt

composer require nextpdf/server

Tổng quan khái niệm

NextPDF\Server\ToolRegistry xây dựng danh mục khi khởi động theo thứ tự sau:

Tầng core. Một bộ công cụ core cố định luôn được đăng ký mà không cần điều kiện. Hai công cụ khác chỉ được đăng ký khi đáp ứng điều kiện tiên quyết.
Tầng Pro. Các công cụ Pro đăng ký khi lớp provider Pro phân giải được, điều này xảy ra khi nextpdf/premium được cài đặt. Máy chủ lặng lẽ bỏ qua bước này khi lớp đó không phân giải được.
Tầng Enterprise. Provider Enterprise theo cùng mô hình với provider Pro.
Các tầng mở rộng đi kèm. Các provider công cụ AST và mutation đi kèm với gói máy chủ và được đăng ký ở tầng Pro. Mỗi provider do một cổng môi trường kiểm soát và suy giảm nhẹ nhàng khi thiếu phần hỗ trợ core nền tảng tương ứng.
Bộ lọc chính sách bảo mật. Máy chủ áp dụng allowlist enabled_tools cho từng đăng ký. Allowlist không rỗng sẽ loại bỏ mọi công cụ không có trong danh sách. Bộ đếm theo tầng chỉ bao gồm các công cụ mà chính sách cho phép.

Phản hồi initialize của Model Context Protocol (MCP) báo cáo tool_count thu được và số lượng theo từng tầng cho máy chủ đang chạy. Giá trị đó là nguồn có thẩm quyền. Hãy xem mọi tổng số cố định được ghi trong văn bản là đã lỗi thời.

Bề mặt API

Các công cụ core đã được kiểm chứng luôn sẵn dùng

Mười hai công cụ này luôn được đăng ký trong tầng core. Máy chủ đọc mức rủi ro và gợi ý hành vi MCP của từng công cụ từ phần triển khai của công cụ đó.

Tên công cụ	Danh mục	Mô tả	Rủi ro
`create_pdf`	document	Tạo tài liệu PDF và trả về một `document_id`	caution
`add_text`	document	Thêm nội dung văn bản vào tài liệu PDF	caution
`add_image`	document	Thêm hình ảnh từ đường dẫn tệp hoặc dữ liệu base64	caution
`add_table`	document	Thêm bảng HTML vào tài liệu PDF	caution
`set_font`	document	Đặt phông chữ cho các thao tác văn bản tiếp theo	caution
`add_page`	document	Thêm trang mới vào tài liệu PDF	caution
`output_pdf`	document	Hoàn tất PDF dưới dạng tệp hoặc base64	approval_required
`preview_layout`	document	Trả về bản tóm tắt bố cục JSON mà không kết xuất	safe
`diagnostic.doctor`	diagnostic	Chạy kiểm tra tình trạng; cung cấp chẩn đoán môi trường có cấu trúc	safe
`diagnostic.capabilities`	diagnostic	Liệt kê các khả năng cùng tầng và trạng thái	safe
`diagnostic.inspect`	diagnostic	Kiểm tra PDF và trả về siêu dữ liệu cấu trúc	safe
`diagnostic.verify`	diagnostic	Xác minh tính toàn vẹn của PDF, kèm tùy chọn kiểm tra PDF/A hoặc PDF/UA	caution

Các công cụ core đăng ký có điều kiện

Tên công cụ	Điều kiện
`generate_barcode`	Đăng ký khi bản `nextpdf/core` đã cài đặt bao gồm registry bộ mã hóa barcode core
`parse_pdf`	Chỉ được đăng ký khi `NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED` là `true` hoặc `1`

output_pdf là công cụ core duy nhất có mức rủi ro approval_required. Thao tác ghi tệp sẽ đi qua cổng human-in-the-loop; kết quả base64 thì không. Xem /connect/hitl-risk-tiers/.

Các công cụ chỉ được thêm vào khi cài đặt các gói bổ sung

Máy chủ phát hiện các lớp provider bằng class_exists():

Các công cụ Pro đăng ký khi nextpdf/premium được cài đặt và provider Pro có thể phân giải.
Các công cụ Enterprise đăng ký khi nextpdf/premium được cài đặt và provider Enterprise có thể phân giải. Các công cụ về quyền riêng tư (redaction, de-identification, zone redaction) bao bọc các lớp Enterprise. Chúng chỉ đăng ký dưới tầng Enterprise khi các lớp đó có thể autoload.
Các công cụ AST và mutation đi kèm với máy chủ và được đăng ký ở tầng Pro. Các cổng NEXTPDF_AST_TOOLS_ENABLED và NEXTPDF_MUTATION_TOOLS_ENABLED kiểm soát chúng; cả hai cổng đều được bật theo mặc định.

Chính gói Premium, không phải máy chủ, định nghĩa danh sách công cụ Pro và Enterprise chính xác và cung cấp tài liệu cho chúng trong chính gói đó. Hợp đồng của máy chủ nằm ở cơ chế đăng ký, không phải một danh sách Premium cố định.

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

In các công cụ mà bản cài đặt này cung cấp mà không cần khởi động máy chủ:

./vendor/bin/generate-skills --dry-run --list-tools

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

Truy vấn máy chủ đang chạy để lấy số lượng có thẩm quyền qua MCP:

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

Máy chủ tính capabilities.nextpdf.tool_count và tiers trong kết quả initialize của tiến trình đang chạy. Qua REST, GET /api/v1/capabilities trả về thông tin tự kiểm tra tương đương.

Các trường hợp ngoại lệ và lưu ý

Không có con số cố định “33 công cụ” — hay bất kỳ tổng số cố định nào. Tài liệu cũ từng trích dẫn một con số duy nhất, nhưng đó không phải là cam kết. Số lượng thay đổi theo các gói đã cài đặt, allowlist enabled_tools và các cổng môi trường parse_pdf, AST và mutation. Hãy luôn đọc giá trị này từ máy chủ đang chạy.
Allowlist chỉ trừ bớt, không bao giờ thêm vào. Liệt kê một công cụ Pro trong enabled_tools sẽ không đăng ký công cụ đó khi thiếu nextpdf/premium.
Việc thiếu một tầng diễn ra âm thầm và là điều dự kiến. Một bản cài đặt chỉ dùng mã nguồn mở cung cấp bộ công cụ core và báo cáo không có công cụ Pro nào, cũng không có công cụ Enterprise nào. Đó là hành vi đúng, không phải lỗi.
Tầng trong danh mục là bất biến được khai báo. Mỗi công cụ tự khai báo tầng và rủi ro của nó trong mã. Registry không bao giờ suy ra tầng từ namespace hay gói.

Hiệu năng

Các thao tác quét registry và phát hiện tầng chỉ chạy một lần khi khởi động. performance_budget của trang đặt giới hạn cho các thao tác đó. Chi phí cho mỗi công cụ đến từ thao tác của engine nền tảng, không phải từ việc tra cứu danh mục, vốn là O(1) theo tên công cụ.

Ghi chú về bảo mật

Hãy dùng enabled_tools như biện pháp kiểm soát đặc quyền tối thiểu: chỉ cung cấp những công cụ mà một tích hợp cần. Danh mục không bao giờ bao gồm công cụ bị chính sách bảo mật từ chối, và bộ đếm theo tầng chỉ phản ánh các công cụ được cho phép. Các công cụ rủi ro cao vẫn chịu sự kiểm soát bằng xác nhận của con người, bất kể có xuất hiện trong danh mục hay không. Xem /connect/security-and-operations/.

Tuân thủ

Trang này mô tả cơ chế registry. Các trích dẫn giao thức cho bề mặt tools/list và initialize được ghim tại /transports/mcp/. Mô hình rủi ro được quy định tại /connect/hitl-risk-tiers/.

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

Danh mục core bao gồm tạo, kiểm tra và chẩn đoán. Các công cụ ký, redaction, tuân thủ và forensic chỉ xuất hiện khi nextpdf/premium được cài đặt cùng máy chủ. Ranh giới đóng gói này được áp dụng tại thời điểm composer require, không bao giờ thông qua lời nhắc trong thời gian chạy.

Xem thêm

/connect/hitl-risk-tiers/ — ý nghĩa của cột rủi ro và cách cơ chế thực thi hoạt động
/connect/boot-and-discovery/ — toàn bộ trình tự khởi động và khám phá
/connect/configuration/ — enabled_tools và các cổng môi trường
/transports/mcp/ — tools/list và initialize trong các định dạng truyền dữ liệu
/connect/overview/ — vì sao danh mục được thiết kế để phụ thuộc vào thời gian chạy