إعداد خادم PandaNpc MCP لـ Claude Code و Codex

آخر تحديث

يوصّل خادم PandaNpc MCP وكيل البرمجة المتوافق مع MCP بقاعدة معرفة PandaNote وسجلات العمل والمهام المجدولة وإعدادات النماذج ومركز خدمات الوكلاء. يكون مفيدًا عندما يحتاج الوكيل إلى سياق مشروع دائم بدلاً من البدء من محادثة فارغة في كل مرة.

يعمل الخادم محليًا عبر ناقل الإدخال/الإخراج القياسي الخاص بـ MCP. يبدأ عميل MCP عملية pandanpc-mcp عند فتح جلسة؛ ولست بحاجة إلى تعريض منفذ أو تشغيل خادم ويب منفصل.

قبل التثبيت

ستحتاج إلى:

  • Node.js و npm متاحين في نفس البيئة التي يعمل فيها عميل MCP.
  • حساب PandaNpc مع إمكانية الوصول إلى عنوان البريد الإلكتروني المستخدم للتحقق.
  • Claude Code أو OpenAI Codex أو Cursor أو عميل آخر يدعم خوادم MCP المحلية عبر stdio.

إذا أردت أن يقوم الوكيل بجدولة عمل على أحد أجهزتك الخاصة، فثبّت واربط PandaPaw أولاً. لا تتطلب أدوات الملاحظات ومساحات العمل جهاز PandaPaw متصلاً بالإنترنت.

تثبيت خادم MCP أو تحديثه

ثبّت الحزمة على مستوى النظام على macOS أو Linux أو Windows:

bash
npm install -g @pandanpc/mcp-server

تحقق من أن الملف التنفيذي مرئي لواجهة الأوامر الخاصة بك:

bash
pandanpc-mcp --help

نفّذ أمر npm نفسه كلما أردت التحديث. أعد تشغيل عميل MCP بعد أي تحديث لأن العميل الذي يعمل بالفعل يحتفظ بإصدار العملية التي شغّلها في البداية.

راجع سجل إصدارات خادم MCP عندما تختلف أداة أو سلوكها عن لقطة شاشة أو برنامج تعليمي قديم.

إضافة PandaNpc إلى Claude Code

الطريقة الأكثر موثوقية هي أمر الإعداد الخاص بـ Claude Code نفسه. استخدم نطاق المستخدم إذا أردت توفر PandaNpc في كل مشروع:

bash
claude mcp add --scope user pandanpc -- pandanpc-mcp

استخدم --scope project بدلاً من ذلك عندما يجب مشاركة الإعداد عبر المستودع الحالي، أو --scope local عندما يجب أن ينطبق عليك وحدك في المشروع الحالي.

تحقق من الخادم المسجّل:

bash
claude mcp get pandanpc
claude mcp list

يمكنك أيضًا إعداد خادم stdio يدويًا في إعداد MCP الذي يستخدمه تثبيت Claude Code لديك:

json
{
  "mcpServers": {
    "pandanpc": {
      "command": "pandanpc-mcp"
    }
  }
}

إضافة PandaNpc إلى OpenAI Codex

يمكن لـ Codex تسجيل العملية المحلية نفسها من سطر الأوامر:

bash
codex mcp add pandanpc -- pandanpc-mcp

تحقق من الإعداد المحفوظ:

bash
codex mcp get pandanpc
codex mcp list

الإدخال المكافئ في ~/.codex/config.toml هو:

toml
[mcp_servers.pandanpc]
command = "pandanpc-mcp"

أعد تشغيل Codex أو افتح جلسة جديدة بعد إضافة الخادم. إذا كنت تحتفظ بملف إعداد Codex مخصص، فضَع جدول MCP في هذا الملف بدلاً من تكراره عبر ملفات متعددة.

إعداد Cursor وعملاء MCP الآخرين

بالنسبة إلى Cursor، أضف خادمًا محليًا إلى ~/.cursor/mcp.json باستخدام بنية JSON نفسها الموضحة لـ Claude Code. بالنسبة إلى Windsurf والعملاء الآخرين، أنشئ خادم MCP عبر stdio يكون أمره pandanpc-mcp وقائمة وسائطه فارغة.

يجب أن يكون الملف التنفيذي ضمن PATH الذي يرثه التطبيق الرسومي. إذا كان يعمل في الطرفية لكن العميل المكتبي يُبلغ عن "الأمر غير موجود"، فاستخدم المسار المطلق للملف التنفيذي الذي يعيده الأمر التالي:

bash
command -v pandanpc-mcp

على Windows PowerShell، استخدم:

powershell
Get-Command pandanpc-mcp

تسجيل الدخول من الوكيل

تستخدم PandaNpc تدفق تحقق عبر البريد الإلكتروني من خطوتين. اطلب من الوكيل تنفيذ هذه الإجراءات بالترتيب:

  1. استدعاء note_login مع عنوان بريدك الإلكتروني. ترسل PandaNpc رمز تحقق.
  2. استدعاء note_login مرة أخرى مع عنوان البريد الإلكتروني نفسه والرمز.

يتم تخزين بيانات الاعتماد المحلية مؤقتًا، لذا لن تحتاج إلى تسجيل الدخول في كل جلسة. لا تلصق رمز التحقق أبدًا في نص عام أو في مطالبة مشتركة.

التحقق من اتصال MCP

نفّذ اختبارًا صغيرًا للقراءة فقط قبل السماح للوكيل بإنشاء البيانات أو تعديلها:

  1. اطلب منه استدعاء list_workspaces.
  2. اطلب منه استدعاء list_notes لمساحة عمل واحدة.
  3. اطلب منه البحث عن كلمة مفتاحية غير ضارة باستخدام search_notes.

يثبت الاستجابة الناجحة أن عميل MCP شغّل العملية، وأن المصادقة اكتملت، وأن واجهة برمجة تطبيقات الحساب (API) قابلة للوصول. لاختبار الكتابة، أنشئ ملاحظة مؤقتة ثم احذفها حذفًا غير نهائي.

قائمة الأدوات الدقيقة التي يعرضها عميل MCP لديك هي المرجع الأساسي للإصدار المثبّت. الأدوات مجمّعة حول مسارات العمل هذه:

سير العمل الأدوات النموذجية السلوك المهم
الملاحظات list_notes, create_note, read_note, update_note, search_notes update_note يستبدل النص الكامل؛ اقرأ قبل التحرير
سجلات العمل save_done يخزّن العمل المكتمل في مجلد مشروع اليوم تلقائيًا
مساحات العمل list_workspaces, create_workspace, update_workspace مسار المشروع المرتبط يتيح للخادم العثور على مساحة العمل الصحيحة
العمل المجدول list_scheduled_bridges, create_scheduled_task, list_scheduled_task_runs يجب أن يكون جهاز PandaPaw متصلاً بالإنترنت؛ تستخدم تعبيرات cron ستة حقول
المزودون والنماذج list_providers, list_models, أدوات الإنشاء/التحديث/الحذف اعرض القائمة أولاً لتستخدم المعرّفات الحالية وأنواع النماذج الصالحة
القواعد والمهارات sync_rules يزامن تعليمات المشروع المدعومة مع تخطي الملفات غير المتغيرة

لتعريفات حقول المزودين والنماذج، راجع مزودو الذكاء الاصطناعي المخصصون ومفاتيح API. لحدود الحساب والفوترة، راجع حسابات PandaNpc والخطط وتكاليف API.

ممارسات التشغيل الآمنة

  • ابدأ بأدوات القائمة أو القراءة أو البحث قبل إجراءات الإنشاء أو التحديث أو الحذف أو الجدولة.
  • اقرأ الملاحظة قبل تحديثها لأن تحديثات الملاحظات تستبدل مستند Markdown بالكامل بدلاً من تطبيق تصحيح جزئي.
  • تعامل مع المطالبات المجدولة على أنها طلبات تنفيذ كود: تأكد من الجهاز المستهدف ومجلد العمل والمنطقة الزمنية وتعبير cron ذي الحقول الستة.
  • أبقِ مفاتيح API الخاصة بالمزودين خارج المطالبات والملاحظات. أدخل الأسرار فقط عبر تدفق إعداد المزود المخصص لذلك.
  • راجع بطاقة الموافقة على أدوات MCP قبل السماح بإجراءات تدميرية أو خارجية.
  • استخدم save_done لسجلات العمل بدلاً من تخمين مساحة العمل ومجلد التاريخ الصحيحين يدويًا.

استكشاف الأخطاء وإصلاحها

يقول العميل إنه لم يتم العثور على `pandanpc-mcp`

افتح طرفية جديدة بعد التثبيت وتحقق من مسار الملف التنفيذي. ترث تطبيقات سطح المكتب أحيانًا PATH أقدم؛ عليك إعداد المسار المطلق أو إعادة تشغيل التطبيق. إذا تم تثبيت npm عبر مدير إصدارات، فتأكد من أن عميل MCP يبدأ تحت نفس المستخدم والبيئة.

الخادم مسجّل لكن لا تظهر أي أدوات

أعد تشغيل العميل، ثم افحص claude mcp get pandanpc أو codex mcp get pandanpc. أزل الإدخال وأعد إضافته إذا كان الأمر خاطئًا. وتحقق أيضًا من أنك لم تُعدّ عملية stdio المحلية كعنوان HTTP URL.

تقول الأدوات إنك غير مصادَق

كرر استدعاءَي note_login. استخدم أحدث رمز تحقق، وتفقد مجلد الرسائل غير المرغوبة، وتأكد من أن كلا الاستدعاءين يستخدمان عنوان البريد الإلكتروني نفسه.

لا يمكن للمهام المجدولة العثور على جهاز

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

تحديث ملاحظة أزال نصًا موجودًا

يقبل update_note النص البديل الكامل. استعد الملاحظة من سجلها أو سلة المهملات حيثما كان ذلك متاحًا، ثم اقرأ المحتوى الحالي وقدّم المستند المدمج.

هل تحتاج مساعدة خاصة بحسابك؟ تواصل مع support@pandanpc.com مع ذكر اسم عميل MCP ونظام التشغيل وإصدار الحزمة ورسالة الخطأ الدقيقة دون تضمين أي أسرار.