MCP समस्या निवारण

Synapse MCP को अपने LLM client के साथ एकीकृत करते समय सामान्य समस्याएँ और समाधान।

त्वरित डायग्नोस्टिक चेकलिस्ट

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. ✅ कॉन्फ़िग परिवर्तन के बाद client पुनः आरंभ किया?
7. ✅ MCP server मैन्युअली शुरू होता है? (npx -y synapse-mcp-api@latest)

समस्या: Client में कोई टूल दिखाई नहीं देता

लक्षण

• Claude Desktop / Cursor / Continue 0 टूल दिखाता है
• MCP servers सूची में कोई 🔌 आइकन या "synapse" एंट्री नहीं

समाधान

1. Client पूरी तरह पुनः आरंभ करें — macOS पर Cmd+Q (केवल विंडो बंद न करें)
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 त्रुटियों के लिए client लॉग जाँचें:
   • Claude Desktop: ~/Library/Logs/Claude/mcp.log (macOS)
   • Cursor: View → Output → MCP
5. स्टार्टअप त्रुटियाँ देखने के लिए MCP server मैन्युअली चलाएँ:

   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. जाँचें कि env var सेट है — stdio ट्रांसपोर्ट के लिए, env var आपके शेल में नहीं, MCP server कॉन्फ़िग में होना चाहिए
4. नई Mind Key प्राप्त करें:

   # Login to get JWT
   curl -X POST .../login -d '{"email":"...","password":"..."}'
   # Create new mind
   curl -X POST .../minds -H "Authorization: Bearer YOUR_JWT" -d '{"name":"new mind"}'

समस्या: npx नहीं मिला

लक्षण

• त्रुटि: "npx: command not found"
• MCP server शुरू होने में विफल

समाधान

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. इंस्टॉल के बाद टर्मिनल पुनः आरंभ करें
3. सत्यापित करें: node --version && npx --version

समस्या: SYNAPSE_URL पहुँच योग्य नहीं

लक्षण

• MCP server शुरू होता है लेकिन टूल कॉल टाइमआउट हो जाते हैं
• त्रुटि: "fetch failed" या "ECONNREFUSED"

समाधान

1. कनेक्टिविटी टेस्ट करें:

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

2. कॉर्पोरेट फ़ायरवॉल जाँचें — आउटबाउंड HTTPS को ब्लॉक कर सकता है
3. वैकल्पिक URL आज़माएँ:
   • Production: https://synapse.schaefer.zone
   • MCP server: https://synapse-mcp.schaefer.zone
4. सेल्फ-होस्टेड के लिए: सुनिश्चित करें कि आपका Synapse इंस्टेंस चल रहा है और पहुँच योग्य है

समस्या: MCP Server क्रैश

लक्षण

• MCP server शुरू होने के तुरंत बाद बाहर निकलता है
• Client लॉग "MCP server disconnected" दिखाते हैं

समाधान

1. त्रुटि देखने के लिए मैन्युअली चलाएँ:

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

2. पोर्ट संघर्ष की जाँच करें — MCP server डिफ़ॉल्ट रूप से पोर्ट 13100 का उपयोग करता है
3. npx कैश साफ़ करें:

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

4. नवीनतम में अपडेट करें:

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

समस्या: टूल कॉल 429 लौटाते हैं

लक्षण

• त्रुटि: "Rate limit exceeded"

समाधान

यह MCP के साथ नहीं होना चाहिए (हेडर auth का उपयोग करता है, कोई रेट लिमिट नहीं)। यदि होता है:

1. जाँचें कि कहीं आप ?key= का उपयोग तो नहीं कर रहे — हेडर auth पर स्विच करें
2. SYNAPSE_URL सत्यापित करें — सुनिश्चित करें कि यह सही इंस्टेंस की ओर इशारा करता है
3. सहायता से संपर्क करें यदि समस्या बनी रहे

समस्या: टूल दिखाई देते हैं लेकिन काम नहीं करते

लक्षण

• Client में टूल सूचीबद्ध हैं
• टूल कॉल करने पर त्रुटि या कोई परिणाम नहीं

समाधान

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. मौजूदा issues जाँचें: https://gitlab.com/schaefer-services/synapse-mcp/-/issues
2. नया issue खोलें इनके साथ:
   • MCP server संस्करण (npx -y synapse-mcp-api@latest --version)
   • Client नाम और संस्करण
   • ऑपरेटिंग सिस्टम
   • संबंधित लॉग अंश
   • पुनः उत्पन्न करने के चरण

अगले कदम

• Claude Desktop Setup
• Claude Code Setup
• API Errors