# forms-mcp — חיבור קבוע של Claude ל-Google Forms

שרת MCP מרוחק (Remote MCP) שרץ על Cloudflare Workers ונותן ל-Claude גישה מלאה וקבועה ל-Google Forms של החשבון המחובר: יצירת טפסים, עריכת שאלות, בחנים עם ציונים, פרסום/סגירה, ושליפת כל התשובות.

- **אימות**: OAuth מלא — השרת הוא OAuth Server מול Claude ו-OAuth Client מול Google. עם `access_type=offline` נשמר Refresh Token, כך שהחיבור מתחדש לבד לתמיד.
- **פרטיות**: השרת פרטי. `ALLOWED_EMAILS` חוסם כל חשבון גוגל שאינו ברשימה. אין אף סוד בקוד — הכול ב-Cloudflare Secrets.
- **בסיס**: התבנית הרשמית של Cloudflare‏ (`remote-mcp-google-oauth`) + הרחבות: Refresh Token אוטומטי, כלי Forms מלאים, allowlist.

## הכלים שהשרת חושף ל-Claude

| כלי | מה הוא עושה |
|---|---|
| `whoami` | לאיזה חשבון גוגל השרת מחובר |
| `list_forms` | רשימת טפסים שנגישים לשרת דרך Drive (scope‏ `drive.file`) |
| `get_form` | המבנה המלא של טופס: שאלות, itemId, הגדרות בוחן, מצב פרסום, קישור למשיבים |
| `create_form` | יצירת טופס חדש + פרסום אוטומטי (טפסים חדשים נוצרים לא-מפורסמים כברירת מחדל) |
| `batch_update` | **כלי העריכה המקסימלי** — העברה ישירה של `batchUpdate` מה-API: הוספה/עריכה/מחיקה/הזזה של שאלות, כותרות, הגדרות בוחן וציונים |
| `set_publish_state` | פרסום/ביטול פרסום, פתיחה/סגירה לתשובות |
| `list_responses` | כל התשובות שהוגשו (כולל ציוני בוחן), עם דפדוף וסינון לפי זמן |
| `get_response` | תשובה בודדת לפי מזהה |

הערה על `list_forms`: ה-scope המינימלי `drive.file` רואה טפסים שנוצרו דרך השרת. טפסים קיימים מאתרים דרך מחבר Google Drive הרגיל של Claude — ומרגע שיש formId, כל שאר הכלים עובדים עליהם ישירות.

## הקמה (חד-פעמית)

### שלב 1 — GitHub + Cloudflare (PowerShell)

דרישות: Node.js‏ + git. הפקודות המלאות נמצאות ב-`SETUP.md` / בשיחת ההקמה. תמצית:

```powershell
Set-Location C:\Users\yaniv\claude-work\forms-mcp
npm install
npx wrangler login          # התחברות / הרשמה חינמית ל-Cloudflare
npx wrangler kv namespace create OAUTH_KV   # ואז לעדכן את ה-id ב-wrangler.jsonc
npx wrangler deploy         # מדפיס את כתובת השרת: https://forms-mcp.<subdomain>.workers.dev
npx wrangler secret put COOKIE_ENCRYPTION_KEY   # מחרוזת אקראית (64 hex)
npx wrangler secret put ALLOWED_EMAILS          # yanivmiz77@gmail.com
```

### שלב 2 — Google Cloud Console

1. ליצור פרויקט חדש (למשל `forms-mcp`) ב-console.cloud.google.com.
2. להפעיל שני API‑ים: **Google Forms API** ו-**Google Drive API**.
3. במסך OAuth‏ (Google Auth Platform): סוג **External**, להוסיף את ה-scopes:
   `.../auth/forms.body`, `.../auth/forms.responses.readonly`, `.../auth/drive.file`
4. **לפרסם את האפליקציה ל-Production** (Audience → Publish). בלי זה, במצב Testing, ה-Refresh Token פג אחרי 7 ימים והחיבור "הקבוע" יישבר כל שבוע.
5. ליצור **OAuth Client** מסוג Web application עם Redirect URI:
   `https://forms-mcp.<subdomain>.workers.dev/callback`
6. לשמור את המזהים כסודות:

```powershell
npx wrangler secret put GOOGLE_CLIENT_ID
npx wrangler secret put GOOGLE_CLIENT_SECRET
```

### שלב 3 — חיבור ב-Claude

Settings ‏→ Connectors ‏→ **Add custom connector** ‏→ להדביק:
`https://forms-mcp.<subdomain>.workers.dev/mcp`
בהתחברות גוגל יופיע מסך "האפליקציה לא מאומתת" (כי זו אפליקציה אישית שלא עברה Verification) — ‏Advanced ‏→ Continue. זה מסך חד-פעמי.

## פתרון תקלות

- **401 / token expired**: השרת מרענן טוקנים לבד. אם בכל זאת נתקע — לנתק ולחבר מחדש את המחבר בהגדרות Claude.
- **403 בסיום ההתחברות**: החשבון לא ב-`ALLOWED_EMAILS`.
- **החיבור נשבר אחרי שבוע**: האפליקציה בגוגל נשארה במצב Testing — לפרסם ל-Production (שלב 2.4).
- **create_form יצר טופס שלא מקבל תשובות**: טפסים חדשים נוצרים לא-מפורסמים; `create_form` מפרסם אוטומטית, ואפשר לשלוט בזה עם `set_publish_state`.
- לוגים: `npx wrangler tail forms-mcp`.

## כללי עבודה בריפו

- אין commit ישיר ל-main — תמיד branch חדש ואז PR (חריג יחיד: קומיט האתחול לריפו הריק).
- אין סודות בקוד — רק Cloudflare Secrets (ול-CI, אם יתווסף: GitHub Secrets).