การแก้ไขปัญหา NextPDF Connect

ภาพรวมโดยสรุป

ความล้มเหลวส่วนใหญ่แบ่งได้เป็นหนึ่งในห้ารูปแบบ ได้แก่ การแฮนด์เชค JavaScript Object Notation Remote Procedure Call (JSON-RPC) ที่มีรูปแบบไม่ถูกต้อง คีย์ application programming interface (API) ที่ขาดหาย เครื่องมือที่ไม่ได้ติดตั้งในระดับชั้นนี้ ความท้าทายในการยืนยันที่ยังไม่ได้ตอบ หรือ store ที่ worker ไม่ได้ใช้ร่วมกัน แต่ละรูปแบบมีลักษณะเฉพาะของตนเอง

การติดตั้ง

composer require nextpdf/server

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

ทรานสปอร์ต Model Context Protocol (MCP) จะส่งคืนอ็อบเจกต์ข้อผิดพลาด JSON-RPC 2.0 พร้อมรหัสมาตรฐาน ส่วนทรานสปอร์ต Representational State Transfer (REST) จะส่งคืนเอกสาร problem-details ตาม Request for Comments (RFC) 7807 เอกสารแต่ละฉบับมี URL type ที่ระบุเงื่อนไขนั้น สำหรับปัญหาด้านสภาพแวดล้อม ให้เริ่มต้นด้วยเครื่องมือวินิจฉัย (diagnostic.doctor, diagnostic.capabilities) เครื่องมือเหล่านี้อยู่ในแคตตาล็อกหลักเสมอ

พื้นผิว API

รหัสข้อผิดพลาด JSON-RPC ของ MCP

รหัส	ชื่อ	สาเหตุ
`-32700`	ข้อผิดพลาดในการแยกวิเคราะห์	บรรทัดนั้นไม่ใช่ JSON ที่ถูกต้อง
`-32600`	คำขอไม่ถูกต้อง	ไม่ใช่ข้อความ JSON-RPC 2.0 (ไม่มี `jsonrpc`/`method`)
`-32601`	ไม่พบเมธอด	เมธอดอื่นนอกเหนือจาก `initialize`, `tools/list`, `tools/call`
`-32602`	พารามิเตอร์ไม่ถูกต้อง	ไม่มี `params.name` ใน `tools/call`
`-32603`	ข้อผิดพลาดภายใน	เครื่องมือเกิดข้อยกเว้นขณะดำเนินการ

เครื่องมือที่ล้มเหลว อย่างนุ่มนวล จะไม่ใช้รหัสเหล่านี้ แต่จะส่งคืนการตอบกลับ JSON-RPC ที่สำเร็จ พร้อม isError: true ในผลลัพธ์และคำอธิบายแบบข้อความ เช่น เครื่องมือที่ไม่รู้จัก เครื่องมือที่ถูกปิดใช้งานโดยนโยบาย หรืออาร์กิวเมนต์ไม่ถูกต้อง

ประเภท problem-details ของ REST

HTTP	`type` ตัวระบุ (slug)	สาเหตุ
`401`	`unauthorized`	คีย์ API ขาดหาย/ไม่ถูกต้อง/ถูกปิดใช้งาน/หมดอายุ
`403`	`capability-denied`	ระดับชั้นของคีย์ไม่มีสิทธิ์ในการดำเนินการนี้
`413`	`payload-too-large` / `tier-payload-exceeded`	เนื้อหาเกินเพดานระดับโกลบอลหรือระดับชั้น
`422`	`validation-failed`	เนื้อหาคำขอไม่ผ่านการตรวจสอบสคีมา
`429`	`ip-rate-exceeded` / `client-rate-exceeded`	ถึงขีดจำกัดอัตราแล้ว
`404`	`not-found`	เส้นทางที่ไม่รู้จักหรือ id ของ job/session
`504`	(หมดเวลาคำขอ)	การดำเนินการเกินเวลาหมดเวลาของระดับชั้น

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

รันการตรวจสอบสถานะของสภาพแวดล้อม โดยไม่ต้องใช้เอกสารหรือการยืนยัน:

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

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

ก่อนดีบัก “เครื่องมือที่ขาดหายไป” ให้ยืนยันก่อนว่าการดีพลอยนี้เปิดเผยเครื่องมือใดบ้าง:

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

หรือเชื่อมต่อกับ REST server ที่กำลังทำงานอยู่:

curl -sS http://localhost:8080/api/v1/capabilities \
  -H "Authorization: Bearer $NEXTPDF_KEY"

กรณีพิเศษและจุดที่ควรระวัง

“เครื่องมือที่ไม่รู้จัก” สำหรับเครื่องมือ Pro/Enterprise แพ็กเกจของเครื่องมือนั้นยังไม่ได้ติดตั้ง รีจิสทรีจะตรวจสอบคลาสของผู้ให้บริการและข้ามระดับชั้นที่ไม่มีอยู่โดยไม่มีการเตือน นี่เป็นพฤติกรรมที่คาดไว้ ไม่ใช่ข้อบกพร่อง ติดตั้ง nextpdf/premium ควบคู่กับ server หรือใช้เครื่องมือหลัก ข้อความแสดงข้อผิดพลาดมีเส้นทางการติดตั้งรวมอยู่ด้วย
เครื่องมือที่ฉันกำหนดค่าไว้ใน enabled_tools ไม่ปรากฏ รายการที่อนุญาตจะถูกนำไปตัดกับเครื่องมือที่ค้นพบแล้ว ไม่สามารถเพิ่มเครื่องมือที่รีจิสทรีไม่พบได้ ตรวจสอบการติดตั้งระดับชั้นและเกตด้านสภาพแวดล้อมที่เกี่ยวข้อง ตัวอย่างเช่น parse_pdf เป็นแบบ opt-in ผ่าน NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED
tools/call ส่งคืนข้อความที่ขอโทเค็น นั่นคือความท้าทายในการยืนยัน ไม่ใช่ข้อผิดพลาด เรียกเครื่องมือนี้อีกครั้งภายใน 300 วินาทีโดยตั้งค่า _confirmation_token เป็นโทเค็นที่ออกให้ ดู /connect/hitl-risk-tiers/
บรรทัดการแจ้งเตือนไม่สร้างเอาต์พุต นั่นถูกต้องแล้ว ข้อความ JSON-RPC ที่ไม่มี id ถือเป็นการแจ้งเตือน และตัวจัดการจะไม่ส่งคืนสิ่งใด ส่งคำขอพร้อม id เพื่อรับการตอบกลับ
id ของคำขอที่ซ้ำกันส่งคืนการตอบกลับที่ค้างอยู่ ตัวจัดการจะลบรายการซ้ำตาม id ของคำขอในบัฟเฟอร์ขนาด 64 รายการ ใช้ id ใหม่สำหรับคำขอเชิงตรรกะแต่ละรายการ
ขีดจำกัดอัตราทำงานผิดปกติข้าม worker store แบบ in-memory เป็นแบบต่อ worker หากต้องการใช้จำนวนการนับร่วมกัน ให้ตั้งค่า NEXTPDF_REDIS_HOST และติดตั้ง ext-redis ดู /connect/deployment/
เอกสารหายไประหว่างคำขอ document store แบบ in-memory เป็นแบบต่อ worker และถูกจำกัดด้วยเวลามีชีวิต (document_ttl ค่าเริ่มต้น 1800 วินาที) เพื่อความต่อเนื่องของเอกสารข้าม worker ให้ใช้ store ที่รองรับด้วย Redis ใช้เอนด์พอยต์เซสชัน หรือเก็บชุดการดำเนินการทั้งหมดไว้ในการเรนเดอร์แบบซิงโครนัสครั้งเดียว
server ถอยกลับไปใช้ in-memory แม้จะมีการกำหนดค่า Redis REST server จะถอยกลับโดยอัตโนมัติหากการเชื่อมต่อ Redis ล้มเหลวตอนบูต ตรวจสอบความสามารถในการเข้าถึง Redis และยืนยันว่า ext-redis มีอยู่ในอิมเมจที่กำลังทำงาน อย่าสันนิษฐานว่ามีการใช้ Redis โดยไม่ตรวจสอบยืนยัน
server ปฏิเสธที่จะบูตพร้อมข้อผิดพลาดของการกำหนดค่า รายการ risk_level_overrides พยายามลดระดับเครื่องมือ ApprovalRequired ตัวโหลดปฏิเสธสิ่งนี้โดยการออกแบบ ให้นำการลดระดับออก การแทนที่เพิ่มระดับความเสี่ยงได้เท่านั้น

ประสิทธิภาพ

หากการเรนเดอร์ช้าภายใต้โหลด ให้ยืนยันว่าพูลของ worker ไม่ได้ทำงานเต็มกำลัง ตรวจสอบเอนด์พอยต์เมตริกของ RoadRunner จากนั้นย้ายการเรนเดอร์ที่ใช้เวลานานไปยังเส้นทางงานแบบ async เพื่อไม่ให้ worker ค้างอยู่ ดู /connect/production-usage/

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

อย่าแก้ปัญหา 401 ด้วยการเปิดเผยทรานสปอร์ต MCP ที่ไม่ได้รับการรับรองตัวตนผ่านเครือข่าย เพราะนั่นเท่ากับลบการรับรองตัวตนออกทั้งหมด ให้แก้ไขคีย์ API แทน อย่าเพิ่มระดับความละเอียดของบันทึกเพื่อตรวจสอบอาร์กิวเมนต์ของเครื่องมือในสภาพแวดล้อมที่ใช้ร่วมกัน เพราะ payload ของอาร์กิวเมนต์อาจมีข้อมูลอ่อนไหว ดู /connect/security-and-operations/

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

หน้านี้ให้คำแนะนำเชิงปฏิบัติการ ส่วนการอ้างอิงด้านโปรโตคอลและความปลอดภัยถูกตรึงไว้ที่ /transports/mcp/, /transports/rest/ และ /connect/security-and-operations/

ดูเพิ่มเติม

/connect/tool-catalog/ — สิ่งที่แคตตาล็อกหลักมีและเหตุผลที่จำนวนแปรผัน
/connect/hitl-risk-tiers/ — ความท้าทายในการยืนยันโดยละเอียด
/connect/deployment/ — Redis พูลของ worker และการใช้ store ร่วมกัน
/connect/security-and-operations/ — ความล้มเหลวในการรับรองตัวตนและสถานะการตั้งค่า