MCP Tools — การอ้างอิงเชิงลึก

ความพร้อมใช้งานและการออกใบอนุญาต

ความสามารถนี้มาพร้อมกับ NextPDF Pro (nextpdf/pro) และเปิดใช้งานด้วยซองใบอนุญาตระดับ Pro การนำไปใช้งานที่ไม่มีสิทธิ์ดังกล่าวจะไม่โหลดคลาสของความสามารถนี้ เปรียบเทียบรุ่นและขอใบอนุญาต

ไม่มีแฟล็กใบอนุญาตรายฟีเจอร์ โค้ดมาพร้อมกับรุ่น Pro และเครื่องมือทั้งแปดลงทะเบียนภายใต้ระดับชั้น pro เมื่อแพ็กเกจ Pro แปลงค่าได้ขณะบูตควบคู่กับ nextpdf/server

ข้อกำหนดด้านพฤติกรรม

• NextPDF Server ค้นพบระดับชั้นขณะบูตโดยตรวจสอบหาคลาส tool-provider ของ Pro หากแปลงค่าได้ เซิร์ฟเวอร์จะลงทะเบียนเครื่องมือทั้งแปดภายใต้ระดับชั้น pro แพ็กเกจ Pro ไม่ใช่การพึ่งพาแบบบังคับของเซิร์ฟเวอร์ ดังนั้นเครื่องมือ Pro จึงเป็นแบบเลือกใช้โดยเด็ดขาดผ่านการติดตั้งร่วม การลงทะเบียนระดับชั้นเป็นอิสระต่อกัน ระดับชั้นที่ขาดหายไปหรือถูกนโยบายกีดกันจะไม่ขัดขวางระดับชั้นอื่น
• เครื่องมือแต่ละตัวประกาศหนึ่งในสี่ระดับความเสี่ยง (safe, caution, review, approval-required) การ override โดยผู้ปฏิบัติงานที่เลือกได้สามารถ ยกระดับ ความเสี่ยงของเครื่องมือได้เท่านั้น ไม่สามารถลดได้ เซิร์ฟเวอร์บันทึก audit-log การประมวลผลใด ๆ ที่ระดับ caution ขึ้นไป sign_pdf เป็น approval-required
• อินพุต PDF แปลงค่าตามลำดับตายตัว: document_id จากที่เก็บในหน่วยความจำ จากนั้น source เป็น data: URI พาธของระบบไฟล์ หรือ base64 ดิบ อินพุตที่ขาดหายไปจะคืนค่าข้อผิดพลาดการตรวจสอบแทนที่จะประมวลผลเอกสารว่าง
• sign_pdf สร้างลายเซ็น PAdES B-B baseline เท่านั้น ไม่มีการประทับเวลา ไม่มีการตรวจสอบยืนยันระยะยาว อัลกอริทึมที่รองรับและซองขนส่งคีย์ AES-GCM มีรายละเอียดอยู่ด้านล่าง การถอดรหัสล้มเหลวแบบ fail closed และเครื่องมือไม่เคยใช้ ciphertext เป็นวัสดุคีย์
• ดูส่วนด้านล่างสำหรับรายละเอียดการค้นพบ ความเสี่ยง การแปลงแหล่งข้อมูล รายเครื่องมือ และการลงลายเซ็นแบบครบถ้วน หน้านี้อธิบายเฉพาะพฤติกรรมที่สังเกตได้จากภายนอกและข้อกำหนดเครื่องมือที่เผยแพร่แล้วเท่านั้น

ขอบเขต

หน้านี้เป็นการอ้างอิงสำหรับผู้ปฏิบัติงานและผู้ผสานระบบของเครื่องมือ MCP ของ Pro ทั้งแปด ครอบคลุมแบบจำลองการค้นพบ ความหมายของ risk/HITL ที่เซิร์ฟเวอร์นำมาใช้ กฎการแปลงแหล่งข้อมูล ซองขนส่งคีย์การลงลายเซ็น และพฤติกรรมเมื่อล้มเหลวรายเครื่องมือ หน้านี้อธิบายเฉพาะพฤติกรรมที่สังเกตได้จากภายนอกและข้อกำหนดเครื่องมือที่เผยแพร่แล้วเท่านั้น สำหรับแคตาล็อกที่หันเข้าหาผู้ใช้ ดู หน้า MCP สาธารณะ

แบบจำลองการค้นพบและการลงทะเบียน

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

เซิร์ฟเวอร์แยกการลงทะเบียนต่อระดับชั้น หากแพ็กเกจ Pro ไม่มีอยู่ เครื่องมือ Core ก็ยังลงทะเบียน ผู้ให้บริการระดับชั้นที่มีอยู่ไม่ขัดขวางระดับชั้นอื่น การลงทะเบียนเครื่องมือยังขึ้นกับ allow-list ของนโยบายความปลอดภัยของเซิร์ฟเวอร์ด้วย เครื่องมือที่ถูกนโยบายกีดกันจะไม่ถูกลงทะเบียนอย่างเงียบและไม่ถูกนับในสรุประดับชั้น เซิร์ฟเวอร์เปิดเผยจำนวนต่อระดับชั้น (core / pro / enterprise) สำหรับการวินิจฉัยและการบันทึกล็อก

ผู้ให้บริการคืนเครื่องมือทั้งแปดตามลำดับตายตัว: text extraction, segmentation, comparison, PII masking, form fill, form read-back, accessibility analysis, signing ลำดับเสถียร แต่ผู้เรียกต้องไม่พึ่งพามัน ให้แปลงค่าเครื่องมือด้วยชื่อโปรโตคอล MCP ของมัน

แบบจำลองความเสี่ยงและความหมายของ HITL

เครื่องมือแต่ละตัวประกาศหนึ่งในสี่ระดับความเสี่ยง เซิร์ฟเวอร์ใช้ระดับที่ประกาศไว้สำหรับการบังคับใช้ human-in-the-loop:

• Safe — อ่านอย่างเดียว ไม่มีผลข้างเคียง ประมวลผลอัตโนมัติ
• Caution — สร้างหรือแก้ไขสถานะในหน่วยความจำ ประมวลผลอัตโนมัติพร้อมรายการ audit-log
• Review — สร้างเอาต์พุตที่อาจถูกใช้ในทางที่ผิด ประมวลผลอัตโนมัติ แต่คำสั่งสกิลของเอเจนต์ติดธงไว้เพื่อให้เอเจนต์เตือนผู้ใช้
• Approval-required — ทำลายล้าง เกี่ยวข้องกับกฎหมาย หรือสำคัญต่อความเป็นส่วนตัว เซิร์ฟเวอร์ต้องการการยืนยันจากมนุษย์อย่างชัดเจนก่อนการประมวลผล

การจัดประเภทเครื่องมือ Pro: เครื่องมือสกัด/วิเคราะห์ห้าตัว (extract_text, segment_document, compare_pdfs, extract_form_data, check_accessibility) เป็น safe redact_pii และ fill_form เป็น review sign_pdf เป็น approval-required

ระดับความเสี่ยงมาจากแหล่งสองแหล่งเท่านั้น: การประกาศของเครื่องมือเอง และการ override โดยผู้ปฏิบัติงานที่เลือกได้ขณะรัน การ override สามารถ ยกระดับ ความเสี่ยงของเครื่องมือได้เท่านั้น (เข้มงวดขึ้น) ไม่สามารถลดได้ เซิร์ฟเวอร์บันทึก audit-log การประมวลผลใด ๆ ที่ระดับ caution ขึ้นไป แบบจำลองความเสี่ยงพกเวอร์ชัน เซิร์ฟเวอร์ประกาศเวอร์ชันนั้นในการตอบสนองตอนเริ่มต้น เพื่อให้ไคลเอนต์ตรวจจับการเปลี่ยนแปลงที่เข้ากันไม่ได้

ลำดับการแปลงแหล่งข้อมูล

เครื่องมือทุกตัวที่รับ PDF จะรับผ่านรูปแบบอินพุตหนึ่งในสามแบบ แปลงค่าตามลำดับนี้:

1. document_id — เซิร์ฟเวอร์ดึงไบต์จากที่เก็บเอกสารในหน่วยความจำ id ที่ไม่รู้จักจะล้มเหลวพร้อมข้อผิดพลาดที่ชัดเจนซึ่งชี้นำให้ผู้เรียกสร้างเอกสารก่อน
2. source เป็น data: URI — เครื่องมือถอดรหัสเนื้อ base64 หลังเครื่องหมายจุลภาค
3. source เป็นพาธของระบบไฟล์ — เครื่องมืออ่านจากดิสก์เมื่อพาธแปลงค่าเป็นไฟล์
4. source เป็นสตริง base64 ดิบ — เครื่องมือยอมรับและถอดรหัสเฉพาะอินพุตที่ยาวพอและมีรูปทรงแบบ base64 เท่านั้น

compare_pdfs ใช้การแปลงค่าเดียวกันอย่างเป็นอิสระกับ source_a และ source_b และยังยอมรับค่า document_id ในช่อง source ช่องใดช่องหนึ่งด้วย หากไม่ได้ส่งทั้ง document_id และ source มา เครื่องมือจะคืนค่าข้อผิดพลาดการตรวจสอบแทนที่จะประมวลผลเอกสารว่าง

การอ้างอิงรายเครื่องมือ

Tool	Risk	Inputs	Result fields	Behavioral boundary
extract_text	safe	PDF; page_start / page_end แบบ 1-indexed ที่เลือกได้	ข้อความ จำนวนหน้ารวม	เฉพาะเลเยอร์ข้อความ ช่วงถูกจำกัดให้อยู่ในจำนวนหน้าจริง ไม่มี OCR
segment_document	safe	PDF	จำนวนเซกเมนต์ รายการเซกเมนต์	เซกเมนต์ที่ได้จากเลย์เอาต์ ไม่ใช่ structure tree ของ tagged-PDF
compare_pdfs	safe	สอง PDF	แฟล็กเหมือนกัน จำนวนการเปลี่ยนแปลงรวม จำนวนหน้าต่อเอกสาร บริเวณ (ชนิด ข้อความ ดัชนีหน้า ดัชนีบรรทัด ข้อความคู่ตรงข้ามที่เลือกได้)	เปรียบเทียบเนื้อหาข้อความ ไม่ใช่ภาพหรือไบนารี
redact_pii	review	PDF; types ที่เลือกได้ (email, phone, ssn, credit_card)	แฟล็กมี-PII จำนวนที่ตรวจพบ ข้อความที่ปิดบัง ชนิดที่สแกน	ตรวจจับ/ปิดบังเลเยอร์ข้อความ ไม่ใช่การปิดบังเชิงภาพ อิงแพตเทิร์น ไม่ครบถ้วนสมบูรณ์
fill_form	review	แมป fields; pdf_filename ที่เลือกได้	เอกสาร XFDF จำนวนฟิลด์	สร้าง XFDF (ISO 19444-1) ไม่ได้เขียนค่าลงใน PDF
extract_form_data	safe	PDF	จำนวนฟิลด์ แมปฟิลด์ หมายเหตุที่ชัดเจนเมื่อไม่มี	อ่านเฉพาะ XFDF ที่ฝังอยู่เท่านั้น
check_accessibility	safe	PDF	คะแนนโครงสร้าง (0–100) ปัญหา สรุปเซกเมนต์	ฮิวริสติกเชิงโครงสร้างพร้อมการอ้างอิง WCAG ไม่ใช่คำตัดสินความสอดคล้อง
sign_pdf	approval-required	PDF; ใบรับรอง PEM + คีย์ PKCS#8; อัลกอริทึม ชื่อผู้ลงนาม เหตุผล ซองขนส่งที่เลือกได้	PDF ที่ลงนาม จำนวนลายเซ็น แฟล็กเสร็จสมบูรณ์ อัลกอริทึม OID ไดเจสต์	PAdES B-B baseline เท่านั้น ไม่มีการประทับเวลา ไม่มี LTV

การลงลายเซ็น: อัลกอริทึมและการขนส่งคีย์

sign_pdf สร้างลายเซ็น PAdES B-B baseline อัลกอริทึมที่รองรับ ยอมรับทั้งการสะกดแบบขีดล่างและขีดกลาง:

• RSA with SHA-256 (ปริยาย)
• RSA with SHA-3 256 / 384 / 512 — ต้องใช้ OpenSSL build ที่รองรับ SHA-3
• Ed25519 — ต้องใช้ส่วนขยาย libsodium คีย์ต้องเป็น PKCS#8 PEM ที่ห่อคีย์ส่วนตัว Ed25519

เครื่องมือปฏิเสธตัวระบุที่ไม่รองรับและคืนรายการค่าที่ยอมรับ

ซองเข้ารหัสการขนส่งที่เลือกได้ช่วยให้ผู้เรียกอุโมงค์คีย์ส่วนตัวผ่านการขนส่งที่ไม่ได้รักษาความลับแบบ end-to-end ซองเป็น AES-GCM เท่านั้น:

• คีย์สมมาตร: 16, 24 หรือ 32 ไบต์ (AES-128/192/256) เข้ารหัสแบบ base64
• Nonce: 12 ไบต์พอดี เข้ารหัสแบบ base64
• additional authenticated data ที่เลือกได้ เข้ารหัสแบบ base64
• เพย์โหลด private_key คือ ciphertext แบบ base64 พร้อมแท็กรับรองความถูกต้อง GCM ขนาด 16 ไบต์ต่อท้าย

การถอดรหัสล้มเหลวแบบ fail closed: แท็กรับรองความถูกต้องที่ไม่ตรงกันหรือเพย์โหลดที่ผิดรูปจะคืนค่าข้อผิดพลาดการถอดรหัส และเครื่องมือไม่เคยใช้ ciphertext เป็นวัสดุคีย์ เครื่องมือปฏิเสธขนาดคีย์หรือ nonce ที่ผิดก่อนงานเข้ารหัสลับใด ๆ

กรณีขอบและโหมด FIPS

• extract_text: เครื่องมือจำกัดปลายช่วงหน้าที่เกินเอกสารแทนที่จะปฏิเสธ และทำให้จุดเริ่มที่ต่ำกว่าหน้าแรกกลายเป็นหน้าแรก
• compare_pdfs: source_a หรือ source_b ที่ขาดหายไปจะคืนค่าข้อผิดพลาดการตรวจสอบ เอกสารที่เหมือนกันจะคืนค่าผลลัพธ์เหมือนกันอย่างชัดเจนพร้อมการเปลี่ยนแปลงเป็นศูนย์
• extract_form_data: PDF ที่ไม่มีสตรีม XFDF ฝังอยู่จะคืนค่าผลลัพธ์ฟิลด์เป็นศูนย์พร้อมหมายเหตุอธิบาย ไม่ใช่ข้อผิดพลาด
• redact_pii: รายการที่ไม่รู้จักใน types จะถูกเพิกเฉย รายการที่ไม่รู้จักทั้งหมดจะให้การสแกนว่างแทนที่จะล้มเหลว
• sign_pdf: ใบรับรองหรือคีย์ส่วนตัวที่ขาดหายไปจะล้มเหลวก่อนงานลงนามใด ๆ เครื่องมือตรวจสอบข้อกำหนดของอัลกอริทึม (การรองรับ SHA-3 ของ OpenSSL, libsodium สำหรับ Ed25519) ขณะลงนามและเผยเป็นข้อผิดพลาดที่ชัดเจน
• โหมด FIPS: ความพร้อมใช้งานของอัลกอริทึมเป็นไปตาม OpenSSL/libsodium build ของโฮสต์ ใน build ที่จำกัดด้วย FIPS อัลกอริทึมที่ไม่ได้รับอนุมัติจะล้มเหลวที่ขอบเขตเข้ารหัสลับพร้อมข้อผิดพลาดที่ชัดเจน แทนที่จะลดระดับอย่างเงียบ เลเยอร์ MCP ไม่เพิ่มหรือผ่อนคลายนโยบายเข้ารหัสลับ มันเผยการตัดสินใจของผู้ให้บริการเข้ารหัสลับของโฮสต์

บันทึก runbook สำหรับผู้ปฏิบัติงาน

• คง sign_pdf เป็น approval-required ยืนยันว่าไม่มีการ override โดยผู้ปฏิบัติงานที่ยกระดับความเสี่ยงบนเครื่องมือ safe โดยไม่ตั้งใจ การ override ทำให้เข้มงวดขึ้นเท่านั้น ดังนั้นการ override โดยอุบัติเหตุจะลดความพร้อมใช้งาน ไม่ใช่ความปลอดภัย
• การเก็บรักษา audit: การประมวลผลทุกครั้งที่ระดับ review ขึ้นไปจะถูกบันทึก audit-log โดยเซิร์ฟเวอร์ กำหนดขนาดการเก็บรักษาล็อกของคุณตามปริมาณการเรียก redact_pii, fill_form และ sign_pdf
• การเลือกการขนส่ง: เมื่อรันผ่านการขนส่งที่ไม่ได้รักษาความลับแบบ end-to-end ให้กำหนดซองขนส่งคีย์ AES-GCM สำหรับ sign_pdf และถือว่าวัสดุคีย์ส่วนตัวเป็นความลับในนโยบายการบันทึกล็อกการเรียกเครื่องมือของเอเจนต์ของคุณ
• จำนวนระดับชั้น: ใช้จำนวนต่อระดับชั้นของเซิร์ฟเวอร์เพื่อยืนยันขณะ deploy ว่าระดับชั้น Pro ลงทะเบียนเครื่องมือแปดตัว จำนวนเป็นศูนย์บ่งชี้ว่าแพ็กเกจ Pro ไม่ได้แปลงค่า

ขอบเขตของรุ่น

ระดับชั้น Pro มีส่วนร่วมเครื่องมือ MCP แปดตัวพอดี รุ่น Enterprise มาพร้อมระดับชั้น MCP แยกต่างหากพร้อมเครื่องมือของตนเอง — compliance, forensics, long-term-validation health, AI-ready certification และ document search/embedding อินพุต เอาต์พุต และภายในของเครื่องมือ Enterprise อยู่นอกขอบเขตที่นี่และมีเอกสารอยู่กับรุ่น Enterprise เซิร์ฟเวอร์ค้นพบระดับชั้นอย่างเป็นอิสระ ระดับชั้นที่ขาดหายไปไม่เคยปิดการใช้งานระดับชั้นอื่น

ขอบเขตการเผยแพร่

หน้านี้บันทึกเฉพาะพฤติกรรมที่สังเกตได้จากภายนอกและพื้นผิว API สาธารณะที่รองรับเท่านั้น พาธ namespace ภายใน คลาสตัวช่วย ตารางกลไก ชื่อไฟล์ runbook และคำนำหน้าตั๋วอยู่นอกขอบเขต

ดูเพิ่มเติม

• MCP Tools — NextPDF Pro
• Security — NextPDF Pro
• NextPDF Server tools