แค็ตตาล็อกเครื่องมือ NextPDF Connect

โดยสรุป

NextPDF Connect ไม่ได้เปิดเผยจำนวนเครื่องมือแบบตายตัว เซิร์ฟเวอร์คำนวณจำนวนดังกล่าวขณะรันไทม์จากแพ็กเกจที่ติดตั้ง รายการที่อนุญาตในการกำหนดค่า และเกตสภาพแวดล้อม หน้านี้บันทึกชุดเครื่องมือหลักที่ได้รับการตรวจสอบยืนยันและวิธีที่ใช้กำหนดจำนวนรวม

การติดตั้ง

composer require nextpdf/server

ภาพรวมเชิงแนวคิด

NextPDF\Server\ToolRegistry สร้างแค็ตตาล็อกระหว่างการบูตตามลำดับนี้:

1. ระดับ Core ชุดเครื่องมือหลักแบบตายตัวจะลงทะเบียนโดยไม่มีเงื่อนไข เครื่องมืออีกสองรายการจะลงทะเบียนเฉพาะเมื่อเงื่อนไขเบื้องต้นเป็นจริงเท่านั้น
2. ระดับ Pro เครื่องมือ Pro จะลงทะเบียนเมื่อรีโซลฟ์คลาสผู้ให้บริการ Pro ได้ ซึ่งจะเกิดขึ้นเมื่อมีการติดตั้ง nextpdf/premium เซิร์ฟเวอร์จะข้ามขั้นตอนนี้โดยไม่แจ้งเตือนเมื่อรีโซลฟ์คลาสไม่ได้
3. ระดับ Enterprise ผู้ให้บริการ Enterprise ใช้รูปแบบเดียวกับผู้ให้บริการ Pro
4. ระดับส่วนขยายที่มาพร้อมแพ็กเกจ ผู้ให้บริการเครื่องมือ AST และ mutation มาพร้อมกับแพ็กเกจเซิร์ฟเวอร์และลงทะเบียนภายใต้ระดับ Pro เกตสภาพแวดล้อมควบคุมผู้ให้บริการแต่ละราย และผู้ให้บริการแต่ละรายจะลดความสามารถลงอย่างนุ่มนวลเมื่อไม่มีการรองรับจาก core พื้นฐาน
5. ตัวกรองตามนโยบายความปลอดภัย เซิร์ฟเวอร์นำการลงทะเบียนแต่ละรายการมาเทียบกับรายการที่อนุญาต enabled_tools รายการที่อนุญาตซึ่งไม่ว่างจะตัดเครื่องมือใดก็ตามที่ไม่อยู่ในรายการออก ตัวนับของแต่ละระดับจะรวมเฉพาะเครื่องมือที่นโยบายอนุญาตเท่านั้น

การตอบกลับ initialize ของ Model Context Protocol (MCP) จะรายงาน tool_count ที่ได้และจำนวนแยกตามแต่ละระดับสำหรับเซิร์ฟเวอร์ที่กำลังทำงาน ค่าดังกล่าวคือแหล่งอ้างอิงจริงที่เชื่อถือได้ หากพบจำนวนรวมแบบตายตัวในเนื้อความ ให้ถือว่าเป็นข้อมูลล้าสมัย

พื้นผิว API

เครื่องมือหลักที่ได้รับการตรวจสอบยืนยันและพร้อมใช้งานเสมอ

เครื่องมือทั้งสิบสองรายการนี้ลงทะเบียนในระดับ core เสมอ เซิร์ฟเวอร์อ่านระดับความเสี่ยงและคำใบ้พฤติกรรม MCP ของแต่ละเครื่องมือจากการนำเครื่องมือนั้นไปใช้งาน

ชื่อเครื่องมือ	หมวดหมู่	คำอธิบาย	ความเสี่ยง
create_pdf	document	สร้างเอกสาร PDF และคืนค่า document_id	caution
add_text	document	เพิ่มเนื้อหาข้อความลงในเอกสาร PDF	caution
add_image	document	เพิ่มรูปภาพจากพาธไฟล์หรือข้อมูล base64	caution
add_table	document	เพิ่มตาราง HTML ลงในเอกสาร PDF	caution
set_font	document	ตั้งค่าฟอนต์สำหรับการดำเนินการกับข้อความที่ตามมา	caution
add_page	document	เพิ่มหน้าใหม่ลงในเอกสาร PDF	caution
output_pdf	document	สรุป PDF ขั้นสุดท้ายเป็นไฟล์หรือ base64	approval_required
preview_layout	document	คืนค่าสรุปเค้าโครงในรูปแบบ JSON โดยไม่เรนเดอร์	safe
diagnostic.doctor	diagnostic	เรียกใช้การตรวจสอบสภาพและข้อมูลวินิจฉัยสภาพแวดล้อมแบบมีโครงสร้าง	safe
diagnostic.capabilities	diagnostic	แสดงรายการความสามารถพร้อมระดับและสถานะ	safe
diagnostic.inspect	diagnostic	ตรวจสอบ PDF และคืนค่าเมตาดาตาเชิงโครงสร้าง	safe
diagnostic.verify	diagnostic	ตรวจสอบความสมบูรณ์ของ PDF พร้อมการตรวจสอบ PDF/A หรือ PDF/UA ที่เลือกได้	caution

เครื่องมือหลักที่ลงทะเบียนตามเงื่อนไข

ชื่อเครื่องมือ	เงื่อนไข
generate_barcode	ลงทะเบียนเมื่อ nextpdf/core ที่ติดตั้งมีรีจิสทรีตัวเข้ารหัสบาร์โค้ดของ core
parse_pdf	ลงทะเบียนเฉพาะเมื่อ NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED มีค่าเป็น true หรือ 1

output_pdf เป็นเครื่องมือหลักเพียงรายการเดียวที่อยู่ในระดับความเสี่ยง approval_required การเขียนไฟล์ต้องผ่านเกต human-in-the-loop ส่วนเอาต์พุต base64 จะไม่ผ่านเกตดังกล่าว ดู /connect/hitl-risk-tiers/

เครื่องมือที่เพิ่มเข้ามาเฉพาะเมื่อมีการติดตั้งแพ็กเกจเพิ่มเติม

เซิร์ฟเวอร์ตรวจสอบคลาสผู้ให้บริการด้วย class_exists():

• เครื่องมือ Pro ลงทะเบียนเมื่อมีการติดตั้ง nextpdf/premium และรีโซลฟ์ผู้ให้บริการ Pro ได้
• เครื่องมือ Enterprise ลงทะเบียนเมื่อมีการติดตั้ง nextpdf/premium และรีโซลฟ์ผู้ให้บริการ Enterprise ได้ เครื่องมือด้านความเป็นส่วนตัว (การลบข้อมูล การถอดข้อมูลระบุตัวตน การลบข้อมูลตามโซน) ครอบคลาส Enterprise ไว้ เครื่องมือเหล่านี้จะลงทะเบียนภายใต้ระดับ Enterprise เฉพาะเมื่อคลาสดังกล่าวสามารถออโตโหลดได้เท่านั้น
• เครื่องมือ AST และ mutation มาพร้อมกับเซิร์ฟเวอร์และลงทะเบียนภายใต้ระดับ Pro เกต NEXTPDF_AST_TOOLS_ENABLED และ NEXTPDF_MUTATION_TOOLS_ENABLED ควบคุมเครื่องมือเหล่านี้ และเกตทั้งสองเปิดใช้งานโดยค่าเริ่มต้น

แพ็กเกจ Premium ไม่ใช่เซิร์ฟเวอร์ คือผู้กำหนดรายการเครื่องมือ Pro และ Enterprise ที่แน่นอน และจัดทำเอกสารรายการดังกล่าวไว้พร้อมกับแพ็กเกจนั้น สัญญาของเซิร์ฟเวอร์คือกลไกการลงทะเบียน ไม่ใช่รายการ Premium แบบตายตัว

ตัวอย่างโค้ด — เริ่มต้นใช้งานอย่างรวดเร็ว

แสดงรายการเครื่องมือที่การติดตั้ง นี้ เปิดเผยโดยไม่ต้องเริ่มเซิร์ฟเวอร์:

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

ตัวอย่างโค้ด — การใช้งานจริง

สอบถามจำนวนจริงที่เชื่อถือได้จากเซิร์ฟเวอร์ที่กำลังทำงานผ่าน 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

เซิร์ฟเวอร์คำนวณ capabilities.nextpdf.tool_count และ tiers ในผลลัพธ์ initialize สำหรับโพรเซสที่กำลังทำงานอยู่ เมื่อเรียกผ่าน REST GET /api/v1/capabilities จะคืนค่าการตรวจสอบภายในที่เทียบเท่ากัน

กรณีขอบและข้อควรระวัง

• ไม่มี “เครื่องมือ 33 รายการ” แบบตายตัว — หรือจำนวนรวมแบบตายตัวใด ๆ เอกสารรุ่นเก่าอ้างถึงตัวเลขเดียว แต่ตัวเลขดังกล่าวไม่ใช่สัญญา จำนวนดังกล่าวเปลี่ยนแปลงตามแพ็กเกจที่ติดตั้ง รายการที่อนุญาต enabled_tools และเกตสภาพแวดล้อมสำหรับ parse_pdf, AST และ mutation ให้อ่านค่าจากเซิร์ฟเวอร์ที่กำลังทำงานเสมอ

• รายการที่อนุญาตมีหน้าที่ตัดออก ไม่เคยเพิ่มเครื่องมือเข้ามา การระบุเครื่องมือ Pro ไว้ใน enabled_tools ไม่ได้ทำให้เครื่องมือนั้นลงทะเบียนเมื่อ nextpdf/premium ไม่ปรากฏอยู่

• ระดับที่ขาดหายไปจะไม่มีการแจ้งเตือนและเป็นเรื่องที่คาดไว้แล้ว การติดตั้งแบบโอเพนซอร์สเท่านั้นจะให้บริการชุดเครื่องมือ core และรายงานจำนวนเครื่องมือ Pro เป็นศูนย์และเครื่องมือ Enterprise เป็นศูนย์ ผลลัพธ์ดังกล่าวคือการทำงานที่ถูกต้อง ไม่ใช่ข้อผิดพลาด

• ระดับในแค็ตตาล็อกเป็นค่าคงที่ที่ประกาศไว้ เครื่องมือแต่ละรายการประกาศระดับและความเสี่ยงของตนเองในโค้ด รีจิสทรีไม่เคยอนุมานระดับจากเนมสเปซหรือแพ็กเกจ

ประสิทธิภาพ

การสแกนรีจิสทรีและการตรวจหาระดับทำงานเพียงหนึ่งครั้งระหว่างการบูต performance_budget ของหน้านี้เป็นตัวกำหนดขอบเขตสำหรับงานเหล่านี้ ต้นทุนต่อเครื่องมือมาจากการดำเนินการของเอนจินพื้นฐาน ไม่ใช่จากการค้นหาในแค็ตตาล็อกซึ่งเป็น O(1) ตามชื่อเครื่องมือ

หมายเหตุด้านความปลอดภัย

ใช้ enabled_tools เป็นกลไกควบคุมแบบสิทธิ์ขั้นต่ำ: เปิดเผยเฉพาะเครื่องมือที่การผสานการทำงานจำเป็นต้องใช้ แค็ตตาล็อกไม่เคยรวมเครื่องมือที่ถูกปฏิเสธโดยนโยบายความปลอดภัย และตัวนับของแต่ละระดับสะท้อนเฉพาะเครื่องมือที่ได้รับอนุญาตเท่านั้น เครื่องมือที่มีความเสี่ยงสูงยังคงถูกควบคุมด้วยการยืนยันจากมนุษย์โดยไม่ขึ้นอยู่กับการเป็นสมาชิกในแค็ตตาล็อก ดู /connect/security-and-operations/

ความสอดคล้อง

หน้านี้อธิบายกลไกของรีจิสทรี การอ้างอิงโพรโทคอลสำหรับพื้นผิว tools/list และ initialize ถูกตรึงไว้ที่ /transports/mcp/ ส่วนโมเดลความเสี่ยงระบุไว้ที่ /connect/hitl-risk-tiers/

บริบทเชิงพาณิชย์

แค็ตตาล็อก core ครอบคลุมการสร้าง การตรวจสอบ และการวินิจฉัย เครื่องมือการลงนาม การลบข้อมูล การปฏิบัติตามข้อกำหนด และนิติวิทยาศาสตร์จะปรากฏเฉพาะเมื่อมีการติดตั้ง nextpdf/premium ควบคู่ไปกับเซิร์ฟเวอร์ ขอบเขตการจัดแพ็กเกจนี้ถูกบังคับใช้ในขั้นตอน composer require ไม่ใช่ผ่านการแจ้งเตือนขณะรันไทม์

ดูเพิ่มเติม

• /connect/hitl-risk-tiers/ — ความหมายของคอลัมน์ความเสี่ยงและวิธีการบังคับใช้
• /connect/boot-and-discovery/ — ลำดับการบูตและการค้นหาทั้งหมด
• /connect/configuration/ — enabled_tools และเกตของสภาพแวดล้อม
• /transports/mcp/ — tools/list และ initialize ในรูปแบบ wire
• /connect/overview/ — เหตุผลที่แค็ตตาล็อกออกแบบมาให้ขึ้นกับรันไทม์