> העתק ציבורי של מדריך המפתחים של ViewStream (לקריאה גם על ידי סוכני AI). רשימת המדריכים: https://www.viewstream.co.il/he/developers/guide/index.md · תיעוד ה-API: https://api.viewstream.co.il/docs/

# שרת MCP (עוזרי AI)

ViewStream מפעילה **שרת MCP** מרוחק (Model Context Protocol) בכתובת

```
https://api.viewstream.co.il/mcp
```

דרכו עוזר AI — Claude, ChatGPT, Cursor או כל לקוח MCP אחר — יכול לעבוד עם חשבון ה-ViewStream שלכם
בשפה טבעית: *"מה משודר עכשיו בערוץ הראשי שלנו?"*, *"מצא את התוכניות מהשבוע שעבר על אליפות אירופה וסכם
אותן"*, *"אילו סרטונים נצפו הכי הרבה אתמול?"*, *"חתוך קליפ של חמש הדקות הראשונות של מהדורת
20:00"*. העוזר מפעיל **כלים** (tools) של ViewStream בשמכם, עם מפתח API שאתם נותנים לו.

## איך זה עובד

- **תעבורה:** MCP Streamable HTTP, גרסת פרוטוקול `2025-06-18` (אפשר לנהל משא ומתן גם על `2025-11-25` ועל
  `2025-03-26`). הלקוח שולח בקשות POST עם הודעות JSON-RPC 2.0 אל `/mcp` ומקבל תשובת JSON אחת לכל בקשה. השרת
  חסר מצב (stateless): הוא לא מנפיק `Mcp-Session-Id` ולא פותח זרם ביוזמת השרת (`GET /mcp` עונה `405`).
- **אימות:** מפתח API של הארגון שלכם, שנשלח כ-`Authorization: Bearer <key>` — אותם מפתחות, אותן הרשאות ואותה
  הגבלת קצב (20 בקשות לשנייה לכל מפתח, פרץ של 100) כמו ב-REST API. אין התחברות ב-OAuth; עוגיית התחברות של
  Studio לא מתקבלת ב-`/mcp`.
- **אותם כללים כמו ב-API:** כל כלי קורא ל-API הציבורי `/v1` בתוך השרת *בתור המפתח שלכם*, כך שהוא רואה רק את
  הנתונים של הארגון שלכם, רק את מה שההרשאות של המפתח מתירות, ועובר אימות קלט, הגבלת קצב ורישום ביומן הביקורת בדיוק
  כמו קריאה ישירה ל-API. כל הפעלת כלי נרשמת גם ביומן הביקורת כ-`mcp.tool_call` (שם הכלי ותקציר של
  הארגומנטים — טקסטים ארוכים, כמו הודעת תמיכה, נשמרים רק כאורך שלהם).
- **פלט:** כותרות, סיכומים וכתוביות בעברית מוחזרים כמו שהם (UTF-8). תוצאה של כלי מוגבלת לכ-60 KB; רשימות
  ארוכות יותר מקוצרות ומסומנות `_truncated` — בקשו `limit` קטן יותר או טווח קצר יותר.
- **שגיאות:** כלי שנכשל מחזיר תוצאה עם `isError: true` ופרטי הבעיה של ה-API (type, status,
  detail), כך שהעוזר יכול להסביר את הבעיה או לתקן את הקריאה.

## יצירת מפתח API לעוזר

ב-Studio, היכנסו ל-**אינטגרציות ← מפתחות API ← יצירת מפתח** ותנו למפתח רק את ההרשאות שהעוזר צריך:

| אתם רוצים שהעוזר… | הרשאות |
|---|---|
| יקרא ערוצים, EPG, צפייה חוזרת, תוכניות, מצב השירות והתראות | `channels:read` |
| יקרא את הספרייה, סיכומי AI וכתוביות | `assets:read` |
| יקרא סטטיסטיקת צפייה | `stats:read` |
| יחתוך קליפים | `clips:write` |
| יפתח פניות תמיכה | `support:write` |
| ייצר מחדש סיכומי AI | `assets:write` |

עוזר לקריאה בלבד צריך את `channels:read`, `assets:read` ו-`stats:read`. העוזר *רואה* רק את הכלים שהמפתח שלו
יכול להפעיל (`tools/list` מסונן לפי הרשאות). התייחסו למפתח כמו לסיסמה: כל מי שמחזיק בו יכול לעשות את מה
שההרשאות שלו מתירות. בטלו אותו באותו מסך כשאתם מפסיקים להשתמש בעוזר.

## כלים

כלי קריאה (לא משנים את הנתונים שלכם):

| כלי | מה הוא עושה | הרשאה |
|---|---|---|
| `list_channels` | ערוצים עם מזהה, slug, כותרת, מצב, פידים של מקודדים, חלון DVR, תקופת שמירה, כתובת שידור חי | `channels:read` |
| `channel_status` | ערוץ אחד עכשיו: משודר עכשיו / הבא, תקינות הפיד וההקלטה, התראות פעילות עליו | `channels:read` |
| `search_catchup` | חיפוש בתוכניות מוקלטות (כותרת, טקסט הלוח, סיכום AI, מגישים, נושאים — וגם במה שנאמר, עם הרגעים) בערוץ אחד או בכל הערוצים | `channels:read` |
| `get_programme` | תוכנית אחת: זמנים, טקסט הלוח, ערוץ, מצב ההקלטה, VOD, כתובות צפייה; עם `assets:read` גם הסיכום שלה ושפות הכתוביות | `channels:read` |
| `get_epg` | לוח השידורים של ערוץ בין שני זמנים (ברירת מחדל: משלוש שעות אחורה ועד 21 שעות קדימה, לכל היותר 7 ימים) | `channels:read` |
| `search_library` | חיפוש או רשימה של סרטונים בספרייה (כותרת, תיאור, מזהה חיצוני, סיכום AI) | `assets:read` |
| `get_asset` | סרטון אחד: מצב, פרסום, משך, רנדישנים, צפייה, סיכום, שפות כתוביות | `assets:read` |
| `get_subtitles` | כתוביות של תוכנית, סרטון או קליפ כתמליל עם חותמות זמן (`text`) או כ-WebVTT, בעמודים | `assets:read` |
| `get_summary` | סיכום ה-AI בעברית של תוכנית או סרטון (סיכום, מגישים, נושאים, מצב) | `assets:read` |
| `stats_overview` | סקירת קהל ואיכות לתקופה, עם תקופת השוואה | `stats:read` |
| `stats_top` | הסרטונים, הקליפים או הערוצים המובילים; או התוכניות של ערוץ לפי קהל (`entity: programmes`) | `stats:read` |
| `list_alerts` | התראות ניטור, מהחדשה לישנה | `channels:read` או `stats:read` |
| `service_status` | תקינות השירות לפי שכבה (סטרימינג, הפצה, מקור, QoE) ושירותי ה-AI | `channels:read` או `stats:read` |
| `search_docs` | חיפוש במדריך של Studio (אנגלית ועברית), במדריך הזה ובתיעוד ה-API | כל מפתח |

כלי כתיבה (הם משנים נתונים — עוזר טוב שואל אתכם לפני שהוא מפעיל אותם):

| כלי | מה הוא עושה | הרשאה |
|---|---|---|
| `create_clip` | חיתוך קליפ (עד 6 שעות) מההקלטה של ערוץ בין שני זמנים; דיוק `segment` מוכן מיד, `frame` מושלם על ידי משימת רקע. קליפים מערוצים בלבד. | `clips:write` |
| `create_support_request` | פתיחת פניית תמיכה ל-Interhost (חובה `contact_email`; עד 10 לארגון בשעה) | `support:write` |
| `regenerate_summary` | יצירת סיכום AI חדש לתוכנית או לסרטון מהכתוביות בעברית (מחליף את הסיכום השמור, כולל עריכה ידנית) | `assets:write` |

אפשר לציין ערוצים לפי מזהה או לפי slug (`main`, `news`). זמנים הם בפורמט RFC 3339 (`2026-10-06T20:00:00+03:00`).

**משאבים** (resources — מסמכים שעוזר יכול לקרוא): `viewstream://docs/{lang}/{topic}` — עמודים מהמדריך של
Studio ומהמדריך הזה, `lang` = `en` או `he`, למשל `viewstream://docs/he/catch-up`, `viewstream://docs/en/api-recipes`;
`viewstream://openapi` — כל פעולות ה-API עם ההרשאה שכל אחת דורשת; `viewstream://openapi/{operationId}` — פעולה
אחת במלואה. **הנחיות** (prompts): `daily_report` (דוח הצפייה של אתמול) ו-`find_programme` (מציאת תוכנית
וסיכום שלה).

## חיבור עוזר

בכל דוגמה, החליפו את `<key>` במפתח ה-API שלכם.

### Claude Code

```bash
claude mcp add --transport http viewstream https://api.viewstream.co.il/mcp \
  --header "Authorization: Bearer <key>"
```

אחר כך שאלו, למשל: *"בעזרת viewstream, מה משודר עכשיו בכל הערוצים?"* בדקו את החיבור עם
`claude mcp list`.

### Claude Desktop ו-claude.ai

מחברים מותאמים אישית ב-Claude Desktop וב-claude.ai (**Settings → Connectors → Add custom connector**) מתחברים
ב-OAuth, שהשרת הזה עדיין לא מציע. עד אז, חברו את Claude Desktop דרך הגשר `mcp-remote`,
שמוסיף את הכותרת (דורש Node.js). בקובץ `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "viewstream": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.viewstream.co.il/mcp",
               "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer <key>" }
    }
  }
}
```

### Cursor

בקובץ `~/.cursor/mcp.json` (לכל הפרויקטים) או `.cursor/mcp.json` (לפרויקט אחד — אל תעשו commit למפתח):

```json
{
  "mcpServers": {
    "viewstream": {
      "url": "https://api.viewstream.co.il/mcp",
      "headers": { "Authorization": "Bearer <key>" }
    }
  }
}
```

### לקוחות אחרים

כל לקוח שתומך בשרתי MCP מרוחקים על גבי Streamable HTTP עם כותרת מותאמת אישית יעבוד: השתמשו בכתובת שלמעלה
ובכותרת `Authorization`. לקוחות שתומכים רק בתעבורה הישנה HTTP+SSE יכולים להשתמש ב-`mcp-remote` כמו למעלה.

## JSON-RPC גולמי עם curl

```bash
KEY=<key>
MCP=https://api.viewstream.co.il/mcp
H=(-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream")

# 1. handshake
curl -s "${H[@]}" "$MCP" -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
  "params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'
curl -s "${H[@]}" -H "MCP-Protocol-Version: 2025-06-18" "$MCP" -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

# 2. the tools this key may call
curl -s "${H[@]}" -H "MCP-Protocol-Version: 2025-06-18" "$MCP" -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 3. call a tool
curl -s "${H[@]}" -H "MCP-Protocol-Version: 2025-06-18" "$MCP" -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
  "params":{"name":"search_catchup","arguments":{"q":"אליפות אירופה","limit":5}}}'
```

תוצאה של כלי נראית כך (בקיצור):

```json
{"jsonrpc":"2.0","id":3,"result":{
  "content":[{"type":"text","text":"{\"q\":\"אליפות אירופה\",\"items\":[…]}"}],
  "structuredContent":{"q":"אליפות אירופה","items":[{"id":"0192c8a0-…","title":"חמש","start_at":"2026-10-04T17:00:00Z",
    "status":"recorded","match":{"field":"summary","snippet":"…להעפיל לאליפות אירופה 2028…"},"channel":{"id":"…","slug":"main"}}],
    "truncated":false,"channels_searched":1}}}
```

## שגיאות

| HTTP | מתי |
|---|---|
| `401` + `WWW-Authenticate: Bearer` | אין מפתח, או שהמפתח פגום, לא מוכר או מבוטל |
| `403` | הבקשה הגיעה מדף אינטרנט שה-`Origin` שלו לא מורשה (הגנה מפני DNS rebinding), או שהמפתח לא שייך לארגון |
| `400` | `MCP-Protocol-Version` מציין גרסה שהשרת לא תומך בה |
| `405` | `GET /mcp` (אין זרם ביוזמת השרת) או כל שיטה אחרת מלבד POST |
| `406` / `415` | `Accept` לא כולל את `application/json`, או שגוף הבקשה אינו `application/json` |
| `429` | הגבלת קצב (`Retry-After` אומר מתי לנסות שוב) |

בתוך תשובת `200`, בעיות פרוטוקול הן שגיאות JSON-RPC (`-32601` שיטה לא מוכרת, `-32602` כלי לא מוכר או
פרמטרים שגויים, `-32002` משאב לא מוכר), וכשלים של כלים הם תוצאות עם `isError: true` שנושאות את סוג
הבעיה של ה-API: `insufficient_scope` (למפתח אין את ההרשאה של הכלי), `not_found` (אין ערוץ או תוכנית כאלה
*בארגון שלכם*), `validation_error`, `rate_limited`, `feature_disabled`.

## מגבלות והערות

- החיפוש בצפייה החוזרת מכסה כותרות, טקסטים של הלוח וסיכומי AI; בטקסט הכתוביות עצמו לא מחפשים.
- `create_clip` חותך הקלטות של ערוצים בלבד (אין קליפים מסרטונים בספרייה); לקליפ אין מצב טיוטה או
  פרסום נפרד.
- הזמנים בתשובות הם ב-UTC; העוזר ממיר אותם לשעון ישראל כשמבקשים ממנו.
- השרת משרת ארגון אחד לכל מפתח. פונקציות מפעיל (ניהול של Interhost) לא זמינות דרך MCP.