تخطَّ إلى المحتوى الرئيسي
PPDF123

خوادم PDF123 MCP لوكلاء الذكاء الاصطناعي

MCP، أي بروتوكول سياق النموذج (Model Context Protocol)، معيار مفتوح يتيح لعملاء الذكاء الاصطناعي مثل Claude Code وClaude Desktop وCursor استدعاء أدوات خارجية. يوفّر PDF123 خادم MCP محليًا هو @pdf123/mcp للملفات على جهازك، ونقطة نهاية مستضافة تعمل بمفتاح API.

@pdf123/mcpNode 20.3 أو أحدث

التثبيت

npx -y @pdf123/mcp
في هذه الصفحة

أي خادم MCP أستخدم؟

يتيح الخادمان عمليات PDF123. ويختلفان في مكان التشغيل وفي طريقة وصول الملفات إليهما.

محلي: @pdf123/mcpمستضاف: /mcp
مكان التشغيلعلى جهازك، ويشغّله عميل MCP عبر stdioعلى خوادم PDF123 في https://pdf123.xyz/mcp
المدخلاتمسارات ملفات على القرص. يرفعها الخادم ويحفظ النتيجة بجانب المدخلملفات تُرسل عبر أداة الرفع
بيانات الاعتمادلا شيء للاستخدام المجهول. PDFX_API_KEY اختياريالترويسة X-API-KEY في كل طلب. ومن دونها يكون الردّ 401
التثبيتnpx -y @pdf123/mcpلا شيء. أضف العنوان والترويسة إلى العميل
الأدواتخمس أدوات للكتالوج الكامل المؤلف من 97 أداةسبع أدوات: الوصف والتحويل والصفحات والمتنوعة والأمان والرفع والتنزيل
متى تستخدمهحين يعمل وكيل على مستندات في مجلد محليحين يتولى وكيل أو خدمة مستضافة عمليات الرفع عبر API

استخدم الخادم المحلي لمساعدي البرمجة على الحاسوب المحمول. واستخدم نقطة النهاية المستضافة حين يعمل الوكيل في السحابة ولا يستطيع قراءة قرصك.

كيف أثبّت خادم MCP المحلي؟

لا حاجة إلى تثبيت شيء، لأن عميل MCP يشغّل الخادم عبر npx. في Claude Code أضِفه بأمر واحد.

Claude Codebash
claude mcp add pdf123 -- npx -y @pdf123/mcp

يقرأ Claude Desktop الملف claude_desktop_config.json، ويقرأ Cursor الملف .cursor/mcp.json. وللعملاء الآخرين صفحة إعدادات MCP أو ملف خاص بها. وكلها تقبل مدخل mcpServers نفسه.

MCP client configurationjson
{
  "mcpServers": {
    "pdf123": {
      "command": "npx",
      "args": ["-y", "@pdf123/mcp"]
    }
  }
}

أعد تشغيل العميل بعد تغيير إعداداته. ولتثبيته عامًا على جهازك شغّل npm install -g @pdf123/mcp، فيوفّر الأمر pdf123-mcp. يحتاج الخادم إلى Node 20.3 أو أحدث وإلى عنوان API أساسي يمكن الوصول إليه. ولا يوجد وضع دون اتصال.

ماذا أطلب من الوكيل أولًا؟

اكتب طلبك بلغة عادية وسمِّ الملفات. مثلًا:

ادمج /Documents/a.pdf و/Documents/b.pdf، ثم اضغط الناتج.

يستدعي الوكيل pdf123_run_pipeline، أو pdf123_run_tool مرتين، ويرفع الملفات إلى PDF123، ثم يجيب بمسار الملف المحفوظ. يُحفظ الناتج بجانب المدخل الأول ولا يستبدل ملفًا موجودًا أبدًا. والعمليتان نفسهما متاحتان على الموقع باسم الدمج والضغط.

ما الأدوات التي يوفرها الخادم المحلي؟

للخادم خمس أدوات. معرّفات الأدوات مثل merge وسائط نصية عادية، فتبقى قائمة الأدوات صغيرة.

الأداةوظيفتهاأهم الوسائط
pdf123_list_toolsتسرد الأدوات، سطرًا لكل أداةgroup وquery وformat
pdf123_describe_toolتعرض حقول الأداة وقيمها الافتراضية وقيمها المسموح بها وهل تعمل كدفعةtool
pdf123_run_toolتشغّل أداة واحدة على ملفات محلية وتُرجع المسار المحفوظ أو تقرير JSONtool وfiles وparams وoutput
pdf123_run_pipelineتسلسل حتى 8 أدوات في طلب واحدsteps وfiles وoutput
pdf123_callترسل طلبًا خامًا إلى أي معرّف أداة أو معرّف عملية أو مسار /api/...target وfiles وfields

يستدعي الوكيل عادةً pdf123_list_tools ليعثر على أداة، ثم pdf123_describe_tool ليقرأ حقولها، ثم pdf123_run_tool. وإذا كُتب معرّف خطأً عادت اقتراحات من نوع «هل تقصد».

كيف تعمل الدفعات وكلمات المرور والتسلسلات؟

  • الدفعات. إذا أُعطيت عدة ملفات لأداة ذات ملف واحد، عملت كدفعة بنتيجة لكل ملف. ويُحفظ كل ملف فور انتهائه. والردّ تقرير لكل ملف. وإذا فشل أي ملف كان الردّ خطأً مرفقًا به التقرير، ليعيد الوكيل المحاولة للملفات الفاشلة فقط.
  • كلمات المرور. يفتح input_password كل مدخل مشفّر. ويحدّد passwords كلمة مرور لكل ملف، بالترتيب نفسه في files، مع سلسلة فارغة للملف المفتوح. ويعمل ذلك أيضًا مع الأدوات متعددة الملفات مثل الدمج.
  • التسلسلات. تقبل pdf123_run_pipeline حتى 8 خطوات، وتغذّي كل خطوة التي تليها. وتقبل وسائط كلمات المرور نفسها.
  • الاستدعاءات الخام. تصل pdf123_call إلى عمليات أحدث من الخادم. ولا يجري أي تحقق محليًا.
  • أدوات المرشِّح. الأداة التي يبدأ معرّفها بـ filter- تردّ بـ {"matched": false} حين لا يتحقق شرطها. وهذه نتيجة وليست خطأً.
  • إعادة المحاولة. يعيد idempotencyKey النتيجة الأولى خلال 24 ساعة.

كيف أحدّد المجلدات التي يستطيع الوكيل استخدامها؟

عيّن PDFX_MCP_ROOT على مجلد. افصل بين عدة مجلدات بنقطتين رأسيتين، أو بفاصلة منقوطة على Windows. عندها لا يقرأ الخادم المدخلات ولا يكتب النتائج إلا داخل تلك المجلدات. وتُرفض المسارات خارجها ومحاولات الخروج بـ .. والروابط الرمزية التي تقود إلى الخارج قبل رفع أي شيء، مع Code: path_not_allowed. ومن دون هذا المتغيّر يُسمح بأي مسار تستطيع عملية الخادم الوصول إليه.

Restrict file accessjson
"env": { "PDFX_API_BASE": "https://pdf123.xyz", "PDFX_MCP_ROOT": "/Users/me/Documents/pdfs" }

عيّن متغيّرات البيئة في كتلة env الخاصة بالعميل، أو بالأمر claude mcp add -e NAME=value. ويوجّه PDFX_API_BASE الخادم إلى pdfx-server الخاص بك بدلًا من ذلك؛ راجع الاستضافة الذاتية.

كيف تبدو النتائج والأخطاء؟

النتيجة الواحدة كائن JSON صغير فيه path المحفوظ، وcontentType، والحجم في bytes. ونتيجة الدفعة فيها processed وunmatched وfailed وقائمة files. وتطابق هذه الأشكال مخرجات pdfx --json في سطر الأوامر. والأداة التي تُرجع تقريرًا، مثل معلومات المستند، تُرجع التقرير ضمن الردّ نفسه.

Single resultjson
{
  "path": "/Users/me/Documents/merged.pdf",
  "contentType": "application/pdf",
  "bytes": 1096
}

يعود الاستدعاء الفاشل على هيئة خطأ أداة. وينتهي نصه بأسطر Reason: وCode: وHint: حين يوفّرها الخادم، ليتمكن الوكيل من التفرّع بحسب الرمز.

Error texttext
HTTP 400: This PDF is password-protected. Enter its password.
Reason: password_required
Code: bad_request
Hint: Provide the document password, or unlock the PDF first.

إذا كان في معرّف الأداة خطأ إملائي، يسرد الخطأ معرّفات قريبة وينتهي بـ Code: unknown_tool. والأداة التي لا تجد ما تُرجعه، مثل pdf-to-csv على ملف PDF بلا جداول، تُرجع Code: no_content بدلًا من ملف فارغ. راجع رموز الأخطاء.

كيف أستخدم نقطة نهاية MCP المستضافة؟

تضمّ API خادم MCP على POST https://pdf123.xyz/mcp. صادِق بالترويسة X-API-KEY نفسها التي يستخدمها REST API. ومن دون مفتاح تردّ نقطة النهاية بالرمز 401. أنشئ مفتاحًا في صفحة المطوّرين.

Hosted endpoint configurationjson
{
  "mcpServers": {
    "pdf123": {
      "url": "https://pdf123.xyz/mcp",
      "headers": { "X-API-KEY": "<your-key>" }
    }
  }
}

يسرد الخادم المستضاف سبع أدوات: pdf_toolbox_describe_operation وpdf_toolbox_convert وpdf_toolbox_pages وpdf_toolbox_misc وpdf_toolbox_security وpdf_toolbox_upload وpdf_toolbox_download. تقبل كل أداة من أدوات الفئات اسم operation ومعاملاتها، إضافة إلى ملف أو fileId تُرجعه أداة الرفع. واستخدم أداة الوصف للحصول على مخطط عملية واحدة.

الأسئلة الشائعة

ما هو MCP؟

MCP، أي بروتوكول سياق النموذج، معيار مفتوح لربط عملاء الذكاء الاصطناعي بأدوات خارجية. يشغّل عميل مثل Claude Code خادم MCP أو يتصل به، ويسرد أدواته، ويستدعيها نيابةً عن المستخدم.

هل يعمل خادم MCP المحلي دون اتصال بالإنترنت؟

لا. فهو يرفع الملفات إلى PDF123 API، أو إلى الخادم المحدد في PDFX_API_BASE، ويحفظ النتيجة محليًا. ويجب أن يكون عنوان API الأساسي قابلًا للوصول.

هل يحتاج إلى مفتاح API؟

لا يحتاج الخادم المحلي إلى مفتاح للاستخدام المجهول. عيّن PDFX_API_KEY إذا كان خادمك يتطلب مفتاحًا. أما نقطة النهاية المستضافة على /mcp فتحتاج دائمًا إلى الترويسة X-API-KEY.

هل يستطيع الوكيل قراءة أي ملف على حاسوبي؟

افتراضيًا يستطيع قراءة أي مسار تصل إليه عملية الخادم. عيّن PDFX_MCP_ROOT لحصر القراءة والكتابة في المجلدات التي تختارها.

ماذا يحدث لملفاتي؟

يرفع الخادم المحلي كل مدخل إلى PDF123 API، أو إلى خادمك الخاص، لمعالجته. ويذكر وصف الأداة أن الملفات تُحذف هناك بعد المعالجة. ويُحفظ الناتج على جهازك. وللتفاصيل اقرأ صفحة خصوصية الملفات.

كم أداة يستطيع الوكيل استخدامها؟

يصل الخادم المحلي إلى كل الأدوات الـ 97 في الكتالوج عبر خمس أدوات MCP. أما نقطة النهاية المستضافة فتجمع عملياتها بحسب الفئة (التحويل والصفحات والمتنوعة والأمان) خلف سبع أدوات MCP.