การบูตและการค้นพบใน NextPDF Connect

โดยสรุป

transport แต่ละตัวมีจุดเข้าใช้งานและลำดับการบูตเป็นของตนเอง transport ทั้งหมดใช้ registry การกำหนดค่า และ gate ร่วมกันในเชิงแนวคิด แต่ในทางปฏิบัติ transport เหล่านี้ทำงานเป็นกระบวนการที่แยกจากกัน ดังนั้นการเริ่มต้นตัวหนึ่งจะไม่เริ่มตัวอื่น

การติดตั้ง

composer require nextpdf/server

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

ลำดับการบูตของ MCP

McpServer::create() ประกอบเซิร์ฟเวอร์ Model Context Protocol (MCP) ตามลำดับคงที่ ขั้นแรก ระบบจะโหลดการกำหนดค่า สร้างนโยบายความปลอดภัยจากการกำหนดค่านั้น สร้าง registry ของเครื่องมือ และดำเนินการค้นพบ tier ถัดมา ระบบจะสร้างที่เก็บเอกสารแบบ in-memory จากค่า time to live (TTL) และความจุที่กำหนดไว้ สร้าง transport แบบ stdio และประกอบตัวจัดการโปรโตคอล JSON-RPC เข้ากับ confirmation gate และ audit logger จากนั้นเซิร์ฟเวอร์จะเข้าสู่ลูป read-handle-write และทำงานจนกว่า standard input จะถึงจุดสิ้นสุดไฟล์

ลำดับการบูตของ REST

HttpServer::create() อ่าน HttpConfig จาก environment และใช้ค่า override จาก command-line interface (CLI) จากนั้นจะเลือกที่เก็บคีย์ของ application programming interface (API) ตามลำดับความสำคัญ ได้แก่ ที่เก็บไฟล์แบบ hot-reloading ก่อน ตามด้วยไฟล์แบบ static แล้วจึงใช้ environment ถัดมา ระบบจะเลือกที่เก็บ rate-limit และ idempotency ที่เก็บเหล่านี้จะใช้ Redis เมื่อมีการกำหนดค่า Redis ไว้และเข้าถึงได้ และจะถอยกลับไปใช้ที่เก็บแบบ in-memory ในกรณีอื่น จากนั้นเซิร์ฟเวอร์จะเปิดที่เก็บงาน SQLite ที่ใช้ร่วมกัน สร้างบริการของแอปพลิเคชัน และสร้างตาราง route เนื่องจากตาราง route สร้างจาก tier ที่ตรวจพบ จึงสะท้อนแพ็กเกจที่ติดตั้งไว้ จากนั้น RoadRunner จะขับเคลื่อนลูปคำขอของ worker

ลำดับการบูตของ gRPC

GrpcServer::create() เลือกที่เก็บคีย์เดียวกัน สร้างบริการของแอปพลิเคชันชุดเดียวกัน และลงทะเบียนบริการ nextpdf.connect.v1 กับ worker ของ Spiral gRPC เมื่อ dependency ของ engine ไม่พร้อมใช้งาน เซิร์ฟเวอร์ gRPC จะยังเริ่มทำงานและให้บริการคำขอตรวจสอบ health และ capability ได้ ในสถานะนี้ กระบวนการจะไม่ปฏิเสธการบูต แต่ remote procedure call (RPC) ที่ใช้ส่งข้อมูลจะล้มเหลวแบบควบคุมได้แทน

การค้นพบเครื่องมือ

การค้นพบคือขั้นตอนที่ลงทะเบียนค่าเริ่มต้นของ registry โดยจะลงทะเบียน tier ของ core ก่อน จากนั้นจึงลงทะเบียน provider ของ Pro และ Enterprise หากคลาสของ provider เหล่านั้นตรวจพบได้ผ่าน class_exists() ถัดมา provider ของ Abstract Syntax Tree (AST) และ mutation ที่มาพร้อมกันจะลงทะเบียนภายใต้ tier ของ Pro โดยขึ้นอยู่กับ environment gate ของ provider เหล่านั้น การลงทะเบียนทุกรายการจะถูกกรองผ่าน allowlist ความปลอดภัย enabled_tools และการตอบกลับ initialize ของ MCP จะรายงานจำนวนรายการที่ได้ในแต่ละ tier ดู /connect/tool-catalog/

การค้นพบ transport

ไม่มีค่าการกำหนดค่าเพียงค่าเดียวที่ “enables transports” แต่ละ transport เป็นจุดเข้าใช้งานแยกกัน REST และ gRPC ต่างมีโปรไฟล์ RoadRunner ของตนเอง การ deploy จะเลือก transport ตามโปรไฟล์ที่รัน ได้แก่ .rr.yaml สำหรับ REST, .rr.grpc.yaml สำหรับ gRPC หรือ .rr.full.yaml สำหรับทั้งสองอย่าง ส่วน transport ทั้งหมดทำงานเป็นกระบวนการที่อิสระต่อกัน การไม่มีไคลเอนต์ MCP จะไม่ขัดขวางเซิร์ฟเวอร์ REST แต่อย่างใด และการไม่มีไคลเอนต์ REST ก็ไม่ขัดขวาง MCP เช่นกัน ดู /connect/deployment/

ลำดับการแก้ไขการกำหนดค่า

เซิร์ฟเวอร์ MCP แก้ไขการกำหนดค่าตามลำดับความสำคัญดังนี้ environment (NEXTPDF_MCP_*) มีลำดับเหนือกว่าส่วน nextpdf_mcp ของไฟล์ YAML และส่วนดังกล่าวมีลำดับเหนือกว่าค่าเริ่มต้นในตัว เซิร์ฟเวอร์ REST และ gRPC อ่าน HttpConfig จากตัวแปร environment NEXTPDF_* พร้อมค่าเริ่มต้นที่ปลอดภัย เซิร์ฟเวอร์เหล่านี้ไม่อ่านไฟล์ YAML ของ MCP ดู /connect/configuration/

การ binding ของ container

ไม่มี container ของ dependency-injection หรือ service provider ที่ต้องลงทะเบียน factory แต่ละตัวของ create() สร้าง object graph ของตนเองอย่างชัดเจนและกำหนดได้แน่นอน มี seam ที่ inject ได้สองจุด — คือ transport และ worker factory — และทั้งสองจุดมีไว้สำหรับการทดสอบ ไม่ใช่สำหรับ wiring ของแอปพลิเคชัน

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

ตรวจสอบผลที่การค้นพบสร้างขึ้นโดยไม่ต้องให้บริการ traffic:

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

ตัวอย่างโค้ด — Production

บูต transport ที่รวมไว้ภายใต้ supervisor ตัวเดียว:

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

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

• tier ที่ขาดหายไปจะไม่ทำให้การบูตล้มเหลว การค้นพบ tier จะข้ามแพ็กเกจ Pro หรือ Enterprise ที่ไม่พบไปอย่างเงียบๆ เซิร์ฟเวอร์จะบูตด้วย catalog ของ core

• การ override เพื่อลดระดับจะทำให้การบูตล้มเหลว รายการ risk_level_overrides ที่ทำให้เครื่องมือ approval_required ลดความเข้มงวดลงจะทำให้เกิดข้อผิดพลาดระหว่างการโหลดการกำหนดค่า เซิร์ฟเวอร์จะปฏิเสธการเริ่มทำงาน พฤติกรรมนี้เป็นความตั้งใจ

• ความล้มเหลวของ Redis ทำให้ประสิทธิภาพลดลง ไม่ใช่ทำให้ขัดข้อง หากมีการกำหนดค่า Redis ไว้แต่เข้าถึงไม่ได้ขณะบูต เซิร์ฟเวอร์ REST จะถอยกลับไปใช้ที่เก็บแบบ in-memory ควรตรวจสอบ health ของ Redis แทนที่จะสันนิษฐานว่า Redis กำลังถูกใช้งานอยู่

ประสิทธิภาพ

ต้นทุนการบูตมาจากการ parse การกำหนดค่า การสแกน registry และการตรวจหา tier performance_budget ของเพจกำหนดกรอบต้นทุนนี้ ต้นทุนนี้เกิดขึ้นเพียงครั้งเดียวต่อการเริ่มกระบวนการ ไม่ใช่ต่อคำขอแต่ละครั้ง

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

นโยบายความปลอดภัยถูกสร้างขึ้นก่อน registry ดังนั้น allowlist enabled_tools จึงจำกัดการค้นพบตั้งแต่การลงทะเบียนครั้งแรก คีย์ API จะไม่ถูกอ่านจากไฟล์ YAML ของ MCP โดยเด็ดขาด transport ที่เชื่อมต่อเครือข่ายจะอ่านคีย์จากไฟล์ secret หรือจาก environment ดู /connect/security-and-operations/

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

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

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

การตรวจหา tier ระหว่างบูตเป็นจุดเดียวที่ nextpdf/premium นำเครื่องมือ Pro และ Enterprise ของตนเข้าสู่ catalog เมื่อมีการติดตั้ง nextpdf/premium ควบคู่ไปกับเซิร์ฟเวอร์

ดูเพิ่มเติม

• /connect/tool-catalog/ — สิ่งที่การค้นพบลงทะเบียนและเหตุผลที่จำนวนแตกต่างกันไป
• /connect/configuration/ — ลำดับการแก้ไขโดยละเอียด
• /connect/deployment/ — การเลือก transport ผ่านโปรไฟล์ RoadRunner
• /transports/mcp/ · /transports/rest/ · /transports/grpc/ — รายละเอียดของแต่ละ transport