Pro الإصدار

‏⁨MCP Tools⁩ — مرجع متعمّق

التوافر والترخيص

تُشحَن هذه القدرة في ‏⁨NextPDF Pro⁩ (nextpdf/pro) وتُفعَّل بمغلّف ترخيص من طبقة ⁨Pro⁩. والنشر الذي يفتقر إلى ذلك الاستحقاق لا يُحمِّل أصناف القدرة. قارِن الإصدارات واحصل على ترخيص.

لا توجد علامة ترخيص لكل ميزة. تُشحَن الشيفرة مع إصدار ⁨Pro⁩، وتُسجَّل الأدوات الثماني تحت طبقة pro عندما تُحَلّ حزمة ⁨Pro⁩ عند الإقلاع جنبًا إلى جنب مع nextpdf/server.

عقد السلوك

يكتشف ⁨NextPDF Server⁩ الطبقات عند الإقلاع بفحصه عن صنف مزوِّد أدوات ⁨Pro⁩؛ فإذا حُلَّ، يُسجِّل الخادم الأدوات الثماني تحت طبقة pro. وحزمة ⁨Pro⁩ ليست اعتمادية صارمة للخادم، لذا فأدوات ⁨Pro⁩ اختيارية تمامًا بالتثبيت المشترك. وتسجيل الطبقات مستقلّ: طبقة مفقودة أو مستبعَدة بالسياسة لا تحجب الأخريات أبدًا.
تُعلِن كل أداة عن واحد من أربعة مستويات مخاطرة (آمن، تنبيه، مراجعة، يتطلّب موافقة). ولا يمكن لتجاوز اختياري من المُشغِّل إلّا رفع مستوى الأداة، لا خفضه أبدًا؛ ويُسجِّل الخادم في سجلّ التدقيق أي تنفيذ عند مستوى تنبيه أو أعلى. وsign_pdf يتطلّب موافقة.
يُحَلّ مدخل ⁨PDF⁩ بترتيب ثابت: document_id من المخزن في الذاكرة، ثم source بوصفه مُعرِّف موارد منتظمًا data:، أو مسار نظام ملفّات، أو ⁨base64⁩ خام. والمدخل المفقود يُرجِع خطأ تحقّق بدل معالجة مستند فارغ.
يُنتِج sign_pdf توقيع ⁨PAdES B-B⁩ أساسيًا فقط — بلا طابع زمني، وبلا تحقّق طويل الأمد. والخوارزميات المدعومة ومغلّف نقل المفتاح ⁨AES-GCM⁩ مفصَّلة أدناه؛ ويفشل فكّ التشفير مغلقًا ولا تستخدم الأداة النصّ المُشفَّر مادةً للمفتاح أبدًا.
راجِع الأقسام أدناه للاطّلاع على التفاصيل الكاملة للاكتشاف والمخاطرة وحلّ المصدر وكل أداة والتوقيع. تصف هذه الصفحة السلوك القابل للملاحظة خارجيًا وعقد الأداة المنشور فقط.

النطاق

هذه الصفحة هي مرجع المُشغِّل والمُكامِل لأدوات ⁨Pro MCP⁩ الثماني. تغطّي نموذج الاكتشاف، ودلالات المخاطرة/إشراك الإنسان (‏⁨HITL⁩) التي يطبّقها الخادم، وقواعد حلّ المصدر، ومغلّف نقل مفتاح التوقيع، وسلوك فشل كل أداة. وتصف السلوك القابل للملاحظة خارجيًا وعقد الأداة المنشور فقط. وللاطّلاع على الفهرس الموجَّه للمستخدم، راجِع صفحة ⁨MCP⁩ العامة.

نموذج الاكتشاف والتسجيل

يكتشف ⁨NextPDF Server⁩ مزوِّدي الطبقات عند الإقلاع. ويكشف طبقة ⁨Pro⁩ بفحصه عن صنف مزوِّد أدوات ⁨Pro⁩؛ فإذا حُلَّ الصنف، يُنشئ الخادم المزوِّد ويُسجِّل كل أداة يُرجِعها تحت طبقة pro. وحزمة ⁨Pro⁩ ليست عمدًا اعتمادية صارمة للخادم — وهذا يُبقي الخادم المفتوح المصدر قابلًا للتثبيت دون الحزمة المملوكة، ويجعل أدوات ⁨Pro⁩ اختيارية تمامًا بالتثبيت المشترك.

يعزل الخادم التسجيل لكل طبقة. فإذا كانت حزمة ⁨Pro⁩ غائبة، تظلّ أدوات ⁨Core⁩ مُسجَّلة؛ ومزوِّد طبقة حاضر لا يحجب طبقات أخرى. كما يخضع تسجيل الأدوات لقائمة سماح سياسة أمان الخادم: أداة مستبعَدة بالسياسة لا تُسجَّل بصمت ولا تُحتسَب في ملخّص الطبقة. ويكشف الخادم عددًا لكل طبقة (‏⁨core⁩ / ⁨pro⁩ / ⁨enterprise⁩) للتشخيص والتسجيل.

يُرجِع المزوِّد الأدوات الثماني بترتيب ثابت: استخراج النص، والتقطيع، والمقارنة، وحجب البيانات الشخصية، وتعبئة النموذج، وقراءة النموذج، وتحليل الوصولية، والتوقيع. والترتيب مستقرّ لكن على المُستدعِين ألّا يعتمدوا عليه — حُلّ الأدوات باسمها في بروتوكول ⁨MCP⁩.

نموذج المخاطرة ودلالات ⁨HITL⁩

تُعلِن كل أداة عن واحد من أربعة مستويات مخاطرة. ويستخدم الخادم المستوى المُعلَن لإنفاذ إشراك الإنسان:

آمن — للقراءة فقط، بلا آثار جانبية. يُنفَّذ تلقائيًا.
تنبيه — يُنشئ حالة في الذاكرة أو يعدّلها. يُنفَّذ تلقائيًا مع مدخل في سجلّ التدقيق.
مراجعة — يُنتِج مخرَجًا قد يُساء استخدامه. يُنفَّذ تلقائيًا، لكن تعليمات مهارة الوكيل تُعلِّمه فيُنذِر المستخدم.
يتطلّب موافقة — مدمِّر أو قانوني أو حرِج للخصوصية. يطلب الخادم تأكيدًا بشريًا صريحًا قبل التنفيذ.

تصنيفات أدوات ⁨Pro⁩: أدوات الاستخراج/التحليل الخمس (extract_text، segment_document، compare_pdfs، extract_form_data، check_accessibility) آمنة؛ وredact_pii وfill_form مراجعة؛ وsign_pdf يتطلّب موافقة.

يأتي مستوى المخاطرة من مصدرين اثنين بالضبط: إعلان الأداة نفسها، وتجاوز اختياري من المُشغِّل في وقت التشغيل. ولا يمكن للتجاوز إلّا رفع مستوى مخاطرة الأداة (إحكام الإنفاذ)؛ ولا يمكنه خفضه أبدًا. ويُسجِّل الخادم في سجلّ التدقيق أي تنفيذ عند مستوى تنبيه أو أعلى. ويحمل نموذج المخاطرة إصدارًا؛ ويُعلِن الخادم عن ذلك الإصدار في استجابة تهيئته ليكتشف العملاء أي تغيير غير متوافق.

ترتيب حلّ المصدر

تقبل كل أداة تأخذ مستند ⁨PDF⁩ المدخلَ عبر واحد من ثلاثة أشكال مدخل، تُحَلّ بهذا الترتيب:

document_id — يسترجع الخادم البايتات من مخزن مستنداته في الذاكرة. ومُعرِّف غير معروف يفشل بخطأ صريح يوجّه المُستدعِي إلى إنشاء المستند أولًا.
source بوصفه مُعرِّف موارد منتظمًا data: — تفكّ الأداة جسم ⁨base64⁩ بعد الفاصلة.
source بوصفه مسار نظام ملفّات — تقرأ الأداة من القرص عندما يُحَلّ المسار إلى ملف.
source بوصفه سلسلة ⁨base64⁩ خام — تقبل الأداة وتفكّ المدخل الطويل بما يكفي والمُشكَّل على هيئة ⁨base64⁩ فقط.

يطبّق compare_pdfs الحلّ نفسه مستقلًّا على source_a وsource_b، ويقبل إضافيًا قيمة document_id في أي من خانتي المصدر. وإذا لم تُقدَّم لا document_id ولا source، تُرجِع الأداة خطأ تحقّق بدل معالجة مستند فارغ.

مرجع كل أداة

الأداة	المخاطرة	المدخلات	حقول النتيجة	الحدّ السلوكي
`extract_text`	آمن	⁨PDF⁩؛ `page_start` / `page_end` اختياريان بفهرسة تبدأ من 1	النص، إجمالي عدد الصفحات	طبقة النص فقط؛ النطاقات محدودة بعدد الصفحات الفعلي؛ بلا ⁨OCR⁩
`segment_document`	آمن	⁨PDF⁩	عدد المقاطع، قائمة المقاطع	مقاطع مشتقّة من التخطيط؛ ليست شجرة بنية ⁨PDF⁩ موسومة
`compare_pdfs`	آمن	مستندا ⁨PDF⁩	علامة التطابق، إجمالي التغييرات، عدد صفحات كل مستند، المناطق (النوع، النص، فهرس الصفحة، فهرس السطر، نص النظير الاختياري)	مقارنة محتوى نصّي؛ ليست مرئية ولا ثنائية
`redact_pii`	مراجعة	⁨PDF⁩؛ `types` اختيارية (`email`، `phone`، `ssn`، `credit_card`)	علامة وجود بيانات شخصية، العدد المكتشَف، النص المحجوب، الأنواع المفحوصة	كشف/حجب على طبقة النص؛ ليس حجبًا مرئيًا؛ قائم على الأنماط، لا شامل
`fill_form`	مراجعة	خريطة `fields`؛ `pdf_filename` اختياري	مستند ⁨XFDF⁩، عدد الحقول	يُنتِج ⁨XFDF⁩ (ISO 19444-1)؛ لا يكتب القيم في ⁨PDF⁩
`extract_form_data`	آمن	⁨PDF⁩	عدد الحقول، خريطة الحقول، ملاحظة صريحة عند عدم وجودها	يقرأ ⁨XFDF⁩ المُضمَّن فقط
`check_accessibility`	آمن	⁨PDF⁩	درجة بنيوية (0–100)، المشكلات، ملخّص المقاطع	إرشاد بنيوي بمراجع ⁨WCAG⁩؛ ليس حُكم مطابقة
`sign_pdf`	يتطلّب موافقة	⁨PDF⁩؛ شهادة ⁨PEM⁩ + مفتاح ⁨PKCS#8⁩؛ الخوارزمية واسم المُوقِّع والسبب ومغلّف النقل اختيارية	⁨PDF⁩ موقَّع، عدد التواقيع، علامة الإنجاز، الخوارزمية، ⁨OID⁩، الملخّص	⁨PAdES B-B⁩ أساسي فقط؛ بلا طابع زمني، بلا ⁨LTV⁩

التوقيع: الخوارزميات ونقل المفتاح

يُنتِج sign_pdf توقيع ⁨PAdES B-B⁩ أساسيًا. الخوارزميات المدعومة، المقبولة بالتهجئة بالشرطة السفلية والشرطة معًا:

‏⁨RSA⁩ مع ⁨SHA-256⁩ (الافتراضي).
‏⁨RSA⁩ مع ⁨SHA-3 256⁩ / ⁨384⁩ / ⁨512⁩ — يتطلّب بناء ⁨OpenSSL⁩ بدعم ⁨SHA-3⁩.
‏⁨Ed25519⁩ — يتطلّب امتداد ⁨libsodium⁩؛ ويجب أن يكون المفتاح ⁨PKCS#8 PEM⁩ يغلّف مفتاح ⁨Ed25519⁩ الخاص.

ترفض الأداة المُعرِّفات غير المدعومة وتُرجِع قائمة القيم المقبولة.

يتيح مغلّف تشفير النقل الاختياري للمُستدعِي تمرير المفتاح الخاص عبر نقل ليس سرّيًا من طرف إلى طرف. والمغلّف ⁨AES-GCM⁩ فقط:

مفتاح متماثل: 16 أو 24 أو 32 بايتًا (‏⁨AES-128/192/256⁩)، مُرمَّز بترميز ⁨base64⁩.
‏⁨Nonce⁩: 12 بايتًا بالضبط، مُرمَّز بترميز ⁨base64⁩.
بيانات مُصادَق عليها إضافية اختيارية، مُرمَّزة بترميز ⁨base64⁩.
حمولة private_key هي نصّ ⁨base64⁩ المُشفَّر مع علامة مصادقة ⁨GCM⁩ لاحقة بحجم 16 بايتًا.

يفشل فكّ التشفير مغلقًا: عدم تطابق علامة المصادقة أو حمولة مُشوَّهة يُرجِع خطأ فكّ تشفير، ولا تستخدم الأداة النصّ المُشفَّر مادةً للمفتاح أبدًا. وترفض الأداة أحجام المفتاح أو ⁨Nonce⁩ الخاطئة قبل أي عمل تشفيري.

الحالات الحدّية ووضع ⁨FIPS⁩

extract_text: تحدّ الأداة نهاية نطاق الصفحات التي تتجاوز المستند بدل رفضها، وتُسوّي بدايةً دون الصفحة الأولى إلى الصفحة الأولى.
compare_pdfs: source_a أو source_b مفقود يُرجِع خطأ تحقّق؛ والمستندات المتطابقة تُرجِع نتيجة تطابق صريحة بصفر تغييرات.
extract_form_data: مستندات ⁨PDF⁩ بلا تدفّق ⁨XFDF⁩ مُضمَّن تُرجِع نتيجة بصفر حقول مع ملاحظة تفسيرية، لا خطأ.
redact_pii: مدخل غير معروف في types يُتجاهَل؛ وقائمة كلها غير معروفة تُنتِج فحصًا فارغًا بدل فشل.
sign_pdf: شهادة أو مفتاح خاص مفقود يفشل قبل أي عمل توقيع؛ وتفحص الأداة متطلّبات الخوارزمية (دعم ⁨SHA-3⁩ في ⁨OpenSSL⁩، و⁨libsodium⁩ لـ‏⁨Ed25519⁩) عند التوقيع وتُبرِزها أخطاءً صريحة.
وضع ⁨FIPS⁩: تتبع توافرية الخوارزمية بناء ⁨OpenSSL⁩/⁨libsodium⁩ على المضيف. وفي بناء مُقيَّد بـ‏⁨FIPS⁩، تفشل الخوارزميات غير المعتمَدة عند الحدّ التشفيري بخطأ صريح بدل الخفض بصمت. ولا تضيف طبقة ⁨MCP⁩ سياسة تشفيرية ولا تُرخّيها — بل تُبرِز قرار مزوِّد التشفير على المضيف.

ملاحظات دليل تشغيل المُشغِّل

أبقِ sign_pdf متطلِّبًا للموافقة. تأكّد من عدم وجود تجاوز من المُشغِّل يرفع المخاطرة على الأدوات الآمنة دون قصد — فالتجاوزات تُحكِم فقط، لذا فالتجاوز العَرَضي يُضعِف التوافرية، لا الأمان.
الاحتفاظ بالتدقيق: كل تنفيذ عند مستوى مراجعة أو أعلى يُسجَّل في سجلّ التدقيق بواسطة الخادم. قَدِّر حجم احتفاظك بالسجلّ لحجم نداءات redact_pii وfill_form وsign_pdf.
اختيار النقل: عند التشغيل عبر نقل ليس سرّيًا من طرف إلى طرف، اطلب مغلّف نقل مفتاح ⁨AES-GCM⁩ لـsign_pdf وعامِل مادة المفتاح الخاص سرًّا في سياسة تسجيل نداءات الأدوات لدى وكيلك.
أعداد الطبقات: استخدم عدد الخادم لكل طبقة لتؤكّد عند النشر أنّ طبقة ⁨Pro⁩ سجّلت ثماني أدوات؛ والعدد صفر يدلّ على أنّ حزمة ⁨Pro⁩ لم تُحَلّ.

حدود الإصدار

تسهم طبقة ⁨Pro⁩ بثماني أدوات ⁨MCP⁩ بالضبط. ويشحن إصدار ⁨Enterprise⁩ طبقة ⁨MCP⁩ منفصلة بأدواتها الخاصة — الامتثال، والتحليل الجنائي، وصحّة التحقّق طويل الأمد، والاعتماد الجاهز للذكاء الاصطناعي، وبحث المستندات/تضمينها. ومدخلات أدوات ⁨Enterprise⁩ ومخرجاتها ودواخلها خارج النطاق هنا وموثَّقة مع إصدار ⁨Enterprise⁩. ويكتشف الخادم الطبقات مستقلًّا؛ وطبقة مفقودة لا تعطّل أخرى أبدًا.

حدود النشر

توثّق هذه الصفحة السلوك القابل للملاحظة خارجيًا وسطح ⁨API⁩ العام المدعوم فقط. أما مسارات فضاء الأسماء الداخلية، والأصناف المساعِدة، وجداول الآليات، وأسماء ملفّات دليل التشغيل، وبادئات التذاكر فخارج النطاق.