ย้ายไปใช้หลายทรานสปอร์ต

โดยสรุป

ย้ายการผสานการทำงานจากทรานสปอร์ต stdio ของ Model Context Protocol (MCP) ไปยัง Representational State Transfer (REST) หรือ gRPC โดยพฤติกรรมของเอนจินไม่เปลี่ยนแปลง แค็ตตาล็อก โมเดลความเสี่ยง และเกตการยืนยันยังคงเหมือนเดิม สิ่งที่เปลี่ยนมีสามส่วน ได้แก่ โปรโตคอลระดับสายส่ง การยืนยันตัวตน และโมเดลการทำงานพร้อมกัน

การติดตั้ง

composer require nextpdf/server
./vendor/bin/rr get-binary

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

เอกสารรุ่นแรกของแพ็กเกจนี้อธิบายทรานสปอร์ตไว้เพียงแบบเดียว คือ MCP ผ่าน stdio ปัจจุบันแพ็กเกจให้บริการ tool registry เดียวกันผ่านทรานสปอร์ตสามแบบ เมื่อต้องย้าย ให้เลือกทรานสปอร์ตแบบเครือข่าย แล้วจับคู่การเรียก MCP เดิมไปยังทรานสปอร์ตนั้น ไม่จำเป็นต้องเขียนตรรกะเอกสารใหม่

เลือกทรานสปอร์ตให้เหมาะกับรูปแบบการดีพลอย:

• คงใช้ MCP สำหรับเอเจนต์ภายในเครื่องเพียงตัวเดียว เมื่อต้องการเวลาแฝงต่ำที่สุด (ไม่มีการกระโดดผ่านเครือข่าย) หรือสำหรับไคลเอนต์ที่รองรับ MCP โดยกำเนิด เช่น ผู้ช่วย IDE ภายในเครื่อง
• ย้ายไป REST สำหรับการเข้าถึงจากหลายไคลเอนต์ด้วย API key รายไคลเอนต์ การดีพลอยด้วยคอนเทนเนอร์หรือ Kubernetes การจำกัดอัตรารายไคลเอนต์ งานแบบ async หรือไคลเอนต์ภาษาใดก็ได้
• ย้ายไป gRPC สำหรับสัญญาที่มีชนิดข้อมูลชัดเจน การสตรีมไฟล์ PDF ขนาดใหญ่จากเซิร์ฟเวอร์ และการดีพลอยแบบบริการต่อบริการด้วย mutual-TLS

พื้นผิว API

สิ่งที่ยังคงเหมือนเดิม

• tool registry และแค็ตตาล็อกที่ขึ้นกับรันไทม์ (ดู /connect/tool-catalog/)
• โมเดลความเสี่ยงสี่ระดับและเกตการยืนยัน (ดู /connect/hitl-risk-tiers/)
• โมเดลเอกสารและความหมายเชิงพฤติกรรมของเอนจิน

สิ่งที่เปลี่ยนไป

ด้าน	ทรานสปอร์ต MCP (stdio)	REST	gRPC
รูปแบบสายส่ง	JSON-RPC 2.0 ผ่าน stdio	JSON ผ่าน HTTP	Protobuf ผ่าน gRPC
การยืนยันตัวตน	ไม่มี (โปรเซสย่อยภายในเครื่อง)	ใช้ Authorization: Bearer เป็น API key	bearer ในเมตาดาตาการเรียก
การทำงานพร้อมกัน	หนึ่งโปรเซส หนึ่งการเรียก	เวิร์กเกอร์พูลของ RoadRunner	gRPC พูลของ RoadRunner
Async	ไม่เกี่ยวข้อง	endpoint สำหรับงาน	RPC สำหรับงาน
การสตรีม	ไม่เกี่ยวข้อง	เนื้อหาแบบ sync	RPC แบบ server-streaming

การจับคู่แนวคิด

ลำดับ MCP โดยทั่วไปคือ create_pdf ตามด้วยเครื่องมือเนื้อหา แล้วจึง output_pdf ใน REST ลำดับนี้จะกลายเป็นคำขอ POST /api/v1/render แบบ stateless หนึ่งคำขอ พร้อมอาร์เรย์ operations ที่เรียงลำดับไว้ หากต้องการสถานะแบบทีละขั้น ให้ใช้ endpoint เซสชันแบบเลือกใช้แทน ใน gRPC สิ่งที่เทียบเท่าคือ RPC Render หรือ RenderStream สำหรับการส่งมอบเป็นชิ้น สำหรับการสร้างแบบ stateful ให้ใช้ RPC CreateSession, SessionOperation และ SessionRender

ลำดับเครื่องมือ MCP	REST	gRPC
create_pdf + เครื่องมือเนื้อหา + output_pdf	POST /api/v1/render	Render / RenderStream
การสร้างแบบ stateful ข้ามการเรียกหลายครั้ง	POST /api/v1/sessions (+ session ops)	CreateSession (+ SessionOperation)
การเรนเดอร์ที่ใช้เวลานาน	POST /api/v1/jobs แล้วโพลผลลัพธ์	SubmitJob แล้ว GetJobResult
การดำเนินการที่ควบคุมตามระดับ	POST /api/v1/<operation>	ExecuteCapability

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

การเรียก MCP:

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"add_text","arguments":{"text":"Hello"}}}

กลายเป็นคำขอ REST:

curl -sS -X POST http://localhost:8080/api/v1/render \
  -H "Authorization: Bearer $NEXTPDF_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"type":"add_text","text":"Hello"}]}' \
  --output hello.pdf

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

เรียกใช้ทรานสปอร์ตทั้งสองแบบระหว่างการย้ายแบบค่อยเป็นค่อยไป โปรไฟล์ RoadRunner แบบรวมจะให้บริการ REST และ gRPC จาก supervisor เดียว การผสานการทำงาน MCP แบบเดิมยังทำงานต่อในเครื่องได้ในจุดที่เหมาะสม:

export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
./vendor/bin/rr serve -c .rr.full.yaml

ไม่มีสถานะร่วมที่ต้องย้าย ทรานสปอร์ตต่างๆ เป็นโปรเซสอิสระที่ทำงานบนเอนจินเดียวกัน จึงย้ายไคลเอนต์ทีละส่วนได้

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

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

• เกตการยืนยันยังคงทำงาน เครื่องมือ approval_required จะขอการยืนยันใน REST และ gRPC เหมือนกับใน MCP ทุกประการ นำโฟลว์การยืนยันเข้าไปไว้ในการผสานการทำงานใหม่ อย่าสันนิษฐานว่าเกตนี้มีเฉพาะใน MCP เท่านั้น ดู /connect/hitl-risk-tiers/

• การควบคุมตามระดับไม่เปลี่ยนแปลง การดำเนินการระดับ Pro หรือ Enterprise ต้องติดตั้ง nextpdf/premium และมีคีย์ที่ได้รับสิทธิ์บนทรานสปอร์ตใหม่ เช่นเดียวกับที่เครื่องมือที่เกี่ยวข้องใน MCP ต้องมีแพ็กเกจนี้

• Idempotency เป็นความสามารถใหม่และมีประโยชน์ REST เพิ่มการควบคุม idempotency ซึ่งไม่มีในทรานสปอร์ต stdio ใช้ความสามารถนี้เพื่อให้การส่งงานลองใหม่ได้อย่างปลอดภัย ดู /connect/production-usage/

ประสิทธิภาพ

MCP ทำงานแบบโปรเซสเดียวและมีเวลาแฝงต่ำที่สุดสำหรับเอเจนต์ภายในเครื่องเพียงตัวเดียว ทรานสปอร์ตแบบเครือข่ายเพิ่ม worker pool และการกระโดดผ่านเครือข่าย แต่รองรับการขยายไปยังไคลเอนต์จำนวนมากที่ทำงานพร้อมกัน ย้ายการเรนเดอร์ที่ใช้เวลานานไปยังเส้นทางงานแบบ async บนทรานสปอร์ตใหม่ เพื่อไม่ให้ worker ถูกใช้งานค้างไว้

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

การย้ายออกจาก stdio เพิ่มการเปิดรับบนเครือข่าย ทำ termination ของ Transport Layer Security (TLS) ไว้หน้า REST ใช้ mutual TLS สำหรับ gRPC บนเครือข่ายที่ไม่น่าเชื่อถือ จำกัดขอบเขตคีย์รายไคลเอนต์ และตั้ง enabled_tools ให้น้อยที่สุด โมเดลแบบไม่ใช้ข้อมูลรับรองของทรานสปอร์ต MCP ปลอดภัยเพียงเพราะเป็นโปรเซสย่อยภายในเครื่องเท่านั้น อย่าสร้างการเปิดรับเช่นนั้นขึ้นใหม่บนเครือข่าย ดู /connect/security-and-operations/

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

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

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

การดำเนินการที่ควบคุมตามระดับต้องใช้ nextpdf/premium ไม่ว่าจะใช้ทรานสปอร์ตใด การย้ายไม่เปลี่ยนว่าสิ่งใดเป็น core เทียบกับ Premium แต่เปลี่ยนเพียงวิธีเข้าถึงแค็ตตาล็อกเท่านั้น

ดูเพิ่มเติม

• /connect/transports/mcp/ — ทรานสปอร์ตต้นทางของการย้าย
• /connect/transports/rest/ · /connect/transports/grpc/ — ทรานสปอร์ตปลายทางของการย้าย
• /connect/tool-catalog/ — แค็ตตาล็อกที่เหมือนกันในทุกทรานสปอร์ต
• /connect/hitl-risk-tiers/ — เกตที่เหมือนกันในทุกทรานสปอร์ต
• /connect/security-and-operations/ — การยืนยันตัวตนที่ต้องเพิ่ม