أي خادم 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 mcp add pdf123 -- npx -y @pdf123/mcpيقرأ Claude Desktop الملف claude_desktop_config.json، ويقرأ Cursor الملف .cursor/mcp.json. وللعملاء الآخرين صفحة إعدادات MCP أو ملف خاص بها. وكلها تقبل مدخل mcpServers نفسه.
{
"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 | تشغّل أداة واحدة على ملفات محلية وتُرجع المسار المحفوظ أو تقرير JSON | tool و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. ومن دون هذا المتغيّر يُسمح بأي مسار تستطيع عملية الخادم الوصول إليه.
"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 في سطر الأوامر. والأداة التي تُرجع تقريرًا، مثل معلومات المستند، تُرجع التقرير ضمن الردّ نفسه.
{
"path": "/Users/me/Documents/merged.pdf",
"contentType": "application/pdf",
"bytes": 1096
}يعود الاستدعاء الفاشل على هيئة خطأ أداة. وينتهي نصه بأسطر Reason: وCode: وHint: حين يوفّرها الخادم، ليتمكن الوكيل من التفرّع بحسب الرمز.
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. أنشئ مفتاحًا في صفحة المطوّرين.
{
"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 تُرجعه أداة الرفع. واستخدم أداة الوصف للحصول على مخطط عملية واحدة.
صفحات ذات صلة
- مهارات الوكلاء لـ Claude Code وCodex وCursor، واحدة للكتالوج وواحدة لكل أداة
- /llms.txt، فهرس بنص عادي للأدوات وAPI ونقطة نهاية MCP
- سطر أوامر pdfx وTypeScript SDK، وهما يشتركان في الكتالوج نفسه
- نظرة عامة للمطوّرين، ومستند OpenAPI وSwagger UI
- صفحات الأدوات: دمج، ضغط، OCR، حماية، إصلاح
- مقالا "Built for AI Agents, Not Just Browsers" و"Same Operation, Four Clients" في مدونة PDF123
الأسئلة الشائعة
ما هو 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.