เริ่มต้นใช้งาน NextPDF Connect อย่างรวดเร็ว

ภาพรวมโดยย่อ

หน้านี้จะพาคุณเรียกใช้การแลกเปลี่ยนข้อมูลที่เล็กที่สุดแต่ใช้งานได้จริงกับทรานสปอร์ตทั้งสองแบบ ได้แก่ Model Context Protocol (MCP) และ Representational State Transfer (REST) คำขอแต่ละรายการใช้รูปแบบ wire format ที่ตรงกับการทำงานจริงของเซิร์ฟเวอร์อย่างแม่นยำ คุณไม่จำเป็นต้องใช้ชุดพัฒนาซอฟต์แวร์ (SDK)

การติดตั้ง

composer require nextpdf/server

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

ทรานสปอร์ต MCP ใช้ JSON-RPC 2.0 ผ่าน standard input และ output คุณต้องส่งข้อความตามลำดับ โดยส่ง initialize ก่อน ตามด้วยการตอบรับ notifications/initialized จากนั้นจึงส่ง tools/list และ tools/call เซิร์ฟเวอร์อ่านข้อความ JSON หนึ่งข้อความต่อหนึ่งบรรทัด แต่ละบรรทัดต้องลงท้ายด้วยอักขระขึ้นบรรทัดใหม่ และเซิร์ฟเวอร์จะเขียนการตอบกลับหนึ่งรายการต่อหนึ่งบรรทัด

ทรานสปอร์ต REST เปิดเผยความสามารถของเอนจินเดียวกันในรูปแบบการดำเนินการผ่าน Hypertext Transfer Protocol (HTTP) การเรนเดอร์แบบ stateless หนึ่งรายการคือการเรียก POST /api/v1/render หนึ่งครั้งพร้อมอาร์เรย์ operations ที่เรียงลำดับไว้ เนื้อหาของการตอบกลับคือไฟล์ Portable Document Format (PDF)

ตัวอย่างโค้ด — การเริ่มต้นใช้งานอย่างรวดเร็ว (MCP ผ่าน stdio)

เริ่มต้นเซิร์ฟเวอร์ แล้ว pipe ลำดับ handshake เข้าไป คำขอทั้งสามรายการนี้ใช้ชื่อเมธอดที่ตรวจสอบยืนยันแล้ว และตัวจัดการโปรโตคอลกำหนดเส้นทางไว้:

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

การตอบกลับของ initialize จะรายงานเวอร์ชันโปรโตคอล 2025-06-18 ชื่อเซิร์ฟเวอร์ NextPDF Connect และบล็อก capabilities.nextpdf บล็อกนั้นมีจำนวน tier แบบเรียลไทม์ ค่า tool_count ขณะรันไทม์ เวอร์ชันของโมเดลความเสี่ยง และ hitl_enabled: true การตอบกลับของ tools/list จะแสดงรายการเครื่องมือที่ลงทะเบียนไว้สำหรับการติดตั้งนี้อย่างแม่นยำ ส่วนบรรทัด notification จะไม่สร้างการตอบกลับโดยเจตนา

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

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

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

เริ่มต้นเซิร์ฟเวอร์ REST จากนั้นเรนเดอร์ PDF ด้วยคำสั่งบรรทัดเดียว เซิร์ฟเวอร์ต้องใช้คีย์ application programming interface (API) สำหรับทุก endpoint ที่ไม่ใช่ health ดังนั้นให้กำหนดคีย์ก่อน:

export NEXTPDF_API_KEYS='npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef:demo:core:default'
./vendor/bin/rr serve -c .rr.yaml

ในเชลล์ที่สอง ให้ส่งคำขอเรนเดอร์ด้วยเมธอด POST เนื้อหาของคำขอคือ RenderRequest คำขอนี้มีอาร์เรย์ operations ที่เรียงลำดับไว้ ซึ่งประกอบด้วยการดำเนินการแบบมีชนิดข้อมูล

curl -sS -X POST http://localhost:8080/api/v1/render \
  -H 'Authorization: Bearer npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef' \
  -H 'Content-Type: application/json' \
  -d '{
        "page_size": "A4",
        "orientation": "portrait",
        "operations": [
          { "type": "add_text", "text": "Hello from NextPDF Connect" }
        ]
      }' \
  --output hello.pdf

เนื้อหาของการตอบกลับ 200 คือ PDF (Content-Type: application/pdf) ที่เขียนลงในไฟล์ hello.pdf การตรวจสอบ health ไม่ต้องใช้คีย์:

curl -sS http://localhost:8080/healthz

กรณีพิเศษและข้อควรระวัง

• ลำดับของ handshake มีความสำคัญ ตัวจัดการโปรโตคอลจะถือว่าข้อความที่ไม่มี id เป็น notification และจะไม่ส่งสิ่งใดกลับมา ส่ง initialize พร้อม id จากนั้นส่ง notification initialized แล้วจึงตามด้วยคำขอที่มี id

• id ของคำขอที่ซ้ำกันจะถูกตัดออก ตัวจัดการจะแคชการตอบกลับล่าสุดไว้ใน circular buffer ขนาด 64 รายการ สำหรับ id ที่ซ้ำกัน ตัวจัดการจะส่งการตอบกลับที่แคชไว้กลับมาโดยไม่เรียกใช้เครื่องมืออีกครั้ง ให้ใช้ id ใหม่เสมอ

• เครื่องมือที่มีความเสี่ยงสูงจะตอบกลับด้วย challenge ไม่ใช่ผลลัพธ์ การเรียก output_pdf พร้อม file_path จะส่ง challenge สำหรับการยืนยันกลับมาแทนที่จะเรียกใช้งาน ให้เรียกใช้เครื่องมืออีกครั้งพร้อม _confirmation_token ที่ออกให้ โหมดเอาต์พุตแบบ base64 ซึ่งไม่มี file_path ไม่ต้องมีการยืนยัน ดู /connect/hitl-risk-tiers/

• คำขอ REST ที่ไม่ได้รับอนุญาตจะได้รับ 401 ส่วนหัว Authorization: Bearer ที่ขาดหายไปหรือมีรูปแบบไม่ถูกต้องจะส่งเนื้อหาแบบ problem-details กลับมาพร้อมส่วนหัว WWW-Authenticate: Bearer การตรวจสอบ /healthz และ /readyz เป็น endpoint แบบไม่ระบุตัวตนเพียงสองรายการเท่านั้น

ประสิทธิภาพ

เส้นทางการเริ่มต้นใช้งานอย่างรวดเร็วทั้งสองแบบใช้คำขอเพียงรายการเดียว เส้นทาง REST ยังมีค่าใช้จ่ายจากการ cold-start ของ worker pool ของ RoadRunner ในคำขอแรกหลังจาก rr serve คำขอถัดไปจะนำ worker ที่อุ่นเครื่องแล้วกลับมาใช้ซ้ำ

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

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

ความสอดคล้องตามมาตรฐาน

รูปแบบ wire format ที่แสดงตรงกับ MCP revision 2025-06-18 ที่นำมาใช้จริง และ contract REST แบบ OpenAPI 3.1 การอ้างอิงเชิงบรรทัดฐานสำหรับโปรโตคอลและการยืนยันตัวตนถูกตรึงไว้ที่ /transports/mcp/ /transports/rest/ และ /connect/security-and-operations/

ดูเพิ่มเติม

• /transports/mcp/ — เอกสารอ้างอิงทรานสปอร์ต MCP ฉบับเต็ม
• /transports/rest/ — เอกสารอ้างอิงทรานสปอร์ต REST ฉบับเต็มและการเรนเดอร์ OpenAPI
• /connect/tool-catalog/ — เครื่องมือใดบ้างที่ tools/list ส่งกลับมาและเพราะเหตุใด
• /connect/hitl-risk-tiers/ — challenge สำหรับการยืนยันมีลักษณะอย่างไร
• /connect/configuration/ — การจำกัด catalog และการปรับแต่งเซิร์ฟเวอร์