# استكشاف أخطاء 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 يدويًا** لرؤية أخطاء بدء التشغيل:
   ```bash
   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. **اختبر مباشرة**:
   ```bash
   curl -H "Authorization: Bearer mk_YOUR_KEY" \
        https://synapse.schaefer.zone/memory/recall
   ```
3. **تحقق أن متغير البيئة مُعيين** — لنقل stdio، يجب أن يكون متغير البيئة في
   إعداد خادم MCP، لا في shell الخاص بك
4. **احصل على Mind Key جديد**:
   ```bash
   # سجل الدخول للحصول على 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. **اختبر الاتصال**:
   ```bash
   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. **شغّل يدويًا لرؤية الخطأ**:
   ```bash
   SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \
     npx -y synapse-mcp-api@latest
   ```
2. **تحقق من تعارضات المنفذ** — خادم MCP يستخدم المنفذ 13100 افتراضيًا
3. **امسح ذاكرة npx المؤقتة**:
   ```bash
   npx clear-npx-cache
   # أو
   rm -rf ~/.npm/_npx
   ```
4. **حدّث إلى الأحدث**:
   ```bash
   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 مباشر**:
   ```bash
   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**:
   ```bash
   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](/docs/mcp/claude-desktop)
- [إعداد Claude Code](/docs/mcp/claude-code)
- [أخطاء الـ API](/docs/api/errors)