🔌 פרק 8

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

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

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

התיעוד הרשמי המפורט עוקב אחרי הענף main הממוזג, כולל שינויים שאחרי v9.7.0. כשמשתמשים בבינארי או בתג קונטיינר נעול, בודקים את הערות השחרור ואת GET /app/info. הפקודה ./whatsapp version מדפיסה רק את מספר הגרסה.

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

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

הכלי whatsapp_send מקבל גם את השדות scheduled_at, timezone, recurrence, weekdays, day_of_month, end_at ו-occurrence_limit כדי לתזמן את ההודעה במקום לשלוח אותה מיד, ואת התוצאה מנהלים באמצעות הכלי whatsapp_schedule.

POST /send/interactive (כפתורים, בקשת מיקום וקרוסלה) מוגדר בתיעוד כניסיוני, מיידי בלבד ו-REST בלבד. הוא אינו כלי MCP ואינו ערך type של whatsapp_send.

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

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

כל עוד רץ ./whatsapp rest ו-MCP_ENABLED לא כובה, נקודת ה-MCP זמינה בכתובת http://<host>:<port><base-path>/mcp. ברירת המחדל היא http://localhost:3000/mcp. לקוחות 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 רק בסביבה עם מספר מכשירים.

APP_BASIC_AUTH נדרש כאשר השרת מאזין על כתובת שאינה loopback. ברירת המחדל של APP_HOST היא 0.0.0.0. בכל רשומה נדרשים שם משתמש וסיסמה. האזנה על loopback נשארת פתוחה לפיתוח מקומי. APP_ALLOW_UNAUTHENTICATED=true חושף את ה-API בלי Basic Auth על bind שאינו loopback.

עבור לקוחות מרוחקים שאינם יכולים להעביר כותרת Basic Auth, קיים מנגנון OAuth 2.1. הוא כבוי כברירת מחדל. תצורה מינימלית לפי התיעוד:

APP_BASIC_AUTH=admin:replace-with-a-strong-password
MCP_ENABLED=true
MCP_OAUTH_ENABLED=true
MCP_OAUTH_ISSUER_URL=https://gowa.example.com

MCP_OAUTH_ISSUER_URL הוא כתובת HTTPS ציבורית של מנפיק ה-OAuth. MCP_OAUTH_RESOURCE_URL אופציונלי ומייצג את כתובת ה-MCP הציבורית הקנונית. אם לא הוגדר, הוא נגזר מהמנפיק ומנתיב הבסיס. MCP_OAUTH_DB_URI שומר לקוחות, קודים וגיבובי טוקנים ב-SQLite, וברירת המחדל היא file:storages/oauth.db. כאשר OAuth מופעל, הנתיב /mcp מקבל טוקן מסוג Bearer או את פרטי ה-Basic Auth שהוגדרו. מנגנון OAuth אינו מבצע אימות לנתיבי REST או ממשק המשתמש (UI). פרטי לקוח, פרוקסי הפוך, נתיב משנה ומודל האבטחה מתועדים ב-docs/mcp-oauth.md.

סדר טעינת ההגדרות, לפי התיעוד הרשמי נכון ל-2026-11-02: ההגדרות מאותחלות מדגלים, ואחר כך רוב משתני הסביבה חלים. ערך סביבה שכבר הוגדר יכול לדרוס את הדגל התואם. קובץ .env ממלא רק משתנים שלא הוגדרו כבר בסביבת התהליך. דגל מפורש גובר בהגדרות MCP OAuth, ובדגלים --allow-unauthenticated, --trusted-origins, --chatwoot-webhook-allow-unsigned ו---webhook-all-device-receipts. לכל אפשרות כדאי מקור אחד, כדי שלא ייווצרו ערכים סותרים. לדוגמה, WHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFY=true דורס --webhook-insecure-skip-verify=false.

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

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

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

הנחיות טכניות לפי GOWA v9:
1. שרת ה-MCP מוגש ישירות מתוך שרת ה-REST בנתיב /mcp מעל תעבורת HTTP streamable, כל עוד רץ ./whatsapp rest. כתובת ברירת המחדל היא http://localhost:3000/mcp (או http://<host>:<port><base-path>/mcp לפי APP_PORT, APP_HOST ו-APP_BASE_PATH אם הוגדרו).
2. השרת דורש כותרת אימות Authorization מסוג Basic Auth אם הוגדר APP_BASIC_AUTH. APP_BASIC_AUTH נדרש בהאזנה על כתובת שאינה loopback (ברירת המחדל של APP_HOST היא 0.0.0.0). על loopback החיבור נשאר פתוח לפיתוח מקומי. APP_ALLOW_UNAUTHENTICATED=true חושף את ה-API בלי Basic Auth על bind שאינו loopback.
3. בריבוי מכשירים, ניתן להגדיר כותרת X-Device-Id לחיבור כולו או להשתמש במכשיר ברירת המחדל. אם רשום מכשיר אחד בלבד, הוא ברירת המחדל. קריאה בודדת יכולה להעביר device_id.
4. לפי טבלת הכלים בתיעוד, המנוע כולל 7 כלים מאוחדים (whatsapp_send, whatsapp_schedule, whatsapp_message, whatsapp_chat, whatsapp_group, whatsapp_app, whatsapp_newsletter) שבהם הפעולה נבחרת באמצעות שדה type או action. משפט המיגרציה באותו תיעוד מציין 5 כלים. POST /send/interactive הוא REST בלבד ומיידי בלבד, ואינו כלי MCP.
5. ההגדרות מאותחלות מדגלים, ואחר כך רוב משתני הסביבה חלים ויכולים לדרוס דגל תואם. קובץ .env ממלא רק משתנים שלא הוגדרו כבר בסביבת התהליך. דגל מפורש גובר בהגדרות MCP OAuth, ובדגלים --allow-unauthenticated, --trusted-origins, --chatwoot-webhook-allow-unsigned ו---webhook-all-device-receipts.
6. OAuth 2.1 מיועד ללקוחות מרוחקים שאינם יכולים לשלוח Basic Auth, והוא כבוי כברירת מחדל. לחיבור מקומי אין להפעיל אותו.
7. התיעוד עוקב אחרי main הממוזג, כולל שינויים שאחרי v9.7.0. אם הבינארי או תג הקונטיינר נעול, את הגרסה בפועל בודקים ב-GET /app/info או באמצעות ./whatsapp version. הפקודה מדפיסה רק את מספר הגרסה.

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

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

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

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

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

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

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

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

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