MCP — เอกสารอ้างอิงเชิงลึก

โดยสังเขป

เนมสเปซ NextPDF\Enterprise\Mcp ส่งมอบระดับ Enterprise ของแคตตาล็อกเครื่องมือ MCP ของ NextPDF พื้นผิวสาธารณะประกอบด้วยคลาสเครื่องมือสิบเอ็ดคลาส client factory หนึ่งตัว และ exception ที่มีชนิดหนึ่งตัว เครื่องมือทุกตัวใช้สัญญา NextPDF\Server\Tools\ToolInterface จากรันไทม์ nextpdf/server และประกาศ ToolTier::Enterprise เครื่องมือหกตัววิเคราะห์ PDF เดียวแบบ in-process เครื่องมือสี่ตัวมอบหมายงาน batch และ RAG ให้ Spectrum sidecar ผ่าน NextPDF\Enterprise\Mcp\SpectrumClientFactory เครื่องมือหนึ่งตัวอ่านเส้นทางตรวจสอบการกลายพันธุ์ AST ที่ฉีดผ่าน constructor แทนไบต์ของ PDF เครื่องมือแต่ละตัวอธิบายตัวเองด้วยชื่อ MCP อินพุต JSON Schema client annotations RiskLevel และหมวดหมู่

ความพร้อมใช้งานและการอนุญาต

ความสามารถนี้ส่งมาใน NextPDF Enterprise ( nextpdf/enterprise ) และเปิดใช้งานด้วยซองใบอนุญาตระดับ Enterprise การติดตั้งที่ไม่มีสิทธิ์ดังกล่าวจะไม่โหลดคลาสของความสามารถนี้ เปรียบเทียบรุ่นและรับใบอนุญาต

พื้นผิว API สาธารณะ

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
ForensicAnalyzeTool::execute	array $arguments, InMemoryDocumentStore $store; args: document_id or source	รันการวิเคราะห์เชิงนิติวิทยา: revisions การอัปเดตแบบ incremental ลายเซ็น	ToolResult (JSON report)	Error ToolResult; exception ถูกจับ ไม่ throw ซ้ำ	Tool forensic_analyze; RiskLevel::Safe; อ่านอย่างเดียว idempotent; category document; since 2.0.0
BatchForensicAnalyzeTool::execute	args: workspace_token, documents[] (each id + path)	การวิเคราะห์เชิงนิติวิทยาแบบ batch ผ่าน Spectrum sidecar	ToolResult พร้อม status ต่อเอกสาร จำนวนที่สำเร็จและล้มเหลว	Error ToolResult (อาร์กิวเมนต์ขาด sidecar ล้มเหลว)	Tool batch_forensic_analyze; RiskLevel::Safe; category document; since 2.1.0
ComplianceCheckTool::execute	args: policy (12-value enum), document_id or source	ประเมิน PDF เทียบนโยบายการปฏิบัติตามข้อกำหนดที่ระบุชื่อหนึ่งนโยบาย	ToolResult พร้อม findings ผ่าน/ไม่ผ่าน duration_ms และฟิลด์ disclaimer	Error ToolResult; นโยบายที่ไม่รู้จักคืนข้อผิดพลาดพร้อมรายการคีย์ที่รองรับ	Tool compliance_check; RiskLevel::Review; category document; since 2.0.0
BatchComplianceCheckTool::execute	args: workspace_token, documents[], policies (pdfa, pades, zugferd; default ["pdfa"])	การตรวจการปฏิบัติตามข้อกำหนดแบบ batch ผ่าน Spectrum sidecar	ToolResult พร้อมจำนวนที่ปฏิบัติตาม / ไม่ปฏิบัติตาม	Error ToolResult; ทุกสมาชิก documents[] ถูกตรวจว่ามี id และ path ที่ไม่ว่าง	Tool batch_compliance_check; RiskLevel::Safe; category document; since 2.1.0
LtvHealthCheckTool::execute	args: document_id or source	รันนโยบายสุขภาพ LTV บน PDF ที่ลงลายเซ็น	ToolResult พร้อม findings และผ่าน/ไม่ผ่าน	Error ToolResult	Tool ltv_health_check; RiskLevel::Safe; category document; since 2.0.0
AiReadyCertifyTool::execute	args: document_id or source	การประเมินความพร้อมด้าน AI แบบอ่านอย่างเดียวบนเกณฑ์สี่ข้อ	ToolResult พร้อม certification_level (certified, partial, not_certified) และค่า boolean ต่อเกณฑ์	Error ToolResult	Tool ai_ready_certify; RiskLevel::Review; อ่านอย่างเดียว; category document; since 2.0.0
CertifyAiReadyTool::execute	args: document_id or source, return_stamped_pdf (default true)	ประเมินเกณฑ์สามข้อและผนวกตราแหล่งที่มา XMP	ToolResult; รวม stamped_pdf_base64 เว้นแต่ปิดใช้งานหรือ not_certified	Error ToolResult	Tool certify_ai_ready; RiskLevel::Review; ไม่ใช่อ่านอย่างเดียว; category document; since 3.0.0
AstAwareChunkTool::execute	args: document_id or source, max_chunk_chars (default 1500), overlap_chars (default 150)	สร้าง AST และปล่อยชิ้นที่ยึดการอ้างอิงพร้อมแหล่งที่มา	ToolResult พร้อม chunk_count และ node ID ดัชนีหน้า bbox ชนิด node ต่อชิ้น	Error ToolResult	Tool ast_aware_chunk; RiskLevel::Review; category extraction; since 3.0.0
AuditAstMutationsTool::__construct	AstAuditTrailInterface $auditTrail	ฉีด backend เส้นทางตรวจสอบ	instance	—	dependency ที่ฉีดผ่าน constructor; since 3.0.0
AuditAstMutationsTool::execute	args: document_source_hash (SHA-256 hex, required)	คืนเหตุการณ์การกลายพันธุ์ AST ที่บันทึกไว้ทั้งหมดของเอกสารนั้น	ToolResult พร้อม entries[] และ count	Error ToolResult เมื่ออาร์กิวเมนต์ขาดหรือว่าง	Tool audit_ast_mutations; RiskLevel::Review; category document; since 3.0.0
EmbedDocumentsTool::execute	args: collection_id, workspace_token, documents[] (all required)	นำเข้า PDF สู่คอลเลกชัน RAG ผ่าน Spectrum sidecar	ToolResult พร้อมจำนวนที่สำเร็จ / ทั้งหมด / ล้มเหลว	Error ToolResult	Tool embed_documents; RiskLevel::Caution; ไม่ใช่อ่านอย่างเดียว ไม่ idempotent; category extraction; since 2.1.0
SearchDocumentsTool::execute	args: collection_id, query (required), top_k (default 10, clamped 1–100), mode (hybrid, bm25, semantic)	การดึงข้อมูลแบบ hybrid บนคอลเลกชันที่นำเข้าแล้ว	ToolResult พร้อมชิ้นที่จัดอันดับและคะแนนความเกี่ยวข้อง	Error ToolResult; mode นอก allowlist ถูกปฏิเสธ	Tool search_documents; RiskLevel::Safe; category extraction; since 2.1.0
SpectrumClientFactory::create	none (reads SPECTRUM_URL, SPECTRUM_TIMEOUT, SPECTRUM_AUTH_TOKEN, SPECTRUM_APP_SECRET)	สร้างและแคช client sidecar หนึ่งตัวทั่วทั้งโปรเซส	SpectrumClient	InvalidArgumentException เมื่อ SPECTRUM_URL ผิดรูปหรือชี้ไปที่ที่อยู่ที่ถูกบล็อก	endpoint เริ่มต้น http://127.0.0.1:7800; timeout 30.0 s; since 2.1.0
SpectrumClientFactory::reset	none	ล้างอินสแตนซ์ client ที่แคชไว้	void	—	มีไว้สำหรับการทดสอบ
SpectrumClientFactory::createRequest	string $method, $uri (string or UriInterface)	สร้าง request PSR-7 จากคลาส HTTP ของ Core	RequestInterface	—	การนำ PSR-17 RequestFactoryInterface ไปใช้
SpectrumClientFactory::createStream	string $content = ''	สร้าง stream PSR-7 แบบ in-memory	StreamInterface	—	การนำ PSR-17 StreamFactoryInterface ไปใช้
SpectrumClientFactory::createStreamFromFile	string $filename, string $mode = 'r'	เปิดไฟล์และห่อเป็น stream	StreamInterface	McpStreamException เมื่อเปิดไฟล์ไม่ได้	McpStreamException สืบทอดจาก RuntimeException
SpectrumClientFactory::createStreamFromResource	$resource (PHP resource)	ห่อ resource ที่มีอยู่เป็น stream	StreamInterface	—	การนำ PSR-17 StreamFactoryInterface ไปใช้
McpStreamException	—	ความล้มเหลวในการได้มาซึ่ง stream แบบมีชนิด	—	—	final class สืบทอดจาก RuntimeException; ซอร์สระบุความเข้ากันได้ PSR-17 §1.5; ซอร์สกำกับเป็น @since 3.2.0 (มีอยู่ในสายพัฒนาที่ alias เป็น 3.1.0 ปัจจุบัน)

เครื่องมือทุกตัวยังเปิดเมธอดอธิบายตัวเองของ ToolInterface ได้แก่ name description inputSchema annotations riskLevel tier และ category ค่าต่อเครื่องมือปรากฏในคอลัมน์ Notes ข้างต้น

ลายเซ็นจุดเข้า คัดตรงจากซอร์ส:

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function __construct(private readonly AstAuditTrailInterface $auditTrail)
public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public static function create(): SpectrumClient
public static function reset(): void
public function createRequest(string $method, $uri): RequestInterface
public function createStream(string $content = ''): StreamInterface
public function createStreamFromFile(string $filename, string $mode = 'r'): StreamInterface
public function createStreamFromResource($resource): StreamInterface

สัญญาพฤติกรรม

• เครื่องมือทุกตัวใช้ NextPDF\Server\Tools\ToolInterface และประกาศ ToolTier::Enterprise อย่างชัดเจน Tier ไม่เคยถูกอนุมานจากเนมสเปซหรือการบรรจุแพ็กเกจ
• execute ไม่ throw ทุกความล้มเหลวถูกจับและคืนเป็นข้อผิดพลาด ToolResult ที่พกข้อความความล้มเหลว
• เครื่องมือเอกสารเดียวแปลงไบต์ PDF ด้วยลำดับความสำคัญคงที่ document_id ถูกค้นใน InMemoryDocumentStore ก่อน มิฉะนั้น source จะถูกตีความเป็น data: URI จากนั้นเป็น base64 ดิบ (เกิน 256 ตัวอักษร) จากนั้นเป็นเส้นทางไฟล์
• เส้นทาง source แบบระบบไฟล์ถูกปิดโดยค่าเริ่มต้น จะเปิดใช้งานเมื่อ environment variable NEXTPDF_MCP_INPUT_DIR ระบุไดเรกทอรีอินพุตที่จำกัดเท่านั้น real path ที่แปลงได้ต้องอยู่ภายในไดเรกทอรีนั้น อย่างอื่นล้มเหลวแบบปิด
• สคีมของ stream-wrapper (phar://, php://, file:// และสคีมอื่นใด) และ null byte ใน source แบบเส้นทางไฟล์ถูกปฏิเสธก่อนการเรียกระบบไฟล์ใด ๆ การ traversal และการหลุด symlink ล้มเหลวต่อการตรวจการจำกัดด้วย real path
• เครื่องมือที่หนุนด้วย sidecar (embed_documents, search_documents, batch_compliance_check, batch_forensic_analyze) ได้ client จาก SpectrumClientFactory::create factory ตรวจ SPECTRUM_URL ที่ไม่ใช่ localhost เทียบช่วงที่อยู่แบบส่วนตัวและสงวนไว้ก่อนใช้ อนุญาต localhost ที่ระบุชัดเจนสำหรับโหมด sidecar ในเครื่อง
• ai_ready_certify อนุมานระดับจากเกณฑ์สี่ข้อ: ความสมบูรณ์เชิงนิติวิทยา การมีลายเซ็น ความสมเหตุสมผลของ LTV และการไม่มีการเข้ารหัส ผ่านทั้งสี่ให้ certified; หนึ่งถึงสามให้ partial; ศูนย์ให้ not_certified ความสมบูรณ์เชิงนิติวิทยาเป็นฮิวริสติกเชิงโครงสร้างบนห่วงโซ่ revision ไม่ใช่การตรวจสอบความสมบูรณ์ระดับไบต์เชิงการเข้ารหัส การตรวจการเข้ารหัสตรวจเฉพาะบริเวณ trailer เท่านั้น
• certify_ai_ready ประเมินเกณฑ์สามข้อและผนวกตราแหล่งที่มา XMP ไบต์ที่ประทับตราถูกคืนแบบเข้ารหัส base64 เว้นแต่ return_stamped_pdf เป็น false หรือระดับเป็น not_certified
• compliance_check รับคีย์นโยบายพอดีสิบสองคีย์: pdfa4, pdfa4e, pdfa4f, pades-baseline, ltv-health, eidas-qualified, zugferd, fda-part11, sec-17a4, sec-17a4-compatible, sec-17a4-structural, sec-17a4-pre-sign คีย์ที่ไม่รู้จักคืนผลลัพธ์ข้อผิดพลาดที่ระบุชุดที่รองรับ
• audit_ast_mutations อ่านเฉพาะ AstAuditTrailInterface ที่ฉีดเข้ามา ตัวมันเองไม่บันทึกอะไร

กรณีขอบและโหมดความล้มเหลว

• ไม่ให้ทั้ง document_id และ source: ผลลัพธ์ข้อผิดพลาดสั่งผู้เรียกให้จัดหาอย่างใดอย่างหนึ่ง
• document_id ที่ไม่รู้จัก: ผลลัพธ์ข้อผิดพลาดระบุ ID และชี้ไปที่ create_pdf
• source แบบระบบไฟล์โดยไม่ได้ตั้ง NEXTPDF_MCP_INPUT_DIR: ถูกปฏิเสธพร้อมข้อความระบุช่องทางที่รองรับ
• เส้นทาง source ที่แปลงไปอยู่นอกไดเรกทอรีอินพุตที่กำหนดค่าไว้ รวมถึงผ่าน symlink: ถูกปฏิเสธ การเปรียบเทียบเกิดขึ้นบนขอบเขตตัวคั่นไดเรกทอรี ดังนั้นไดเรกทอรีพี่น้องที่ใช้คำนำหน้าชื่อเดียวกันไม่สามารถผ่านได้
• data: URI ที่ไม่มีตัวคั่นคอมมา หรือ payload base64 ที่ไม่ถูกต้อง: ผลลัพธ์ข้อผิดพลาด
• search_documents top_k นอกช่วง 1–100: ถูก clamp ไม่ปฏิเสธ top_k ที่ไม่ใช่จำนวนเต็มจะย้อนกลับไปใช้ค่าเริ่มต้นของ pipeline ที่กำหนดค่าไว้
• search_documents mode นอก hybrid, bm25, semantic: ผลลัพธ์ข้อผิดพลาดจาก allowlist ของ pipeline
• สมาชิก documents[] ของ batch_compliance_check ที่ขาด id หรือ path หรือพกสตริงว่าง: ผลลัพธ์ข้อผิดพลาดระบุดัชนีที่มีปัญหา batch_forensic_analyze ตรวจเฉพาะรูปทรงของอาร์เรย์ชั้นนอก ข้อบกพร่องของสมาชิกปรากฏจากชั้น batch
• SpectrumClientFactory::create ด้วย SPECTRUM_URL ที่ผิดรูป หรือที่ชี้ไปที่ที่อยู่แบบส่วนตัว link-local หรือ metadata: InvalidArgumentException ภายในการ execute ของเครื่องมือ สิ่งนี้ปรากฏเป็นผลลัพธ์ข้อผิดพลาด
• SpectrumClientFactory::createStreamFromFile บนเส้นทางที่อ่านไม่ได้: McpStreamException
• environment variable ที่ว่างถูกถือเป็นไม่ได้ตั้งค่าและย้อนกลับไปใช้ค่าเริ่มต้น

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

NextPDF ไม่ถือครองการรับรองใด ๆ และไม่มอบให้ เครื่องมือ MCP รายงานการประเมินระดับความสามารถ การรองรับไม่ใช่ความสอดคล้อง และความสอดคล้องไม่ใช่การรับรอง ค่า certification_level ที่คืนโดย ai_ready_certify และ certify_ai_ready เป็นคำศัพท์ที่เครื่องมือรายงานเอง ไม่ถือเป็นการรับรองจากบุคคลที่สาม การตอบสนองของ compliance_check รวมฟิลด์ disclaimer ที่ผลิตโดยรายงานเบื้องล่างด้วยเหตุผลเดียวกัน การอ้างอิงข้อกำหนดนโยบาย เช่น พื้นฐานนโยบาย LTV ที่ซอร์สผลิตภัณฑ์ระบุว่าเป็น ISO 32000-2:2020 §12.8.4.3 ถูกพกในคำอธิบายเครื่องมือและฟิลด์ clause ต่อ finding; หน้านี้ไม่เพิ่มการอ้างมาตรฐานอิสระใด ๆ เอกสารที่ตรวจแล้วเป็นไปตามข้อบังคับหรือไม่ เป็นการวินิจฉัยของผู้ดำเนินการและผู้ประเมินของพวกเขา

บันทึกการพัฒนา

• SpectrumClientFactory::create แคช client หนึ่งตัวต่อโปรเซส เรียก SpectrumClientFactory::reset ในการตั้งค่าการทดสอบเพื่อบังคับให้ได้ client ใหม่
• การอ่าน environment ตรวจ $_ENV จากนั้น $_SERVER จากนั้น getenv และถือสตริงว่างว่าไม่มี
• RiskLevel ขับการจัดการฝั่งโฮสต์ในรันไทม์เซิร์ฟเวอร์: Safe รันอัตโนมัติ Caution ขึ้นไปถูกบันทึกตรวจสอบ และ ApprovalRequired ต้องการการยืนยันจากมนุษย์ ไม่มีเครื่องมือ MCP ของ Enterprise ตัวใดประกาศ ApprovalRequired การ override ของผู้ดำเนินการยกระดับที่ประกาศไว้ให้สูงขึ้นได้ แต่ไม่ลดลง
• ค่า annotations (readOnlyHint, idempotentHint) เป็น hint ของ client MCP ไม่ใช่การบังคับใช้ การจำกัดและการตรวจสอบเกิดขึ้นฝั่งเซิร์ฟเวอร์ไม่ว่ามี hint หรือไม่
• เครื่องมือรายงานค่า category เป็น document หรือ extraction สำหรับการกรอง tools/list
• AuditAstMutationsTool เป็นเครื่องมือเดียวที่ต้องการการฉีดผ่าน constructor; ลงทะเบียนด้วยการนำ AstAuditTrailInterface ไปใช้แบบรูปธรรม

ดูเพิ่มเติม

• MCP (หน้าความสามารถ)
• Accelerator — เอกสารอ้างอิงเชิงลึก — พื้นผิว client ของ Spectrum sidecar
• Forensics — เอกสารอ้างอิงเชิงลึก — ตัววิเคราะห์เบื้องหลัง forensic_analyze
• Compliance — เอกสารอ้างอิงเชิงลึก — นโยบายเบื้องหลัง compliance_check
• AST — เอกสารอ้างอิงเชิงลึก — การแบ่งชิ้นและเส้นทางตรวจสอบการกลายพันธุ์
• Validation — เอกสารอ้างอิงเชิงลึก

ขอบเขตการเผยแพร่

หน้านี้บันทึกเฉพาะพฤติกรรมที่สังเกตได้จากภายนอกและพื้นผิว API สาธารณะที่รองรับเท่านั้น เส้นทางเนมสเปซภายใน คลาสตัวช่วย ตารางกลไก ชื่อไฟล์ runbook และคำนำหน้า ticket อยู่นอกขอบเขต