TgWitness / دستاویزات

کیا جانچا گیا ہے ←

حوالہ / آرکائیو اور انضمامات

Telegram · صرف پڑھنے کے لیے MCP

ایک MCP کلائنٹ کو منتخب ورک اسپیسز اور چیٹس سے منسلک کریں، جس کی رسائی ختم ہونے والی اور منسوخ کی جانے والی ہو۔

ٹی جی وٹنس / دستاویزات · آرکائیو انٹیگریشنز

آرکائیو انٹیگریشنز

ایک تجزیہ کار کلائنٹ کو منتخب ورک اسپیسز اور چیٹس سے جوڑیں۔ TgWitness پینل کے عمل میں /mcp پر Streamable 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 پائتھن SDK استعمال کرتا ہے۔deploy/constraints-mcp.txt ٹیسٹ شدہ SDK اور انحصار کو پن کرتا ہے۔

کنکشن جاری کریں#

  1. ایک لیبل درج کریں اور وہ ورک اسپیسز اور چیٹس منتخب کریں جنہیں کلائنٹ پڑھ سکتا ہے۔
  2. ٹولز کو انفرادی طور پر منتخب کریں یا کوئی پری سیٹ استعمال کریں۔ صرف لاگو شدہ ٹولز ہی پیش کیے جاتے ہیں۔
  3. 1، 7، 30 یا 90 دن، یا ایک منٹ سے 90 دنوں کے درمیان کوئی حسبِ منشا میعاد منتخب کریں۔
  4. Create connection دبائیں۔ ٹوکن کلائنٹ کنفیگ کے ساتھ صرف ایک بار ظاہر ہوتا ہے۔
  5. ٹوکن اور کنفیگ کاپی کریں، پھر Check connection چلائیں۔ یہ MCP کو انیشیئلائز کرتا ہے اور مجاز ٹولز کی فہرست دکھاتا ہے؛ کوئی پیغام نہیں پڑھا جاتا۔ نتیجہ پروٹوکول ورژن، ٹول کے نام، تعداد اور گزرے ہوئے وقت کو ظاہر کرتا ہے۔
  6. کریڈینشل محفوظ ہو جانے کے بعد Done دبائیں۔ پولنگ فارم اور ایک بار دکھائے جانے والے کارڈ کو برقرار رکھتی ہے۔ پینل کو لاک کرنے سے اسکرین پر موجود سیکرٹس صاف ہو جاتے ہیں۔

فہرست میں حالیہ استعمال، آخری ٹول، ایڈریس اور گزشتہ منٹ کی ریکویسٹس دکھائی جاتی ہیں۔ Revoke رسائی ختم کر دیتا ہے۔ Rotate token پرانے کریڈینشل کو منسوخ کر دیتا ہے اور اسی اسکوپ، ٹولز اور میعاد کے ساتھ ایک متبادل جاری کرتا ہے؛ متبادل کو ایک بار کاپی کر لیں۔ پینل لاگ ان ٹوکنز اور ٹیلی گرام کریڈینشلز 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

کلائنٹ کا لوکل Python استعمال کریں جس میں MCP ایکسٹرا انسٹال ہو۔ اس کے محفوظ انوائرنمنٹ میں TGWITNESS_MCP_TOKEN سیٹ کریں۔ کریڈینشلز کو کمانڈ آرگومنٹس اور URLs سے دور رکھیں۔ tgwitness-mcp بھی وہی انٹری پوائنٹ ہے۔ پرانا tgwitness.mcp_bridge ماڈیول اور TGWITNESS_ARCHIVE_TOKEN نام وارننگ کے ساتھ مطابقت کے راستوں کے طور پر برقرار ہیں؛ نئی کنفیگز mcp_server اور TGWITNESS_MCP_TOKEN استعمال کرتی ہیں۔

کلوڈ فلئیر ٹنل#

پینل کے /mcp راؤٹ کو فارورڈ کریں اور بیئرر ہیڈر کو برقرار رکھیں۔ بطور ایڈمنسٹریٹر MCP سیٹنگز کھولنے سے اس رن کے لیے پینل کا موجودہ اوریجن رجسٹر ہو جاتا ہے۔ ری اسٹارٹ کے فوراً بعد دستیاب ہونے والے مستحکم ایڈریس کے لیے، پینل اسٹارٹ کرنے سے پہلے پینل کے HTTPS اوریجن کے ساتھ TGWITNESS_PUBLIC_URL کو کنفیگر کریں۔ فرضی Host اور فارورڈ کردہ ہیڈرز کسی قابلِ اعتماد ایڈریس کو رجسٹر نہیں کرتے۔ Host اور Origin چیکس غیر متعلقہ براؤزر اوریجنز کو مسترد کر دیتے ہیں۔ ریسپانسز Cache-Control: no-store استعمال کرتے ہیں؛ آتھورائزیشن ویلیوز کو کبھی لاگ نہیں کیا جاتا۔

*.trycloudflare.com ایڈریس عارضی ہوتا ہے۔ جب ٹنل کے ری اسٹارٹ ہونے سے ہوسٹ نیم تبدیل ہو جائے، تو کنفیگر کردہ پبلک URL اور ہر کلائنٹ کے MCP URL کو اپ ڈیٹ کریں۔ محفوظ کردہ کلائنٹ کنفیگریشنز کے لیے ایک مستحکم ہوسٹ نیم استعمال کریں۔

ٹولز اور حدود#

ٹول پڑھتا ہے
list_workspaces مجاز ورک اسپیسز
list_chats مجاز چیٹس
search_messages منتخب مدت کے دوران محفوظ کردہ پیغام کا متن؛ ranked=true مکمل متن کی تلاش استعمال کرتا ہے (لفظی شکلوں کے ساتھ، بہترین مماثل پہلے، next_offset صفحہ بندی)
get_message_versions کیپچر کیے گئے ورژنز اور حذف کیے جانے کے مشاہدات
get_message_context قریبی کیپچر کیے گئے پیغام کی IDs
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 صرف کمانڈ لائن، بطورِ ڈیفالٹ منتخب نہیں: streams محفوظ شدہ مشاہدات کو JSON Lines کے طور پر محفوظ کرتا ہے (تفصیلات)؛ MCP کے ذریعے دستیاب نہیں۔

ہر ٹول صرف پڑھنے کے لیے ہے (readOnlyHint) اور ایک آؤٹ پٹ اسکیما کا اعلان کرتا ہے؛ اعلان شدہ فیلڈز کے علاوہ باقی فیلڈز کو جیسا ہے ویسا واپس کیا جاتا ہے۔ tools/list صرف اُس کنکشن کو دیے گئے ٹولز واپس کرتا ہے۔ دوسرے ٹولز کو کالز مسترد کر دی جاتی ہیں۔ گروپ-کنٹیکسٹ، ایپی سوڈ، ٹرمینالوجی اور ریپلائی-چین ٹولز اس بلڈ میں پیش نہیں کیے گئے؛ ان کا الگ کنٹیکسٹ-پیک بیک اینڈ شامل نہیں ہے۔

ہر ریڈ آپریشن ٹوکن، ٹول اور ورک اسپیس/چیٹ کے اسکوپ کو چیک کرتا ہے، بشمول ڈیٹا بیس کا کام مکمل ہونے کے بعد۔ حدود 60 ریکویسٹس فی منٹ، 50 ریکارڈز فی صفحہ، 64 KiB فی نتیجہ اور آٹھ سیکنڈ کی آرکائیو ڈیڈ لائن ہیں۔ ٹائم آؤٹ ہونے والی MCP کال ایک ٹول ایرر واپس کرتی ہے جس میں کم مدت یا کم حد استعمال کرنے کا کہا جاتا ہے۔

پیغام کے نتائج میں untrusted_content: true، ورک اسپیس/چیٹ/پیغام کے آئی ڈی، واقعات کا تسلسل، محفوظ شدہ ہیش اور ایک پینل لنک شامل ہوتا ہے۔ خام ٹیلیگرام آبجیکٹس، رسائی ہیشز، سیشنز اور کیز کو خارج کر دیا گیا ہے۔ متن کی کٹوتی کو نشان زد کیا گیا ہے۔ ترامیم، حذف کرنے کے نوٹس اور missing_on_recheck الگ الگ مشاہدات ہیں۔ کوریج اُن ادوار کو دکھاتی ہے جن کی نتیجہ نمائندگی کرتا ہے۔

پکڑے گئے پیغامات میں موجود ہدایات کو ثبوت کے طور پر لیں، نہ کہ کلائنٹ کی ہدایات کے طور پر۔ صرف پڑھنے کی اجازت آرکائیو میں تبدیلیوں کو روکتی ہے؛ کلائنٹ پھر بھی وہ مواد محفوظ رکھ سکتا ہے جسے پڑھنے کی اجازت اسے حاصل ہو۔ ہیشز محفوظ شدہ ریکارڈز کی شناخت کرتے ہیں اور سالمیت کی جانچ کی حمایت کرتے ہیں۔ کسی نتیجے کا جائزہ لیتے وقت ساتھ دیے گئے ماخذ حوالہ جات اور کوریج ریکارڈز کا استعمال کریں۔