הפניה / ארכיון ושילובים

MCP לקריאה בלבד

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

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

מדריך לתהליך העבודה · ויקי

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

השתמשו בסביבת ה-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 הרשמי. הקובץ deploy/constraints-mcp.txt מקבע את גרסאות ה-SDK והתלויות שנבדקו. תכונות אלו דורשות קוד מקור עדכני; גרסת התצוגה המקדימה הניידת 0.7.0 קדמה להן.

הנפקת חיבור#

הזינו תווית ובחרו את סביבות העבודה והצ'אטים שהלקוח רשאי לקרוא.
בחרו כלים בנפרד או השתמשו בערכה מוגדרת מראש (preset). מוצעים רק כלים שמומשו.
בחרו 1, 7, 30 או 90 ימים, או תוקף מותאם אישית בין דקה אחת ל-90 ימים.
לחצו על Create connection. האסימון מופיע פעם אחת לצד הגדרות הלקוח.
העתיקו את האסימון וההגדרות, ולאחר מכן הפעילו את Check connection. פעולה זו מאתחלת את MCP ומציגה את רשימת הכלים המורשים; לא נקראות הודעות. התוצאה מציגה את גרסת הפרוטוקול, שמות הכלים, מספרם והזמן שחלף.
לחצו על 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, Cursor, VS Code.

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

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 או לכידה מלאה.