NextPDF Connect — ทรานสปอร์ต MCP

โดยสรุป

ทรานสปอร์ต Model Context Protocol (MCP) เรียกใช้ bin/nextpdf-mcp เป็นกระบวนการย่อยภายในเครื่อง และสื่อสารด้วย JSON-RPC 2.0 ผ่าน standard input และ standard output เซิร์ฟเวอร์ใช้รุ่นแก้ไข MCP วันที่ 2025-06-18

การติดตั้ง

composer require nextpdf/server

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

ในโมเดล stdio ของ MCP ไคลเอนต์เรียกเซิร์ฟเวอร์ขึ้นมาเป็นกระบวนการย่อย ไคลเอนต์แลกเปลี่ยนข้อความ JSON-RPC ที่คั่นด้วยการขึ้นบรรทัดใหม่ หนึ่งข้อความต่อหนึ่งบรรทัด ไม่มีการขึ้นบรรทัดใหม่ฝังอยู่ภายใน และใช้ UTF-8 เซิร์ฟเวอร์เขียนเฉพาะข้อความ MCP ที่ถูกต้องไปยัง standard output และส่ง log ไปยัง standard error ในการใช้งานจริง audit logger จะถูกกำหนดเส้นทางไปยัง standard error เพื่อไม่ให้บรรทัด log ทำให้สตรีมโพรโทคอลเสียหาย ข้อกำหนด MCP อย่างเป็นทางการ รุ่นแก้ไข 2025-06-18 เป็นผู้กำหนดรูปแบบการจัดเฟรมนี้ ข้อกำหนดดังกล่าวไม่ได้เป็นส่วนหนึ่งของคลังมาตรฐานที่ควบคุม จึงอ้างอิงด้วย URL: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports

NextPDF Connect ใช้งานทรานสปอร์ต stdio ข้อกำหนด MCP ยังกำหนดทรานสปอร์ต Streamable HTTP ไว้ด้วย ข้อกำหนดระบุว่าไคลเอนต์ควรรองรับ stdio เมื่อทำได้ และเซิร์ฟเวอร์อาจใช้งาน stdio เพียงอย่างเดียวก็ได้ หากต้องการเข้าถึงเครื่องมือชุดเดียวกันผ่านเครือข่าย ให้ใช้ทรานสปอร์ต REST หรือ gRPC แทน ดู /transports/rest/ และ /transports/grpc/

พื้นผิว API

เมท็อด

เมท็อด	พฤติกรรม
initialize	คืนค่าเวอร์ชันโพรโทคอล ความสามารถ และข้อมูลเซิร์ฟเวอร์
notifications/initialized	การแจ้งเตือน (ไม่มี id) รับไว้โดยไม่มีการตอบกลับ
tools/list	แสดงรายการเครื่องมือที่ลงทะเบียนไว้ พร้อมตัวกรอง params.category ที่เลือกได้
tools/call	เรียกใช้เครื่องมือตาม params.name ด้วย params.arguments

เมท็อดอื่นทั้งหมดจะคืนค่า method-not-found (-32601) ข้อความที่ไม่ใช่ JSON-RPC 2.0 ที่ถูกต้องจะคืนค่า invalid-request (-32600) อินพุตที่แจงไม่ได้จะคืนค่า parse-error (-32700) คำขอที่มี id ซ้ำกันจะคืนค่าการตอบกลับก่อนหน้าที่แคชไว้จากบัฟเฟอร์ขนาด 64 รายการ โดยไม่เรียกใช้งานซ้ำ

การตอบกลับ initialize

ผลลัพธ์ initialize จะคืนค่า protocolVersion 2025-06-18 serverInfo.name: NextPDF Connect และอ็อบเจกต์ capabilities นอกจากความสามารถ tools มาตรฐานแล้ว เซิร์ฟเวอร์ยังเพิ่มบล็อก capabilities.nextpdf:

• tiers — จำนวนเครื่องมือที่ลงทะเบียนแบบเรียลไทม์ แยกตามระดับ (core / pro / enterprise)
• tool_count — จำนวนเครื่องมือที่ลงทะเบียนทั้งหมด คำนวณ ณ รันไทม์
• risk_model_version — เวอร์ชันของโมเดลความเสี่ยงที่เซิร์ฟเวอร์บังคับใช้
• hitl_enabled — true เกตการยืนยันทำงานอยู่

tool_count คือจำนวนที่ถือเป็นทางการสำหรับการดีพลอย นี้ เป็นจำนวนที่นับ ณ รันไทม์ ไม่ใช่ค่าคงที่ที่มีเอกสารกำกับ ดู /connect/tool-catalog/

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

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

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

ตัวกรองหมวดหมู่จะจำกัดแคตตาล็อกให้เหลือเฉพาะโดเมนเดียว:

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

ค่าหมวดหมู่มาจากหมวดหมู่ที่แต่ละเครื่องมือประกาศไว้ (ตัวอย่างเช่น document diagnostic)

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

• ไม่มี API key ทรานสปอร์ต stdio ไม่มีตัวรับฟังเครือข่ายและไม่มี bearer token ให้ถือว่าขอบเขตกระบวนการของระบบปฏิบัติการคือขอบเขตความเชื่อถือ ตามโมเดล stdio ของ MCP อย่าเชื่อมต่อกระบวนการนี้เข้ากับเครือข่าย

• ความท้าทายการยืนยันเป็นแบบ in-band เครื่องมือที่เป็น ApprovalRequired จะคืนค่าการตอบกลับ JSON-RPC ที่สำเร็จ เนื้อหาการตอบกลับคือข้อความความท้าทายและโทเค็นแบบใช้ครั้งเดียว ไม่ใช่ข้อผิดพลาด ดู /connect/hitl-risk-tiers/

• การแจ้งเตือนเป็นแบบเงียบ ข้อความที่ไม่มี id จะไม่สร้างการตอบกลับ การจับมือคือ initialize (ที่มี id) จากนั้นการแจ้งเตือน initialized แล้วจึงเป็นการเรียกที่มี id

ประสิทธิภาพ

เซิร์ฟเวอร์ MCP ทำงานเป็นกระบวนการเดียวและจัดการคำขอครั้งละหนึ่งรายการผ่าน pipe ไม่มีการรับส่งข้อมูลไปกลับผ่านเครือข่าย เวลาแฝงขึ้นอยู่กับการดำเนินการของเอนจินเบื้องหลังเป็นหลัก

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

ทรานสปอร์ตสืบทอดความเชื่อถือจากไคลเอนต์ที่เรียกใช้งาน ให้เก็บกระบวนการย่อยไว้ภายในเครื่อง เครื่องมือที่มีความเสี่ยงสูงยังคงต้องการการยืนยันจากมนุษย์ แม้จะไม่มี API key ก็ตาม ดู /connect/security-and-operations/

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

การจัดเฟรม stdio และพฤติกรรม initialize/lifecycle สอดคล้องกับข้อกำหนด Model Context Protocol อย่างเป็นทางการ การแก้ไข 2025-06-18:

• ทรานสปอร์ต: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports
• วงจรชีวิต: https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle

ข้อกำหนด MCP ไม่ได้อยู่ในคลังมาตรฐานที่ควบคุม จึงไม่มี reference_id URL อย่างเป็นทางการข้างต้นคือแหล่งอ้างอิงที่ถือเป็นหลักฐาน

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

tools/list จะคืนค่าเครื่องมือ Pro และ Enterprise เฉพาะเมื่อมีการติดตั้ง nextpdf/premium ควบคู่ไปกับเซิร์ฟเวอร์ ตัวทรานสปอร์ตเองเหมือนกันไม่ว่าจะติดตั้งระดับใดก็ตาม

ดูเพิ่มเติม

• /connect/quickstart/ — การจับมือที่เรียกใช้งานได้
• /connect/tool-catalog/ — สิ่งที่ tools/list คืนค่าและเหตุผลที่จำนวนแตกต่างกัน
• /connect/hitl-risk-tiers/ — รูปแบบความท้าทายการยืนยัน
• /transports/rest/ · /transports/grpc/ — ทางเลือกแบบเครือข่าย
• /connect/migrating-to-multi-transport/ — การย้ายการผสานรวมที่ใช้ MCP เพียงอย่างเดียวไปยัง REST/gRPC