استكشاف أخطاء MCP

مشكلات وحلول شائعة عند دمج Synapse MCP مع عميل LLM الخاص بك.

قائمة تشخيص سريعة

1. ✅ Node.js 18+ مثبت؟ (node --version)
2. ✅ Mind Key يبدأ بـ mk_؟ (وليس JWT eyJ...)
3. ✅ Synapse API قابل للوصول؟ (curl https://synapse.schaefer.zone/health)
4. ✅ Mind Key يعمل؟ (curl -H "Authorization: Bearer mk_..." .../memory/recall)
5. ✅ ملف الإعداد JSON صالح؟ (بلا فواصل لاحقة، بلا تعليقات)
6. ✅ العميل أُعيد تشغيله بعد تغيير الإعداد؟
7. ✅ خادم MCP يبدأ يدويًا؟ (npx -y synapse-mcp-api@latest)

المشكلة: لا تظهر أدوات في العميل

الأعراض

• Claude Desktop / Cursor / Continue يُظهر 0 أدوات
• لا أيقونة 🔌 أو إدخال "synapse" في قائمة خوادم MCP

الحلول

1. أعد تشغيل العميل بالكامل — Cmd+Q على macOS (ليس مجرد إغلاق النافذة)
2. تحقق من موقع ملف الإعداد:
   • Claude Desktop macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Claude Desktop Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Cursor: ~/.cursor/config.json
   • Continue: ~/.continue/config.json
3. تحقق من صحة JSON — الصق الإعداد في https://jsonlint.com
4. تحقق من سجلات العميل لأخطاء MCP:
   • Claude Desktop: ~/Library/Logs/Claude/mcp.log (macOS)
   • Cursor: View → Output → MCP
5. شغّل خادم MCP يدويًا لرؤية أخطاء بدء التشغيل:

   SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest

المشكلة: خطأ "Mind Key invalid"

الأعراض

• الأدوات تظهر لكن الاستدعاءات تفشل بـ "401 Unauthorized"
• الخطأ: "Mind Key fehlt oder ungültig"

الحلول

1. تحقق من تنسيق Mind Key — يبدأ بـ mk_، ~40 حرفًا
2. اختبر مباشرة:

   curl -H "Authorization: Bearer mk_YOUR_KEY" \
        https://synapse.schaefer.zone/memory/recall

3. تحقق أن متغير البيئة مُعيين — لنقل stdio، يجب أن يكون متغير البيئة في إعداد خادم MCP، لا في shell الخاص بك
4. احصل على Mind Key جديد:

   # سجل الدخول للحصول على JWT
   curl -X POST .../login -d '{"email":"...","password":"..."}'
   # أنشئ عقلًا جديدًا
   curl -X POST .../minds -H "Authorization: Bearer YOUR_JWT" -d '{"name":"new mind"}'

المشكلة: npx غير موجود

الأعراض

• الخطأ: "npx: command not found"
• خادم MCP يفشل في البدء

الحلول

1. ثبّت Node.js 18+:
   • macOS: brew install node أو نزّل من https://nodejs.org
   • Linux: curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs
   • Windows: نزّل من https://nodejs.org
2. أعد تشغيل الـ terminal بعد التثبيت
3. تحقق: node --version && npx --version

المشكلة: SYNAPSE_URL غير قابل للوصول

الأعراض

• خادم MCP يبدأ لكن استدعاءات الأدوات تنتهي بالمهلة
• الخطأ: "fetch failed" أو "ECONNREFUSED"

الحلول

1. اختبر الاتصال:

   curl https://synapse.schaefer.zone/health

2. تحقق من جدار حماية الشركة — قد يحظر HTTPS الصادر
3. جرّب عنوان URL بديلًا:
   • الإنتاج: https://synapse.schaefer.zone
   • خادم MCP: https://synapse-mcp.schaefer.zone
4. للاستضافة الذاتية: تأكد أن نسخة Synapse الخاصة بك تعمل وقابلة للوصول

المشكلة: خادم MCP ينهار

الأعراض

• خادم MCP يخرج فورًا بعد البدء
• سجلات العميل تُظهر "MCP server disconnected"

الحلول

1. شغّل يدويًا لرؤية الخطأ:

   SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \
     npx -y synapse-mcp-api@latest

2. تحقق من تعارضات المنفذ — خادم MCP يستخدم المنفذ 13100 افتراضيًا
3. امسح ذاكرة npx المؤقتة:

   npx clear-npx-cache
   # أو
   rm -rf ~/.npm/_npx

4. حدّث إلى الأحدث:

   npx -y synapse-mcp-api@latest --version

المشكلة: استدعاءات الأدوات تُرجع 429

الأعراض

• الخطأ: "Rate limit exceeded"

الحلول

هذا لا ينبغي أن يحدث مع MCP (يستخدم مصادقة الترويسة، بلا حد معدل). إذا حدث:

1. تحقق إذا كنت تستخدم ?key= في مكان ما — بدّل إلى مصادقة الترويسة
2. تحقق من SYNAPSE_URL — تأكد أنه يشير إلى النسخة الصحيحة
3. تواصل مع الدعم إذا استمرت المشكلة

المشكلة: الأدوات تظهر لكن لا تعمل

الأعراض

• الأدوات مذكورة في العميل
• استدعاء أداة يُرجع خطأ أو بلا نتيجة

الحلول

1. تحقق من اسم الأداة — يجب أن يكون دقيقًا (مثلًا memory_recall، لا memory.recall)
2. تحقق من المعاملات — تحقق من مخطط إدخال الأداة
3. اختبر عبر API مباشر:

   curl -X POST https://synapse.schaefer.zone/memory \
     -H "Authorization: Bearer mk_..." \
     -H "Content-Type: application/json" \
     -d '{"category":"fact","key":"test","content":"hello"}'

4. تحقق من صحة Synapse:

   curl https://synapse.schaefer.zone/health

الحصول على المساعدة

إذا لم يحل أي مما سبح مشكلتك:

1. تحقق من المشكلات الموجودة: https://gitlab.com/schaefer-services/synapse-mcp/-/issues
2. افتح issue جديدًا مع:
   • إصدار خادم MCP (npx -y synapse-mcp-api@latest --version)
   • اسم العميل وإصداره
   • نظام التشغيل
   • مقتطفات السجلات ذات الصلة
   • خطوات إعادة الإنتاج

الخطوات التالية

• إعداد Claude Desktop
• إعداد Claude Code
• أخطاء الـ API