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

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

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

[Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/)

[Documentation index](https://phishdestroy.io/tgwitness/he/llms.txt)

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

[TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [תיעוד](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [שילוב עם מערכות ארכיונים](https://phishdestroy.io/tgwitness/he/docs/reference/cli/)

![שילוב עם מערכות ארכיונים](https://phishdestroy.io/tgwitness/assets/chapter-integrations.svg?v=367d9d210074)

חברו לקוח אנליסט לסביבות עבודה וצ'אטים נבחרים. TgWitness מספק **Streamable HTTP בכתובת `/mcp` בתהליך הפאנל**. לכל חיבור יש אסימון, תוקף וכלים מותרים משלו. MCP אינו יכול לשלוח הודעות Telegram, לשנות הגדרות או לערוך את היומן החתום. אותם חיבורים פועלים גם בשורת [הפקודה](https://phishdestroy.io/tgwitness/he/docs/reference/cli/).

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

**בעמוד זה**

- [התקנה ובדיקה](https://phishdestroy.io/tgwitness/he/docs/reference/mcp/#install-and-check)
- [יצירת חיבור](https://phishdestroy.io/tgwitness/he/docs/reference/mcp/#issue-a-connection)
- [חבר את הלקוח שלך](https://phishdestroy.io/tgwitness/he/docs/reference/mcp/#connect-your-client)
- [מנהרת Cloudflare](https://phishdestroy.io/tgwitness/he/docs/reference/mcp/#cloudflare-tunnel)
- [כלים ומגבלות](https://phishdestroy.io/tgwitness/he/docs/reference/mcp/#tools-and-boundaries)

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

השתמשו בסביבת ה-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`. **כלים נוספים → אינטגרציות → MCP** מציג את מצב הריצה ואת פקודת ההתקנה באמצעות קובץ ההפעלה של Python בפועל של אותו שרת. **לחיצה על בדוק שוב** מרעננת את המצב הזה מבלי לטעון מחדש את הדף; היא אינה מתקינה חבילות ואינה מפעילה מחדש את השרת.

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

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

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) מפורשים; האסימון מועתק בנפרד.

| לקוח | תצורה | קישור |
| --- | --- | --- |
| קוד קלוד | `.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 | 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` | טקסט ההודעות שנשמרו בתקופה הנבחרת; `ranked=true` משתמש [בחיפוש טקסט מלא](https://phishdestroy.io/tgwitness/he/docs/reference/search/) (צורות מילים, התאמות הטובות ביותר תחילה, `next_offset` דפדוף) |
| `get_message_versions` | גרסאות שנלכדו ותצפיות מחיקה |
| `get_message_context` | מזהי הודעות סמוכות שנלכדו |
| `get_journal_event` | רשומה מסוננת אחת עם סימוכין למקור שלה |
| `get_capture_status` | מצב האיסוף, רשומות כיסוי מותרות ו `gap_summary`: מספרי הודעות שמעולם לא נצפו, לפי ערוץ או סופר-קבוצה ולכל הרצף ברמת החשבון ([פרטים](https://phishdestroy.io/tgwitness/he/docs/reference/evidence/#missing-message-numbers-gap_summary)); בחרו צ'אט כדי לראות את הפערים המפורטים בו |
| `get_activity_stats` | הודעות לפי שעה (UTC) ויום בשבוע, ימי שיא, שיעורי עריכה ומחיקה, שולחים, דומיינים ו `@handles`, עם כיסוי ([פרטים](https://phishdestroy.io/tgwitness/he/docs/reference/cli/#activity-statistics)) |
| `get_messages_by_date` | הודעות שנשמרו במשך יום קלנדרי אחד באזור זמן IANA שצוין (`Europe/Kyiv`, `UTC`), לפי הזמן המדווח על ידי Telegram; `from_utc` ו `until_utc` ציינו את היום המחושב, כולל שעון קיץ |
| `get_pinned_messages` | הודעות שהוצמדו בתמונת המצב האחרונה של הצ'אט עם הגרסאות השמורות שלהן, וכן הודעות ההצמדה וההסרה שנצפו בזמן אמת |
| `get_chat_stats` | מספר הרשומות שנשמרו עבור צ'אט אחד או כל הצ'אטים בתחום היישום, התצפית הראשונה והאחרונה, ו `gap_summary`; השתמשו בו לפני קריאה בהיקף נרחב |
| `get_topics` | נושאי פורום מתוך הודעות שירות הנושאים השמורים: היסטוריית כותרות, נושאים סגורים או מוסתרים, מספר ההודעות השמורות |
| `get_media` | תמונה שנשמרה כתצוגה מקדימה בפורמט JPEG מוקטנת (36 KB לכל היותר), המוחזרת כתמונה יחד עם ה-SHA-256 שלה וה `media.saved` הרשומה; הקובץ נבדק תחילה מול ה-hash הרשום שלו, קבצים אחרים מחזירים מטא-נתונים בלבד |
| `export_messages` | שורת פקודה בלבד, לא נבחר כברירת מחדל: זרם התצפיות שנשמרו כ-JSON Lines ([פרטים](https://phishdestroy.io/tgwitness/he/docs/reference/cli/#export)); לא מוצע דרך MCP |

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

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

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

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