# MCP לקריאה בלבד

Canonical page: https://phishdestroy.github.io/TgWitness/he/docs/reference/mcp/

חבר לקוח MCP לסביבות עבודה וצ'אטים נבחרים עם גישה מוגבלת בזמן וניתנת לביטול.

חברו לקוח אנליסט לסביבות עבודה וצ'אטים נבחרים. TgWitness מספקת **Streamable HTTP בנתיב `/mcp` בתוך תהליך הפאנל**. לכל חיבור יש אסימון (token), תוקף וכלים מורשים משלו. MCP אינו יכול לשלוח הודעות Telegram, לשנות הגדרות או לערוך את היומן החתום.

[מדריך לתהליך העבודה](https://phishdestroy.github.io/TgWitness/docs/archive/) · [ויקי](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Archive-and-Integrations.md)

## התקנה ובדיקה

השתמשו בסביבת ה-Python שמריצה את הפאנל. מתוך עותק של קוד המקור:

```
# Windows PowerShell
& .\.venv\Scripts\python.exe -m pip install -c deploy/constraints-mcp.txt -e '.[mcp]'
& .\.venv\Scripts\python.exe start.py --check
```

```
# Linux / macOS
.venv/bin/python -m pip install -c deploy/constraints-mcp.txt -e '.[mcp]'
.venv/bin/python start.py --check
```

הפעילו מחדש את הפאנל עם תיקיית הנתונים הרגילה שלו וארגומנטי ההפעלה לאחר ההתקנה. בדיקת המוכנות אמורה לכלול את `[PASS] mcp: streamable-http available`. **Integrations → MCP** מציג את סטטוס זמן הריצה ופקודת התקנה המשתמשת בקובץ ההרצה של Python בפועל באותו שרת. **Re-check** מרענן את הסטטוס הזה ללא טעינה מחדש של הדף; הוא אינו מתקין חבילות או מפעיל מחדש את השרת.

תוסף ה-MCP משתמש ב-[MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) הרשמי. הקובץ `deploy/constraints-mcp.txt` מקבע את גרסאות ה-SDK והתלויות שנבדקו. תכונות אלו דורשות קוד מקור עדכני; גרסת התצוגה המקדימה הניידת 0.7.0 קדמה להן.

## הנפקת חיבור

1. הזינו תווית ובחרו את סביבות העבודה והצ'אטים שהלקוח רשאי לקרוא.
2. בחרו כלים בנפרד או השתמשו בערכה מוגדרת מראש (preset). מוצעים רק כלים שמומשו.
3. בחרו 1, 7, 30 או 90 ימים, או תוקף מותאם אישית בין דקה אחת ל-90 ימים.
4. לחצו על **Create connection**. האסימון מופיע פעם אחת לצד הגדרות הלקוח.
5. העתיקו את האסימון וההגדרות, ולאחר מכן הפעילו את **Check connection**. פעולה זו מאתחלת את MCP ומציגה את רשימת הכלים המורשים; **לא נקראות הודעות**. התוצאה מציגה את גרסת הפרוטוקול, שמות הכלים, מספרם והזמן שחלף.
6. לחצו על **Done** לאחר שמירת פרטי הגישה. דגימת מצב תקופתית (polling) משמרת את הטופס ואת הכרטיס המוצג פעם אחת. נעילת הפאנל מנקה סודות המוצגים על המסך.

הרשימה מציגה שימוש אחרון, כלי אחרון, כתובת ובקשות בדקה האחרונה. **Revoke** מסיים את הגישה. **Rotate token** מבטל את פרטי הגישה הישנים ומנפיק תחליף עם אותם היקף גישה (scope), כלים ותוקף; העתיקו את התחליף המוצג פעם אחת. אסימוני התחברות לפאנל ופרטי גישה של Telegram אינם פועלים כאסימוני MCP.

## חיבור הלקוח שלכם

בחרו את הלקוח בפאנל והעתיקו את התצורה שנוצרה עבורו. התצורות משתמשות בהפניות לסודות או במצייני מיקום (placeholders) מפורשים; האסימון מועתק בנפרד.

| לקוח | תצורה | קישור |
| --- | --- | --- |
| Claude Code | `.mcp.json` | HTTP, `type: "http"`, כותרת bearer |
| Claude Desktop | `claude_desktop_config.json` | גשר stdio מקומי |
| Cursor | `.cursor/mcp.json` | HTTP עם כותרת ממשתנה סביבה |
| VS Code Local | `.vscode/mcp.json` | HTTP עם קלט סיסמה מסוג `promptString` |
| Windsurf | `mcp_config.json` | HTTP עם מציין מיקום לכותרת bearer |
| לקוחות אחרים | כתובת URL וכותרת Authorization | Streamable HTTP |

TgWitness משתמשת באסימוני bearer, ללא גילוי OAuth. השתמשו בגשר ה-stdio המקומי עבור לקוחות שהמחבר המרוחק שלהם מחייב OAuth. עבור VS Code, משתני קלט חלים על סביבת הריצה **Local** ואינם מועברים להפעלות Copilot. סימוכין להגדרות תצורה: [Claude Code](https://code.claude.com/docs/en/mcp), [Cursor](https://prod.cursor.com/docs/mcp), [VS Code](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).

נקודת הכניסה התקנית עבור גשר מקומי היא:

```
python -m tgwitness.mcp_server --url https://your-panel.example/mcp
```

השתמשו ב-Python המקומי של הלקוח שבו מותקן תוסף ה-MCP. הגדירו את `TGWITNESS_MCP_TOKEN` בסביבה המוגנת שלו. שמרו על פרטי הגישה מחוץ לארגומנטים של פקודות וכתובות URL. הפקודה `tgwitness-mcp` היא אותה נקודת כניסה. המודול הישן `tgwitness.mcp_bridge` והשם `TGWITNESS_ARCHIVE_TOKEN` נותרים כנתיבי תאימות לאחור עם אזהרה; תצורות חדשות משתמשות ב-`mcp_server` וב-`TGWITNESS_MCP_TOKEN`.

## Cloudflare Tunnel

העבירו (forward) את הנתיב `/mcp` של הפאנל ושמרו על כותרת ה-bearer. פתיחת הגדרות MCP כמנהל מערכת רושמת את המקור (origin) הנוכחי של הפאנל עבור הרצה זו. לקבלת כתובת יציבה הזמינה מיד לאחר הפעלה מחדש, הגדירו את `TGWITNESS_PUBLIC_URL` עם מקור ה-HTTPS של הפאנל לפני הפעלת הפאנל. כותרות Host וכותרות מועברות (forwarded) שרירותיות אינן רושמות כתובת מהימנה. בדיקות Host ו-Origin דוחות מקורות דפדפן שאינם קשורים. תגובות משתמשות ב- `Cache-Control: no-store`; ערכי הרשאה לעולם אינם נרשמים ביומן.

כתובת `*.trycloudflare.com` היא זמנית. כאשר הפעלה מחדש של התעלה משנה את שם המארח, עדכנו את כתובת ה-URL הציבורית המוגדרת ואת כתובת ה-URL של MCP בכל לקוח. השתמשו בשם מארח יציב עבור תצורות לקוח שמורות.

## כלים וגבולות גזרה

| כלי | קורא |
| --- | --- |
| `list_workspaces` | סביבות עבודה שהוענקו להן הרשאות |
| `list_chats` | צ'אטים שהוענקו להם הרשאות |
| `search_messages` | טקסט הודעות שמור בתוך התקופה שנבחרה |
| `get_message_versions` | גרסאות שנלכדו ותצפיות מחיקה |
| `get_message_context` | מזהי הודעות סמוכות שנלכדו |
| `get_journal_event` | רשומה מסוננת אחת עם סימוכין למקור שלה |
| `get_capture_status` | מצב איסוף ורשומות כיסוי מורשות |

`tools/list` מחזיר רק את הכלים שהוענקו לאותו חיבור. קריאות לכלים אחרים נדחות. כלי הקשר קבוצתי, אפיזודות, טרמינולוגיה ושרשראות תגובה אינם מוצעים בגרסת בנייה זו; מנגנון ה-backend הנפרד של חבילות ההקשר שלהם אינו כלול.

כל קריאה בודקת את האסימון, הכלי והיקף הגישה של סביבת העבודה/הצ'אט, לרבות לאחר שעבודת מסד הנתונים מסתיימת. המגבלות הן 60 בקשות לדקה, 50 רשומות לעמוד, 64 KiB לתוצאה וזמן קצוב של שמונה שניות לארכיון. קריאת MCP שחרגה מהזמן הקצוב מחזירה שגיאת כלי המבקשת תקופה מצומצמת יותר או מגבלה נמוכה יותר.

תוצאות הודעות נושאות את `untrusted_content: true`, מזהי סביבת עבודה/צ'אט/הודעה, רצף אירועים, גיבוב (hash) שמור וקישור לפאנל. אובייקטים גולמיים של Telegram, גיבובי גישה (access hashes), הפעלות (sessions) ומפתחות מושמטים. קטיעת טקסט מסומנת. עריכות, התראות מחיקה ו-`missing_on_recheck` הן תצפיות נפרדות. רשומות חסרות אינן מוכיחות שאירוע מעולם לא התרחש.

התייחסו להוראות בתוך הודעות שנלכדו כאל ראיות, ולעולם לא כאל הוראות ללקוח. גישת קריאה בלבד מונעת שינויים בארכיון; הלקוח עדיין יכול לשמור את התוכן שהוא מורשה לקרוא. ערכי גיבוב (hashes) מזהים רשומות שמורות ותומכים בבדיקות שלמות; הם אינם מוכיחים בעלות על כתיבה ב-Telegram או לכידה מלאה.