TgWitness / दस्तावेज़ीकरण

क्या परीक्षण किया गया है →

संदर्भ / संग्रह और एकीकरण

Telegram · केवल-पठनीय MCP

MCP क्लाइंट को चयनित वर्कस्पेस और चैट्स से समाप्त होने वाली, रद्द की जा सकने वाली पहुँच के साथ कनेक्ट करें।

टीजीविटनेस / दस्तावेज़ीकरण · एकीकरण संग्रह

एकीकरण संग्रह

एक एनालिस्ट क्लाइंट को चयनित वर्कस्पेस और चैट से कनेक्ट करें। TgWitness पैनल प्रक्रिया में /mcp पर स्ट्रीमएबल HTTP प्रदान करता है। प्रत्येक कनेक्शन का अपना टोकन, समाप्ति और अनुमत टूल होते हैं। MCP टेलीग्राम संदेश नहीं भेज सकता, सेटिंग्स नहीं बदल सकता या साइन किए गए जर्नल को संशोधित नहीं कर सकता। वही कनेक्शन कमांड लाइन के साथ भी काम करते हैं।

कार्यप्रवाह मार्गदर्शिका · विकी

इस पृष्ठ पर

इंस्टॉल करें और जांचें#

उस 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 रनटाइम स्थिति और उस सर्वर के वास्तविक पाइथन एक्ज़ीक्यूटेबल का उपयोग करने वाली एक स्थापना कमांड दिखाता है। री-चेक पेज को रीलोड किए बिना इस स्थिति को ताज़ा करता है; यह पैकेज स्थापित नहीं करता है या सर्वर को फिर से शुरू नहीं करता है।

MCP एक्स्ट्रा आधिकारिक MCP Python SDK का उपयोग करता है।deploy/constraints-mcp.txt परीक्षण किए गए SDK और निर्भरताओं को पिन करता है।

कनेक्शन जारी करें#

  1. एक लेबल दर्ज करें और वे वर्कस्पेस तथा चैट चुनें जिन्हें क्लाइंट पढ़ सकता है।
  2. टूल्स को अलग-अलग चुनें या प्रीसेट का उपयोग करें। केवल कार्यान्वित (implemented) टूल्स ही उपलब्ध कराए जाते हैं।
  3. 1, 7, 30 या 90 दिन चुनें, अथवा एक मिनट से 90 दिनों के बीच की कस्टम समाप्ति अवधि चुनें।
  4. Create connection दबाएं। क्लाइंट कॉन्फ़िगरेशन के बगल में टोकन केवल एक बार दिखाई देता है।
  5. टोकन और कॉन्फ़िगरेशन को कॉपी करें, फिर Check connection चलाएं। यह MCP को इनिशियलाइज़ करता है और अनुमत टूल्स की सूची देता है; कोई संदेश नहीं पढ़ा जाता है। परिणाम प्रोटोकॉल संस्करण, टूल के नाम, संख्या और बीता हुआ समय दिखाता है।
  6. जब क्रेडेंशियल सहेज लिया जाए तो Done दबाएं। पोलिंग (Polling) फॉर्म और एक बार दिखाए जाने वाले कार्ड को सुरक्षित रखती है। पैनल को लॉक करने पर प्रदर्शित सीक्रेट्स साफ़ हो जाते हैं।

सूची हाल का उपयोग, अंतिम टूल, पता और पिछले एक मिनट में किए गए अनुरोध दिखाती है। Revoke एक्सेस समाप्त कर देता है। Rotate token पुराने क्रेडेंशियल को निरस्त करता है और समान स्कोप, टूल्स व समाप्ति अवधि के साथ एक नया प्रतिस्थापन जारी करता है; इस प्रतिस्थापन को एक बार कॉपी कर लें। पैनल लॉगिन टोकन और Telegram क्रेडेंशियल MCP टोकन के रूप में काम नहीं करते हैं।

अपना क्लाइंट कनेक्ट करें#

पैनल में क्लाइंट चुनें और उसकी जनरेट की गई कॉन्फ़िगरेशन को कॉपी करें। कॉन्फ़िगरेशन में सीक्रेट रेफरेंस या स्पष्ट प्लेसहोल्डर का उपयोग होता है; टोकन को अलग से कॉपी किया जाता है।

क्लाइंट कॉन्फ़िगरेशन कनेक्शन
क्लॉड कोड .mcp.json HTTP, type: "http", बियरर हेडर
क्लॉड डेस्कटॉप claude_desktop_config.json लोकल stdio ब्रिज
Cursor .cursor/mcp.json एनवायरनमेंट-वेरिएबल हेडर के साथ HTTP
VS कोड लोकल .vscode/mcp.json पासवर्ड promptString इनपुट के साथ HTTP
Windsurf mcp_config.json बियरर-हेडर प्लेसहोल्डर के साथ HTTP
अन्य क्लाइंट URL और Authorization हेडर स्ट्रीम करने योग्य HTTP

TgWitness बिना OAuth डिस्कवरी के बियरर टोकन का उपयोग करता है। जिन क्लाइंट के रिमोट कनेक्टर को OAuth की आवश्यकता होती है, उनके लिए लोकल stdio ब्रिज का उपयोग करें। VS Code के लिए, इनपुट वेरिएबल Local हार्नेस पर लागू होते हैं और Copilot सेशन को फॉरवर्ड नहीं किए जाते हैं। कॉन्फ़िगरेशन संदर्भ: Claude Code, Cursor, VS Code.

लोकल ब्रिज के लिए कैनोनिकल एंट्री पॉइंट यह है:

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

इंस्टॉल किए गए MCP एक्स्ट्रा के साथ क्लाइंट के लोकल Python का उपयोग करें। इसके सुरक्षित एनवायरनमेंट में TGWITNESS_MCP_TOKEN सेट करें। क्रेडेंशियल को कमांड आर्ग्यूमेंट्स और URL से बाहर रखें। tgwitness-mcp भी समान एंट्री पॉइंट है। पुराना tgwitness.mcp_bridge मॉड्यूल और TGWITNESS_ARCHIVE_TOKEN नाम एक चेतावनी के साथ संगतता (compatibility) पथ बने हुए हैं; नई कॉन्फ़िगरेशन mcp_server और TGWITNESS_MCP_TOKEN का उपयोग करती हैं।

क्लाउडफ्लेयर टनल#

पैनल के /mcp रूट को फॉरवर्ड करें और बियरर हेडर को बनाए रखें। व्यवस्थापक (administrator) के रूप में MCP सेटिंग्स खोलने से इस रन के लिए पैनल का वर्तमान ओरिजिन रजिस्टर हो जाता है। रीस्टार्ट के तुरंत बाद उपलब्ध होने वाले स्थिर पते के लिए, पैनल शुरू करने से पहले पैनल के HTTPS ओरिजिन के साथ TGWITNESS_PUBLIC_URL को कॉन्फ़िगर करें। मनमाने (Arbitrary) Host और फॉरवर्ड किए गए हेडर्स किसी विश्वसनीय पते को रजिस्टर नहीं करते हैं। Host और Origin जांच असंबंधित ब्राउज़र ओरिजिन को अस्वीकार कर देती हैं। रिस्पॉन्स Cache-Control: no-store का उपयोग करते हैं; ऑथोराइजेशन मान कभी भी लॉग नहीं किए जाते हैं।

एक *.trycloudflare.com पता अस्थायी होता है। जब टनल रीस्टार्ट होने से होस्टनेम बदल जाता है, तो कॉन्फ़िगर किए गए पब्लिक URL और प्रत्येक क्लाइंट के MCP URL को अपडेट करें। सहेजे गए क्लाइंट कॉन्फ़िगरेशन के लिए एक स्थिर होस्टनेम का उपयोग करें।

टूल्स और सीमाएं#

टूल पढ़ता है (Reads)
list_workspaces अनुमत वर्कस्पेस
list_chats अनुमत चैट
search_messages चयनित अवधि के भीतर सहेजा गया संदेश पाठ; ranked=true पूर्ण-पाठ खोज का उपयोग करता है (शब्द रूप, सर्वश्रेष्ठ मिलान पहले, next_offset पैजिंग)
get_message_versions कैप्चर किए गए संस्करण और विलोपन (deletion) अवलोकन
get_message_context आस-पास के कैप्चर किए गए संदेश ID
get_journal_event स्रोत संदर्भ के साथ एक सैनिटाइज्ड रिकॉर्ड
get_capture_status संग्रह स्थिति, अनुमत कवरेज रिकॉर्ड और gap_summary: संदेश संख्याएँ जो कभी देखी नहीं गईं, प्रति चैनल या सुपरग्रुप और खाता-व्यापी अनुक्रम के लिए (विवरण); सूचीबद्ध अंतराल देखने के लिए किसी चैट का चयन करें
get_activity_stats UTC घंटे और सप्ताह के दिन के अनुसार संदेश, चरम दिन, संपादन और हटाने के शेयर, प्रेषक, डोमेन और @handles, कवरेज (विवरण) के साथ
get_messages_by_date एक कैलेंडर दिन के संदेश, एक नामित IANA समय क्षेत्र में सहेजे गए (Europe/Kyiv, UTC), टेलीग्राम द्वारा रिपोर्ट किए जाने तक; from_utc और until_utc गणना किया गया दिन निर्दिष्ट करें, जिसमें डेलाइट सेविंग शामिल है
get_pinned_messages नवीनतम चैट-स्टेट स्नैपशॉट में पिन किए गए संदेश अपने सहेजे गए संस्करणों के साथ, और पिन और अनपिन सूचनाएं लाइव देखी गईं
get_chat_stats एक चैट या दायरे में आने वाली हर चैट के लिए सहेजे गए रिकॉर्डों की सस्ती गिनती, पहली और आखिरी अवलोकन, और gap_summary; बड़े रीड से पहले इसका उपयोग करें
get_topics सहेजे गए टॉपिक सर्विस संदेशों से फोरम विषय: शीर्षक का इतिहास, बंद या छिपाए गए, सहेजे गए संदेशों की संख्या
get_media एक संरक्षित छवि को डाउनस्केल किए गए JPEG पूर्वावलोकन (अधिकतम 36 KB) के रूप में लौटाया जाता है, साथ ही उसकी SHA-256 और media.saved रिकॉर्ड; फ़ाइल को पहले उसके रिकॉर्ड किए गए हैश से जांचा जाता है, अन्य फ़ाइलें केवल मेटाडेटा लौटाती हैं
export_messages केवल कमांड लाइन, डिफ़ॉल्ट रूप से चयनित नहीं: सहेजे गए अवलोकनों को JSON Lines के रूप में स्ट्रीम करता है (विवरण); MCP पर उपलब्ध नहीं

प्रत्येक टूल केवल-पठन (readOnlyHint) और एक आउटपुट स्कीमा घोषित करता है; घोषित किए गए फ़ील्ड्स से परे के फ़ील्ड्स को जैसा है वैसा ही लौटा दिया जाता है। tools/list केवल उस कनेक्शन को प्रदान किए गए टूल ही लौटाता है। अन्य टूल के कॉल अस्वीकार कर दिए जाते हैं। ग्रुप-कॉन्टेक्स्ट, एपिसोड, टर्मिनोलॉजी और रिप्लाई-चेन टूल इस बिल्ड में प्रदान नहीं किए गए हैं; उनका अलग कॉन्टेक्स्ट-पैक बैकएंड शामिल नहीं है।

प्रत्येक रीड ऑपरेशन टोकन, टूल और वर्कस्पेस/चैट स्कोप की जांच करता है, जिसमें डेटाबेस का काम पूरा होने के बाद की जांच भी शामिल है। सीमाएं 60 अनुरोध प्रति मिनट, 50 रिकॉर्ड प्रति पेज, 64 KiB प्रति परिणाम और आठ-सेकंड की आर्काइव समय-सीमा (deadline) हैं। टाइम-आउट हो चुका MCP कॉल एक टूल एरर लौटाता है जो छोटी समयावधि या कम सीमा का अनुरोध करता है।

संदेश परिणामों में untrusted_content: true, वर्कस्पेस/चैट/संदेश आईडी, घटना अनुक्रम, सहेजा गया हैश और एक पैनल लिंक शामिल होते हैं। कच्चे टेलीग्राम ऑब्जेक्ट, एक्सेस हैश, सत्र और कुंजियाँ छोड़ी जाती हैं। टेक्स्ट संक्षिप्तिकरण को चिह्नित किया जाता है। संपादन, हटाने की सूचनाएँ और missing_on_recheck अलग-अलग अवलोकन हैं। कवरेज उन अवधियों को दिखाता है जिनके लिए एक परिणाम बोलता है।

कैप्चर किए गए संदेशों के अंदर के निर्देशों को सबूत के रूप में लें, न कि क्लाइंट निर्देशों के रूप में। केवल-पठन (Read-only) पहुँच संग्रह (archive) में बदलाव को रोकती है; क्लाइंट फिर भी उस सामग्री को रख सकता है जिसे पढ़ने की उसे अनुमति है। हैश सहेजे गए रिकॉर्ड की पहचान करते हैं और अखंडता जाँच (integrity checks) का समर्थन करते हैं। किसी परिणाम की समीक्षा करते समय संलग्न स्रोत संदर्भों और कवरेज रिकॉर्ड का उपयोग करें।