เซิร์ฟเวอร์ Python MCP

NextPDF Python SDK มีเซิร์ฟเวอร์ Model Context Protocol (MCP) ที่เผยให้ใช้การสกัด PDF เป็นเครื่องมือแบบเนทีฟสำหรับเอเจนต์ เอเจนต์ที่รองรับ MCP เช่น Claude Code จะลงทะเบียนเซิร์ฟเวอร์เพียงครั้งเดียว แล้วเรียกใช้เครื่องมือ NextPDF ได้แบบเดียวกับเครื่องมืออื่นๆ

เซิร์ฟเวอร์นี้เป็นอะแดปเตอร์แบบบาง เครื่องมือแต่ละตัวจะอ่าน PDF จากดิสก์ภายในเครื่อง เรียกใช้ไคลเอนต์แบบอะซิงโครนัสสำหรับเอนด์พอยต์ NextPDF Connect ของคุณ แล้วส่งคืนผลลัพธ์เป็นสตริง JSON เซิร์ฟเวอร์ไม่เก็บตรรกะทางธุรกิจและไม่จัดเก็บข้อมูลระหว่างการเรียกใช้

ติดตั้ง SDK พร้อม MCP extra ดังนี้:

pip install nextpdf[mcp]

extra mcp จะติดตั้งแพ็กเกจ mcp ต้นทาง (ข้อจำกัด mcp>=1.0,<2.0) เซิร์ฟเวอร์ต้องใช้ Python 3.10 หรือใหม่กว่า

เรียกใช้โมดูลเซิร์ฟเวอร์จากการกำหนดค่าไคลเอนต์ MCP ของคุณ ตัวอย่างด้านล่างอ่านค่าการเชื่อมต่อทั้งสองค่าจากสภาพแวดล้อมของโฮสต์ แทนการฝังข้อมูลลับไว้ในไฟล์การกำหนดค่า (ดู ความปลอดภัย):

{
  "mcpServers": {
    "nextpdf": {
      "command": "python",
      "args": ["-m", "nextpdf.mcp"],
      "env": {
        "NEXTPDF_BASE_URL": "https://connect.example.com",
        "NEXTPDF_API_KEY": "${NEXTPDF_API_KEY}"
      }
    }
  }
}

จุดเข้าใช้งาน python -m nextpdf.mcp จะเรียกใช้ main() ซึ่งเริ่มเซิร์ฟเวอร์ผ่าน standard input/output (stdio) ด้วย asyncio.run(serve()) อย่าสับสนกับ python -m nextpdf เพราะคำสั่งนั้นเรียกใช้อินเทอร์เฟซบรรทัดคำสั่ง (CLI) ไม่ใช่เซิร์ฟเวอร์ MCP

NEXTPDF_BASE_URL และ NEXTPDF_API_KEY เป็นค่าที่จำเป็น เซิร์ฟเวอร์จะสร้างไคลเอนต์แบบ lazy เมื่อมีการเรียกใช้เครื่องมือครั้งแรก หากตัวแปรใดตัวแปรหนึ่งว่างเปล่า เซิร์ฟเวอร์จะส่ง RuntimeError แล้วส่งคืนข้อผิดพลาดนี้ไปยังเอเจนต์เป็นข้อผิดพลาดของเครื่องมือ แทนที่จะทำให้กระบวนการล่ม

แค็ตตาล็อกเครื่องมือและการแมปกับ SDK

เซิร์ฟเวอร์จะลงทะเบียนเครื่องมือแปดตัว ชื่อเครื่องมือทุกตัวใช้คำนำหน้า nextpdf_ เครื่องมือแต่ละตัวจะแมปกับเมท็อดในเนมสเปซ ast ของไคลเอนต์แบบอะซิงโครนัส (AsyncNextPDF.ast) ยกเว้นเครื่องมือแบบประกอบสองตัวที่ระบุไว้ด้านล่าง ซึ่งเซิร์ฟเวอร์จะประกอบจากการเรียกใช้ระดับต่ำกว่า

เครื่องมือ MCP	การเรียกใช้ SDK	หมายเหตุ
`nextpdf_extract_text`	`ast.extract_cited_text(pdf_data, page_index=..., headings_only=...)`	ส่งคืน `CitedTextBlock` เป็นรายการ
`nextpdf_extract_tables`	`ast.extract_cited_tables(pdf_data, page_range=...)`	ส่งคืน `ExtractCitedTablesResponse` เป็นผลลัพธ์
`nextpdf_get_ast`	`ast.get_document_ast(pdf_data, page_range_start=0, page_range_end=..., token_budget=...)`	ส่งคืน `AstDocument` เป็นผลลัพธ์
`nextpdf_info`	`ast.get_document_ast(pdf_data)`	เซิร์ฟเวอร์จะสร้างมุมมองสรุปเมทาดาทา ไม่มีเอนด์พอยต์เฉพาะ
`nextpdf_health`	ไม่มี	ตรวจสอบเฉพาะตัวแปรสภาพแวดล้อม ไม่มีการเรียกใช้เครือข่าย
`nextpdf_search`	`ast.search_ast_nodes(pdf_data, node_type=..., page_index=..., text_query=..., max_results=...)`	ส่งคืน `SearchAstNodesResponse` เป็นผลลัพธ์
`nextpdf_get_outline`	`ast.search_ast_nodes(pdf_data, node_type="heading", max_results=500)`	เซิร์ฟเวอร์จะปรับรูปแบบโหนดหัวข้อให้เป็นโครงร่าง
`nextpdf_diff`	`ast.get_ast_diff(original_pdf_data, modified_pdf_data)`	ส่งคืน `GetAstDiffResponse` เป็นผลลัพธ์

โปรดพิจารณารายละเอียดอินพุตของเครื่องมือเหล่านี้ก่อนเชื่อมต่อเอเจนต์:

อินพุตที่เป็นพาธทั้งหมด (pdf_path, original_pdf_path, modified_pdf_path) เป็นพาธแบบสัมบูรณ์ไปยังไฟล์ บนเครื่องที่เรียกใช้เซิร์ฟเวอร์ เอเจนต์จะส่งพาธ จากนั้นเซิร์ฟเวอร์จะอ่านไบต์ในเครื่อง ไม่มีเครื่องมืออัปโหลด
nextpdf_extract_text จะประกาศฟิลด์ max_pages ไว้ในสคีมาอินพุต แต่ตัวจัดการข้อความไม่ได้ส่งฟิลด์นี้ไปยัง SDK การกำหนดขอบเขตหน้าสำหรับข้อความจะเกิดขึ้นผ่าน page_index (หน้าเดียวที่เริ่มนับจาก 0) ใช้ nextpdf_get_ast ร่วมกับ max_pages เมื่อคุณต้องการจำกัดขอบเขตการเดินผ่านทั้งเอกสาร
nextpdf_get_ast จะแปลง max_pages เป็นช่วงหน้าแบบรวมปลาย [0, max_pages - 1] (ค่าเริ่มต้นของ max_pages คือ 50) ส่ง token_budget เพื่อจำกัดขนาดของทรีที่ส่งคืน
nextpdf_info จะส่งคืน schema_version, source_hash, page_count, estimated_tokens, root_node_type, และ root_children_count ค่าเหล่านี้มาจากโมเดล AstDocument โดยที่ estimated_tokens เป็นพร็อพเพอร์ตีที่คำนวณได้ (ประมาณสี่อักขระต่อหนึ่งโทเค็น)
nextpdf_get_outline จะส่งคืนหนึ่งรายการต่อหนึ่งหัวข้อ พร้อม id, page_index, text, และ depth (อ่านจาก attributes["level"] ของโหนด โดยมีค่าเริ่มต้นเป็น 1) รวมถึง heading_count, total_matches, และ truncated ด้วย

เครื่องมือสกัดแบบอ้างอิงจะแนบ CitationAnchor ไปกับทุกผลลัพธ์ แต่ละ anchor จะมี node_id, page_index, bbox ที่ผ่านการนอร์มัลไลซ์แล้ว (พิกัดอยู่ในช่วง 0.0 ถึง 1.0) และคะแนน confidence (0.0 ถึง 1.0) เอเจนต์ที่ต้องการแหล่งที่มา (provenance) ควรแสดงฟิลด์เหล่านี้ ไม่ใช่แสดงเฉพาะข้อความดิบ

การจัดการข้อผิดพลาด การหมดเวลา และโควตา

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

เงื่อนไข	JSON ที่ส่งคืน
ชื่อเครื่องมือที่ไม่รู้จัก	`{"error": "Unknown tool: <name>"}`
ไฟล์อินพุตหายไป	`{"error": "PDF file not found: <path>"}`
คลาสย่อยของ `NextPDFError` ใดๆ	`{"error": "<message>", "error_type": "<class>", "status_code": <int?>}`
ข้อยกเว้นอื่นใด	`{"error": "Unexpected error: <message>"}`

status_code จะปรากฏเฉพาะเมื่อข้อผิดพลาดต้นทางมีค่านี้เท่านั้น SDK จะแมปการตอบสนอง HTTP ไปยังลำดับชั้นของข้อยกเว้นแบบมีชนิด โดยทั้งหมดมีรากที่ NextPDFError:

ข้อยกเว้น	สถานะ HTTP	`error_code`	เมื่อใด
`NextPDFLicenseError`	402	`license/tier-required`	เอนด์พอยต์ต้องการระดับสิทธิ์การใช้งานฝั่งเซิร์ฟเวอร์ที่สูงขึ้นสำหรับการดำเนินการนี้
`AstNoStructTreeError`	422	`ast/no-struct-tree`	PDF ไม่ได้ติดแท็ก และ heuristic fallback ไม่ได้เปิดใช้งานบนเซิร์ฟเวอร์
`QuotaExceededError`	429	`quota/exceeded`	ถึงขีดจำกัดอัตราหรือโควตา จะมี `retry_after` (วินาที) เมื่อเซิร์ฟเวอร์ส่งเฮดเดอร์ `Retry-After`
`AstBuildTimeoutError`	504	`ast/build-timeout`	การสร้าง AST ใช้เวลาเกินงบประมาณเวลาของเซิร์ฟเวอร์ ลดช่วงหน้าลง
`NextPDFAPIError`	4xx/5xx อื่นๆ	เซิร์ฟเวอร์เป็นผู้กำหนด	ความล้มเหลวในระดับ API อื่นใด

ใช้แนวทางต่อไปนี้สำหรับการผสานรวมกับเอเจนต์:

การหมดเวลา ไคลเอนต์ HTTP ใช้การหมดเวลาเริ่มต้นแบบคงที่: รวม 60 วินาที พร้อมการหมดเวลาในการเชื่อมต่อ 10 วินาที เอกสารที่ช้าหรือมีขนาดใหญ่จะปรากฏเป็น AstBuildTimeoutError (เซิร์ฟเวอร์ยอมแพ้ในการสร้าง AST) หรือเป็นเพย์โหลด Unexpected error จากเลเยอร์ทรานสปอร์ต หากไคลเอนต์เองหมดเวลา เมื่อเห็น ast/build-timeout ให้บอกเอเจนต์ให้จำกัดขอบเขตให้แคบลง: ลด max_pages บน nextpdf_get_ast หรือกำหนด page_index / page_start และ page_end บนเครื่องมือสกัด
โควตาและการถอยกลับ เมื่อเกิด 429 เครื่องมือจะส่งคืน error_type เป็น QuotaExceededError พร้อม status_code 429 ค่า retry_after อยู่บนอ็อบเจกต์ข้อยกเว้น เนื่องจากเซิร์ฟเวอร์ทำซีเรียลไลซ์เฉพาะ error, error_type, และ status_code เท่านั้น เอเจนต์จึงควรมอง 429 เป็นสัญญาณให้หยุดชั่วคราวและลองใหม่ภายหลัง แทนที่จะแยกวิเคราะห์เฮดเดอร์ retry จากเอาต์พุตของเครื่องมือ ให้บังคับใช้โควตาที่เอนด์พอยต์ Connect ไม่ใช่ในเอเจนต์
PDF ที่ไม่ได้ติดแท็ก 422 ast/no-struct-tree หมายความว่า PDF ต้นทางไม่มีทรีโครงสร้าง ให้เปิดใช้งานโหมด heuristic บนเซิร์ฟเวอร์สำหรับเอกสารเหล่านั้น หรือส่งเอกสารไปยังขั้นตอนการติดแท็กก่อนการสกัด

การรักษาความปลอดภัย: การกำหนดขอบเขต API key และสิทธิ์ขั้นต่ำ

ปฏิบัติต่อ API key เสมือนข้อมูลลับ ด้วยความระมัดระวังในระดับเดียวกับรหัสผ่านฐานข้อมูล

อย่าฝังคีย์ไว้ในไฟล์การกำหนดค่า MCP เด็ดขาด ตัวอย่าง JSON ด้านบนอ้างอิงถึง ${NEXTPDF_API_KEY} เพื่อให้ระบบแก้ค่าได้จากสภาพแวดล้อมของโฮสต์หรือตัวจัดการข้อมูลลับ ณ เวลาเริ่มทำงาน ไฟล์การกำหนดค่าอาจถูกคอมมิตเข้าสู่ระบบควบคุมเวอร์ชัน แต่ข้อมูลลับต้องไม่ถูกคอมมิต
กำหนดขอบเขตคีย์ให้เป็นการสกัดแบบอ่านอย่างเดียว เซิร์ฟเวอร์ MCP เรียกใช้เฉพาะพื้นผิวการสกัด AST เท่านั้น (extract_cited_text, extract_cited_tables, get_document_ast, search_ast_nodes, get_ast_diff) เซิร์ฟเวอร์ไม่เรนเดอร์ ไม่ลงนาม ไม่ปกปิด และไม่แก้ไขเอกสาร ให้ออกคีย์แก่เอเจนต์โดยจำกัดขอบเขตฝั่งเซิร์ฟเวอร์ไว้เฉพาะพาธอ่านเหล่านั้น เพื่อให้เอเจนต์ที่ถูกบุกรุกไม่สามารถเข้าถึงการดำเนินการเขียนหรือการดำเนินการระดับสูงกว่าได้
ใช้คีย์เฉพาะแยกตามเอเจนต์ คีย์ต่อหนึ่งเอเจนต์ช่วยให้คุณเพิกถอนหรือหมุนเวียนการผสานรวมรายการหนึ่งได้โดยไม่กระทบรายการอื่น และทำให้บันทึกของเอนด์พอยต์ระบุเจาะจงไปยังเอเจนต์แต่ละรายการได้
จำกัดระบบไฟล์ เนื่องจากทุกเครื่องมืออ่านพาธแบบสัมบูรณ์จากดิสก์ภายในเครื่อง เซิร์ฟเวอร์จึงสามารถอ่านไฟล์ใดก็ตามที่กระบวนการโฮสต์อ่านได้ เรียกใช้เซิร์ฟเวอร์ในฐานะผู้ใช้ที่ไม่มีสิทธิ์พิเศษ จำกัดไดเรกทอรีการทำงานให้อยู่ในโฟลเดอร์เอกสาร และอย่าเรียกใช้ในฐานะบัญชีที่มีสิทธิ์พิเศษเด็ดขาด
เลือกใช้ Transport Layer Security (TLS) ชี้ NEXTPDF_BASE_URL ไปยังเอนด์พอยต์ https:// สำหรับการปรับใช้ที่ไม่ใช่ภายในเครื่องทุกกรณี SDK จะส่งคีย์เป็นโทเค็น Bearer ในเฮดเดอร์ Authorization ดังนั้นการรับส่งแบบ plaintext จะเปิดเผยคีย์ระหว่างทาง

ดู การรักษาความปลอดภัยและการดำเนินงานของ Connect สำหรับการควบคุมฝั่งเอนด์พอยต์ที่รองรับแนวปฏิบัติฝั่งไคลเอนต์เหล่านี้

การทดสอบเซิร์ฟเวอร์ภายในเครื่องก่อนเชื่อมต่อเอเจนต์

ตรวจสอบความถูกต้องของเซิร์ฟเวอร์แบบแยกเดี่ยวก่อนเชื่อมต่อเอเจนต์ การตรวจสอบที่เร็วที่สุดไม่ต้องใช้ PDF และไม่ต้องใช้เครือข่าย:

python -c "from nextpdf.mcp import _tool_definitions; print(len(_tool_definitions()))"

การติดตั้งที่ถูกต้องจะพิมพ์ 8 หากเห็น ImportError ที่กล่าวถึง mcp extra แสดงว่ายังไม่มี dependency แบบเลือกได้นี้ ให้ติดตั้งใหม่ด้วย pip install nextpdf[mcp]

ขั้นต่อไป ให้ทดลองใช้พาธ SDK เดียวกันกับที่เครื่องมือใช้ผ่าน CLI โดย CLI จะสื่อสารกับเอนด์พอยต์ของคุณด้วยตัวแปรสภาพแวดล้อมสองตัวเดียวกัน ตั้งค่าเพียงครั้งเดียว:

export NEXTPDF_BASE_URL="https://connect.example.com"
export NEXTPDF_API_KEY="$(cat /run/secrets/nextpdf_api_key)"

จากนั้นยืนยันเวอร์ชัน การเชื่อมต่อ และการสกัดจริง:

nextpdf version
nextpdf info /path/to/sample.pdf
nextpdf extract text /path/to/sample.pdf --headings-only

nextpdf version ทำงานได้โดยไม่ต้องใช้ข้อมูลรับรอง และยืนยันว่าแพ็กเกจนำเข้าได้ nextpdf info จะทดลองใช้ get_document_ast ซึ่งเป็นการเรียกใช้เดียวกันที่อยู่เบื้องหลัง nextpdf_get_ast และ nextpdf_info หากทั้งสองคำสั่งสำเร็จ แสดงว่าข้อมูลรับรองและเอนด์พอยต์ถูกต้อง และเครื่องมือ MCP ที่ตรงกันจะทำงานได้

หากต้องการขับเคลื่อนโปรโตคอล MCP โดยตรง ให้ใช้ MCP Inspector ต้นทาง (มาพร้อมกับแพ็กเกจ mcp) ชี้ Inspector ไปยังคำสั่งและสภาพแวดล้อมเดียวกันกับที่เอเจนต์ของคุณจะใช้ จากนั้นแสดงรายการและเรียกใช้เครื่องมือด้วยตนเอง ยืนยันว่า nextpdf_health รายงาน status: "ok" เซิร์ฟเวอร์จะส่งคืน misconfigured เมื่อใดก็ตามที่ NEXTPDF_BASE_URL หรือ NEXTPDF_API_KEY ไม่ได้ถูกตั้งค่า วิธีนี้เป็นวิธีที่เร็วที่สุดในการตรวจจับค่าสภาพแวดล้อมที่ขาดหายก่อนที่เอเจนต์จะเรียกใช้เครื่องมือจริง

การตรวจสอบและการดีบักการเรียกใช้เครื่องมือ

เซิร์ฟเวอร์ MCP สื่อสารผ่าน standard input/output (stdio) ดังนั้น standard output จึงนำพาสตรีมโปรโตคอลและต้องคงความสะอาด เซิร์ฟเวอร์ไม่กำหนดค่าการบันทึกล็อกของแอปพลิเคชันเอง ช่องทางสังเกตการณ์หลักของคุณคือเพย์โหลดข้อผิดพลาดของเครื่องมือแบบมีโครงสร้าง, CLI และบันทึกของเอนด์พอยต์ของคุณเอง

เพย์โหลดข้อผิดพลาดของเครื่องมือคือสัญญาณ การเรียกใช้ที่ล้มเหลวทุกครั้งจะส่งคืนอ็อบเจกต์ JSON พร้อม error และสำหรับข้อผิดพลาดของ SDK จะมี error_type และ status_code (ดู การจัดการข้อผิดพลาด) ให้โฮสต์ของเอเจนต์บันทึกเพย์โหลดเหล่านี้ เพย์โหลดเหล่านี้ระบุเครื่องมือที่ล้มเหลวและสาเหตุได้อย่างแม่นยำโดยไม่ต้องใช้การวัดและตรวจสอบเซิร์ฟเวอร์เพิ่มเติม
ทำซ้ำผ่าน CLI ด้วยการบันทึกล็อกแบบดีบัก เซิร์ฟเวอร์ MCP เองไม่ปล่อยล็อก แต่ CLI จะทดลองใช้การเรียกใช้ SDK เดียวกันและมีการบันทึกล็อก ทำซ้ำเครื่องมือที่ล้มเหลวผ่านคำสั่ง CLI ที่ตรงกันด้วย --log-level debug CLI จะบันทึกล็อกไปยัง stderr พร้อมเวลาประทับ และบันทึก traceback แบบเต็มสำหรับข้อผิดพลาดที่ไม่คาดคิด วิธีนี้เป็นวิธีที่ตรงที่สุดในการดูว่าตัวจัดการกำลังทำอะไรอยู่โดยไม่ต้องแนบดีบักเกอร์
Health ในฐานะ probe เรียกใช้ nextpdf_health เพื่อยืนยันว่าเซิร์ฟเวอร์เห็น base URL และ API key ผลลัพธ์จะรายงาน sdk_version, server_url, api_key_configured (ค่าบูลีน ไม่ใช่ตัวคีย์เอง) และ status
การสังเกตการณ์ฝั่งเอนด์พอยต์ เนื่องจากเครื่องมือแต่ละตัวแมปกับคำขอ Connect หนึ่งคำขอ จึงเชื่อมโยงกิจกรรมของเครื่องมือกับบันทึกการเข้าถึงเอนด์พอยต์ตาม API key และเวลาประทับได้ เรียกใช้เอนด์พอยต์ภายใต้การควบคุมการรับรองความถูกต้อง โควตา และการสังเกตการณ์เดียวกันกับที่คุณใช้สำหรับไคลเอนต์บริการอื่นๆ

การแก้ไขปัญหาการผสานรวมกับเอเจนต์ที่พบบ่อย

อาการ	สาเหตุที่เป็นไปได้	การแก้ไข
เซิร์ฟเวอร์เริ่มทำงานไม่สำเร็จพร้อม `ImportError` เกี่ยวกับ `mcp` extra	ยังไม่ได้ติดตั้ง dependency แบบเลือกได้ `mcp`	ติดตั้งด้วย `pip install nextpdf[mcp]` เพื่อแก้ไข
การเรียกใช้เครื่องมือครั้งแรกส่งคืน `{"error": "NEXTPDF_BASE_URL environment variable is required..."}`	บล็อก `env` ของ MCP ไม่ได้ส่ง base URL หรือเชลล์ไม่ได้ขยายค่า `${NEXTPDF_BASE_URL}`	ตั้งค่าตัวแปรในสภาพแวดล้อมของโฮสต์เอเจนต์ และยืนยันว่าตัวเรียกใช้ขยายค่านั้นได้
`nextpdf_health` รายงาน `"status": "misconfigured"`	ตัวแปรที่จำเป็นตัวใดตัวหนึ่งในสองตัวว่างเปล่า	จัดเตรียมทั้ง `NEXTPDF_BASE_URL` และ `NEXTPDF_API_KEY` ให้ครบ
เครื่องมือที่อิงพาธทุกตัวส่งคืน `{"error": "PDF file not found: <path>"}`	เอเจนต์ส่งพาธแบบสัมพัทธ์หรือพาธฝั่งโฮสต์ที่กระบวนการเซิร์ฟเวอร์มองไม่เห็น	ส่งพาธแบบสัมบูรณ์ที่ผู้ใช้ของเซิร์ฟเวอร์อ่านได้ ยืนยันด้วย `nextpdf info <path>` อีกครั้ง
เครื่องมือส่งคืน `error_typeNextPDFLicenseError` (สถานะ 402)	การดำเนินการต้องการระดับสิทธิ์การใช้งานฝั่งเซิร์ฟเวอร์ที่สูงขึ้น	ใช้เอนด์พอยต์และคีย์ที่มีสิทธิ์ในการดำเนินการนี้
เครื่องมือส่งคืน `error_typeAstNoStructTreeError` (สถานะ 422)	PDF ไม่ได้ติดแท็ก และ heuristic fallback ปิดอยู่	เปิดใช้งานโหมด heuristic บนเอนด์พอยต์ หรือติดแท็ก PDF ก่อน
เครื่องมือส่งคืน `error_typeQuotaExceededError` (สถานะ 429)	ถึงขีดจำกัดอัตราหรือโควตา	หยุดชั่วคราวและลองใหม่ เพิ่มโควตาเอนด์พอยต์หากขีดจำกัดต่ำเกินไป
เครื่องมือส่งคืน `error_typeAstBuildTimeoutError` (สถานะ 504) หรือการหมดเวลาของทรานสปอร์ต	เอกสารมีขนาดใหญ่เกินกว่างบประมาณเวลา	จำกัดขอบเขตให้แคบลงด้วย `max_pages`, `page_index`, หรือ `page_start`/`page_end` ก็ได้
เอเจนต์ไม่ลงทะเบียนเครื่องมือ NextPDF เลย	เอเจนต์เรียกใช้ `python -m nextpdf` (CLI) แทน `python -m nextpdf.mcp`	ใช้ `python -m nextpdf.mcp` เป็น `command`/`args` แทน

สำหรับความล้มเหลวในระดับเอนด์พอยต์และการตรวจสอบการปรับใช้ ดู การแก้ไขปัญหา Connect สำหรับการดำเนินการ SDK ที่เครื่องมือเหล่านี้ห่อหุ้มไว้ ให้ดู เอกสารอ้างอิง CLI และ ภาพรวม SDK ประกอบ