פרק 8

הודעת שלב שני, חיבור קונקטור ה-MCP

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

בגרסאות GOWA v9 ואילך, שרת ה-MCP אינו תהליך נפרד אלא מוגש ישירות מתוך שרת ה-REST בנתיב /mcp מעל תעבורת HTTP streamable. הפרומפט שלהלן מנחה את קלוד קוד לאתר את פרטי הגישה של המנוע הקיים, לרשום אותו כשרת MCP מקומי פעיל, לקבוע את כללי הבטיחות ולאמת את רשימת הכלים הזמינים.

#כלי ה-MCP הזמינים

במקום 40 כלים נפרדים שהיו בעבר, השרת כולל 5 כלים מאוחדים. סוכני ה-AI בוחרים את הפעולה המבוקשת באמצעות הפרמטר type או action:

כלי	ערכי `type` או `action`
`whatsapp_send`	`text`, `image`, `video`, `audio`, `document`, `sticker`, `location`, `contact`, `poll`, `link`, `forward`
`whatsapp_message`	`react`, `edit`, `revoke`, `delete`, `mark_read`, `mark_played`, `star`, `unstar`, `download_media`
`whatsapp_chat`	`list_chats`, `list_contacts`, `get_messages`, `archive`
`whatsapp_group`	`create`, `join_with_link`, `leave`, `info`, `participants`, `add_participants`, `remove_participants`, `promote`, `demote`, `invite_link`, `set_name`, `set_topic`, `set_settings`, `join_requests`, `manage_join_requests`
`whatsapp_app`	`status`, `login_qr`, `login_code`, `logout`, `reconnect`

בסביבה מרובת מכשירים (multi-device), כותרת X-Device-Id בהגדרת החיבור קובעת את המכשיר עבור כל קריאות הכלים באותו חיבור. אם הכותרת מושמטת, הבחירה חוזרת למכשיר ברירת המחדל. בנוסף, כל קריאה בודדת יכולה לדרוס את הבחירה באמצעות הפרמטר האופציונלי device_id.

#מבנה הגדרת השרת

לקוחות MCP מתחברים ישירות לנתיב /mcp. השרת יורש את הגדרות ה-Basic Auth של שרת ה-REST:

{
  "mcpServers": {
    "whatsapp": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Basic dXNlcjpzZWNyZXQ=",
        "X-Device-Id": "628123456789"
      }
    }
  }
}

שדה headers הוא אופציונלי: כוללים את Authorization רק כאשר מוגדר Basic Auth, ואת X-Device-Id רק בסביבה עם מספר מכשירים. עבור לקוחות מרוחקים שאינם יכולים להעביר כותרת Basic Auth, קיים מנגנון OAuth 2.1 אופציונלי המופעל באמצעות MCP_OAUTH_ENABLED=true ו-MCP_OAUTH_ISSUER_URL.

#הטקסט המלא להעתקה

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

המשימה: לחבר את מנוע ה-GOWA כשרת MCP פעיל בתוך קלוד קוד על המחשב הנוכחי.

הנחיות טכניות לפי GOWA v9:
1. שרת ה-MCP מוגש ישירות מתוך שרת ה-REST בנתיב /mcp מעל תעבורת HTTP streamable. כתובת ברירת המחדל היא http://127.0.0.1:3000/mcp (או לפי הפורט שנקבע ב-APP_PORT, יחד עם APP_BASE_PATH אם הוגדר).
2. השרת דורש כותרת אימות Authorization מסוג Basic Auth אם הוגדר APP_BASIC_AUTH.
3. בריבוי מכשירים, ניתן להגדיר כותרת X-Device-Id לחיבור כולו או להשתמש במכשיר ברירת המחדל.
4. המנוע כולל 5 כלים מאוחדים (whatsapp_send, whatsapp_message, whatsapp_chat, whatsapp_group, whatsapp_app) שבהם הפעולה נבחרת באמצעות שדה type או action.

מה לבצע כעת:
1. אתר את הפורט, שם המשתמש והסיסמה מתוך קובץ ההגדרות המקומי (.env). אל תמציא סיסמה חדשה.
2. הוסף שרת MCP לקלוד קוד תחת השם whatsapp בתעבורת HTTP לכתובת /mcp, כולל כותרת Authorization מתאימה (וכותרת X-Device-Id אם מוגדרים מספר מכשירים).
3. ודא שההגדרות והסיסמאות נשמרות בקבצים מקומיים בלבד ואינן מועלות ל-git.
4. צור או עדכן קובץ CLAUDE.md בתיקיית הפרויקט עם כלל בטיחות מחייב:
   "לפני כל שליחת הודעה או מדיה בוואטסאפ, חובה להציג למשתמש את תוכן ההודעה המדויק ואת שם הנמען, ולהמתין לאישור מפורש בשיחה. אין לבצע שליחה ללא אישור מראש."
5. בצע בדיקת זיהוי כלים (mcp list) והצג לי את רשימת הכלים שנוספו בעברית פשוטה.
6. אל תשלח שום הודעת וואטסאפ כבדיקה. בצע אך ורק בדיקת קריאה שאינה פוגעת בפרטיות (כגון בדיקת סטטוס או ספירת שיחות ללא תוכן).
7. הצג לי משפט בדיקה אחד להעתקה לצורך אימות קריאת נתונים.

#מה קלוד קוד מחזיר בסיום

לאחר ביצוע ההוראות, קלוד יציג:

אישור על הוספת שרת ה-MCP (whatsapp).
פירוט הכלים הזמינים שנרשמו בסביבה.
אישור על כתיבת כלל האישור המוקדם בקובץ CLAUDE.md.
משפט בדיקה פשוט לקריאת נתונים (למשל: "הצג לי את רשימת 5 השיחות האחרונות").

#רענון רשימת הכלים

במידה והכלים אינם מופיעים מיד בחלון השיחה:

הקלידו בשיחה /mcp לבדיקת סטטוס השרתים המחוברים.
במידת הצורך, צאו מקלוד קוד (Ctrl + C) והפעילו אותו מחדש באותה התיקייה (claude).

#מלכודות נפוצות

מלכודת	סיבה והתנהגות	פתרון נכון לפי התיעוד
הרצת פקודת `./whatsapp mcp`	פקודת המשנה `mcp` הוסרה בגרסה 9.	שרת ה-MCP מאוחד בתוך שרת ה-REST. מריצים `./whatsapp rest`.
ניסיון חיבור לנתיב `/sse` בפורט `8080`	נתיב ה-SSE הנפרד בוטל.	מתחברים לנתיב `/mcp` בפורט ברירת המחדל `3000` (או הפורט שהוגדר ב-`APP_PORT`).
נתיב בסיס שגוי בהגדרת כתובת השרת	הוגדר `APP_BASE_PATH` (לדוגמה `/gowa`), אך הלקוח פונה ישירות ל-`/mcp`.	כאשר מוגדר נתיב בסיס, הנתיב המלא של השרת הוא `<base-path>/mcp` (לדוגמה `/gowa/mcp`).
שגיאת אימות (`401 Unauthorized`)	הוגדר `APP_BASIC_AUTH` במנוע אך לקוח ה-MCP לא שלח כותרת אימות.	מוסיפים כותרת `Authorization` עם הערך `Basic <base64(user:pass)>` בהגדרות השרת.
שרת ה-MCP מחזיר שגיאה או אינו זמין	המשתנה `MCP_ENABLED` הוגדר כ-`false` (או הדגל `--mcp-enabled=false`).	מוודאים ש-`MCP_ENABLED=true` (זו ברירת המחדל).
פעולות מבוצעות על המכשיר הלא נכון	קיימים מספר מכשירים מחוברים ולא צוין מזהה מכשיר.	מגדירים כותרת `X-Device-Id` בהגדרות החיבור של שרת ה-MCP, או מעבירים פרמטר `device_id` בקריאה לכלי.

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