פרק 12

אבחון

כאשר שרת MCP אינו מגיב, נכשל בעלייה או שהכלים שלו אינם מופיעים בשיחה, אין צורך לנחש. פרוטוקול MCP וכלי המארח מספקים כלים מובנים לבדיקת שפיות ודיאגנוסטיקה מקיפה.

#מתודולוגיית אבחון שלב אחר שלב

פעלו לפי ארבעת השלבים הבאים כדי לאתר את מקור הבעיה:

[שלב 1: בדיקת סטטוס CLI] ---> grok mcp list / doctor / claude mcp list
            |
            v
[שלב 2: בדיקת TUI]       ---> בדיקת /mcps או /mcp (האם מספר הכלים > 0?)
            |
            v
[שלב 3: הרצה ידנית בטרמינל] -> הפעלת פקודת ה-stdio ידנית ב-Shell
            |
            v
[שלב 4: בדיקת לוגים מלאה] -> קריאת קובצי stderr.log ולוגי Debug

#שלב 1: בדיקת סטטוס מפקודת המעטפת

ב-Grok CLI:

# הצגת כל השרתים והאם הם פעילים
grok mcp list

# הרצת בדיקת בריאות וחיבורים מקיפה
grok mcp doctor

# בדיקת מקור ההגדרות של כל שרת
grok inspect

ב-Claude Code:

# בדיקת רשימת השרתים המחוברים
claude mcp list

# הצגת פרטי הגדרה של שרת בודד
claude mcp get <server_name>

#שלב 2: בדיקה אינטראקטיבית ב-TUI

ב-Grok CLI: הקלידו /mcps. ודאו שהשרת מופיע בצבע ירוק (פעיל), שמופיע מספר כלים הגדול מאפס, ושלא מופיעה הודעת שגיאה באדום.
ב-Claude Code: הקלידו /mcp. ודאו שהשרת מוצג ושהכלים שלו נטענו בהצלחה.

#שלב 3: בידוד והרצה ידנית של פקודת ה-stdio

אם שרת stdio מקומי מסרב לעלות, העתיקו את פקודת ההרצה המדויקת והריצו אותה ישירות בטרמינל שלכם:

# הרצה ידנית כדי לחשוף שגיאות Node/Python או תלויות חסרות
npx -y @modelcontextprotocol/server-postgres postgresql://user:pass@localhost:5432/db

אם הפקודה קורסת עם הודעת שגיאה (לדוגמה Cannot find module, שגיאת הרשאות בקובץ או חיבור שנכשל למסד הנתונים), תראו מיד את הסיבה האמיתית בטרמינל.

#שלב 4: בחינת קובצי הלוג של המערכת

גרוק שומר את כל הודעות השגיאה (stderr) של כל שרת מקומי בקובץ לוג נפרד:

# מעקב חי אחר הלוג של שרת מסוים
tail -f ~/.grok/logs/mcp/filesystem.stderr.log

להפעלת לוג דיבאג מלא של גרוק הכולל את כל הודעות ה-JSON-RPC שנשלחות ומתקבלות:

GROK_LOG_FILE=/tmp/grok.log RUST_LOG=debug grok

לאחר מכן פתחו את /tmp/grok.log וחפשו שורות המכילות mcp.

#תרחישי כשל נפוצים והפתרונות המדויקים

#1. שגיאת Timeout בעליית השרת (Cold Start של `npx`)

הסימפטום: השרת נכשל בעלייה עם הודעה על פקיעת זמן (Timeout).
הסיבה: בפעם הראשונה שמריצים חבילת npx, ההורדה מהרשת עשויה לקחת 10-15 שניות, מעבר לזמן ההמתנה כברירת מחדל.
הפתרון: הגדילו את זמן ההמתנה בקובץ config.toml:

[mcp_servers.my_server]
startup_timeout_sec = 30

#2. השרת עלה אך מופיעים 0 כלים (Empty Tool List)

הסימפטום: השרת רשום כמחובר, אך המודל אינו מוצא אף כלי.
הסיבה:

תהליך ה-Handshake מול השרת נכשל.
נדרש אימות OAuth שטרם הושלם.
הפתרון:

היכנסו ל-/mcps ולחצו על מקש i להשלמת תהליך האימות בדפדפן.
לחצו על מקש r לרענון וטעינה מחדש של הכלים.

#3. שגיאות HTTP 401 Unauthorized או 403 Forbidden

הסימפטום: שרת HTTP מרוחק מחזיר שגיאת הרשאה.
הסיבה: טוקן ה-API שהוגדר בכותרת פג תוקף, או שהאימות מול ספק ה-OAuth נדרש לרענון.
הפתרון: בדקו את ערך הכותרת Authorization: Bearer <TOKEN> או מחקו את הטוקן הישן מ-~/.grok/mcp_credentials.json ובצעו התחברות מחודשת.

#4. חסימת Cloudflare WAF (שגיאה 1010 או חסימת בוטים)

הסימפטום: שרת HTTP מחזיר דף HTML של Cloudflare במקום JSON-RPC.
הסיבה: חומת האש של Cloudflare מזהה את בקשת הסוכן כבוט אוטומטי ללא דפדפן.
הפתרון: הוסיפו כותרת User-Agent תקינה בהגדרות השרת:

headers = { "User-Agent" = "Mozilla/5.0 (compatible; MyMCPClient/1.0)" }