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

केवल-पठनीय MCP

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

किसी एनालिस्ट क्लाइंट को चुनिंदा वर्कस्पेस और चैट से कनेक्ट करें। TgWitness पैनल प्रोसेस में /mcp पर Streamable HTTP सर्व करता है। प्रत्येक कनेक्शन का अपना टोकन, समाप्ति (expiry) और अनुमत टूल्स होते हैं। 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

इंस्टॉलेशन के बाद पैनल को उसकी सामान्य डेटा डायरेक्टरी और लॉन्च आर्ग्यूमेंट्स के साथ रीस्टार्ट करें। तत्परता (Readiness) जांच में [PASS] mcp: streamable-http available शामिल होना चाहिए। Integrations → MCP उस सर्वर के वास्तविक Python एक्जीक्यूटेबल का उपयोग करते हुए रनटाइम स्थिति और इंस्टॉलेशन कमांड दिखाता है। Re-check पेज को रीलोड किए बिना इस स्थिति को रीफ्रेश करता है; यह पैकेज इंस्टॉल नहीं करता है या सर्वर को रीस्टार्ट नहीं करता है।

MCP एक्स्ट्रा आधिकारिक MCP Python SDK का उपयोग करता है। deploy/constraints-mcp.txt परीक्षित SDK और डिपेंडेंसी को पिन करता है। इन सुविधाओं के लिए वर्तमान सोर्स आवश्यक है; 0.7.0 पोर्टेबल प्रीव्यू इनसे पहले का है।

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

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

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

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

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

क्लाइंट	कॉन्फ़िगरेशन	कनेक्शन
Claude Code	`.mcp.json`	HTTP, `type: "http"`, बियरर हेडर
Claude Desktop	`claude_desktop_config.json`	लोकल stdio ब्रिज
Cursor	`.cursor/mcp.json`	एनवायरनमेंट-वेरिएबल हेडर के साथ HTTP
VS Code Local	`.vscode/mcp.json`	पासवर्ड `promptString` इनपुट के साथ HTTP
Windsurf	`mcp_config.json`	बियरर-हेडर प्लेसहोल्डर के साथ HTTP
अन्य क्लाइंट	URL और Authorization हेडर	Streamable 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 का उपयोग करती हैं।

Cloudflare Tunnel#

पैनल के /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`	चुनी गई अवधि के भीतर सहेजा गया संदेश टेक्स्ट
`get_message_versions`	कैप्चर किए गए संस्करण और विलोपन (deletion) अवलोकन
`get_message_context`	आस-पास के कैप्चर किए गए संदेश ID
`get_journal_event`	स्रोत संदर्भ के साथ एक सैनिटाइज्ड रिकॉर्ड
`get_capture_status`	संग्रह की स्थिति और अनुमत कवरेज रिकॉर्ड

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

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

संदेश परिणामों में untrusted_content: true, वर्कस्पेस/चैट/संदेश ID, इवेंट अनुक्रम, सहेजा गया हैश और एक पैनल लिंक होता है। कच्चे (Raw) Telegram ऑब्जेक्ट, एक्सेस हैश, सेशन और कुंजियां (keys) छोड़ दी जाती हैं। टेक्स्ट के काटे जाने (truncation) को चिह्नित किया जाता है। संपादन, विलोपन सूचनाएं और missing_on_recheck अलग-अलग अवलोकन हैं। अनुपलब्ध रिकॉर्ड यह साबित नहीं करते कि कोई घटना कभी हुई ही नहीं थी।

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