TgWitness / مستندسازی

آنچه آزمایش شده است ←

منبع / آرشیو و یکپارچه‌سازی‌ها

Telegram · MCP فقط-خواندنی

یک کلاینت MCP را به فضاهای کاری و چت‌های منتخب با دسترسی منقضی‌شونده و قابل فسخ متصل کنید.

TgWitness / مستندسازی · یکپارچه‌سازی‌های آرشیو

یکپارچه‌سازی‌های آرشیو

یک کلاینت تحلیلگر را به فضاهای کاری و چت‌های منتخب متصل کنید. TgWitness در فرآیند پنل، HTTP قابل جریانی‌سازی را در /mcp ارائه می‌دهد. هر اتصال دارای توکن، تاریخ انقضا و ابزارهای مجاز خاص خود است. MCP نمی‌تواند پیام‌های تلگرام ارسال کند، تنظیمات را تغییر دهد یا دفترچه یادداشت امضا شده را اصلاح کند. همین اتصالات با خط فرمان نیز کار می‌کنند.

راهنمای گردش کار · ویکی

در این صفحه

نصب و بررسی#

از محیط پایتونی استفاده کنید که پنل را اجرا می‌کند. از یک نسخه دریافت‌شده از سورس:

# 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 وضعیت زمان اجرا و یک دستور نصب را با استفاده از فایل اجرایی پایتون واقعی آن سرور نشان می‌دهد. گزینه بازبینی (Re-check) این وضعیت را بدون بارگذاری مجدد صفحه تازه می‌کند؛ این گزینه بسته‌ها را نصب یا سرور را مجدداً راه‌اندازی نمی‌کند.

MCP extra از SDK رسمی MCP Python استفاده می‌کند.deploy/constraints-mcp.txt SDK آزمایش‌شده و وابستگی‌ها را ثابت می‌کند.

صدور یک اتصال#

  1. یک برچسب وارد کنید و محیط‌های کاری و چت‌هایی را که کلاینت مجاز به خواندن آن‌هاست انتخاب کنید.
  2. ابزارها را به‌صورت تکی انتخاب کنید یا از یک پیش‌تنظیم استفاده کنید. تنها ابزارهای پیاده‌سازی‌شده ارائه می‌شوند.
  3. مدت 1، 7، 30 یا 90 روز، یا یک زمان انقضای سفارشی بین یک دقیقه تا 90 روز را انتخاب کنید.
  4. دکمه Create connection را فشار دهید. توکن یک بار در کنار پیکربندی کلاینت ظاهر می‌شود.
  5. توکن و پیکربندی را کپی کنید، سپس Check connection را اجرا کنید. این کار MCP را مقداردهی اولیه کرده و ابزارهای مجاز را فهرست می‌کند؛ هیچ پیامی خوانده نمی‌شود. نتیجه، نسخه پروتکل، نام ابزارها، تعداد و زمان سپری‌شده را نشان می‌دهد.
  6. زمانی که اطلاعات احراز هویت ذخیره شد، Done را فشار دهید. بررسی دوره‌ای (Polling) فرم و کارت یک‌بارمصرف نمایش‌داده‌شده را حفظ می‌کند. قفل کردن پنل، اطلاعات محرمانه نمایش‌داده‌شده را پاک می‌کند.

این فهرست استفاده اخیر، آخرین ابزار، آدرس و درخواست‌ها در دقیقه گذشته را نشان می‌دهد. گزینه Revoke دسترسی را پایان می‌دهد. گزینه Rotate token اعتبارنامه قدیمی را باطل کرده و یک جایگزین با همان محدوده، ابزارها و تاریخ انقضا صادر می‌کند؛ جایگزین را یک بار کپی کنید. توکن‌های ورود به پنل و اعتبارنامه‌های تلگرام به‌عنوان توکن‌های MCP کار نمی‌کنند.

اتصال کلاینت شما#

کلاینت را در پنل انتخاب کنید و پیکربندی تولیدشده آن را کپی کنید. پیکربندی‌ها از ارجاعات محرمانه یا متغیرهای جایگزین صریح استفاده می‌کنند؛ توکن به‌صورت جداگانه کپی می‌شود.

کلاینت پیکربندی اتصال
کد کلاود .mcp.json HTTP، type: "http"، هدر bearer
کلود دسکتاپ claude_desktop_config.json پل محلی stdio
Cursor .cursor/mcp.json HTTP با یک هدر متغیر محیطی
کد محلی VS Code .vscode/mcp.json HTTP با یک ورودی رمز عبور promptString
Windsurf mcp_config.json HTTP با یک متغیر جایگزین هدر bearer
سایر کلاینت‌ها URL و هدر Authorization HTTP قابل پخش

TgWitness از توکن‌های bearer بدون اکتشاف OAuth استفاده می‌کند. برای کلاینت‌هایی که اتصال‌دهنده راه‌دور آن‌ها نیازمند OAuth است، از پل محلی stdio استفاده کنید. برای VS Code، متغیرهای ورودی روی بستر Local اعمال می‌شوند و به نشست‌های Copilot ارسال نمی‌گردند. مراجع پیکربندی: Claude Code، Cursor، VS Code.

نقطه ورود استاندارد برای یک پل محلی عبارت است از:

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

از پایتون محلی کلاینت که افزونه MCP روی آن نصب شده است استفاده کنید. متغیر TGWITNESS_MCP_TOKEN را در محیط حفاظت‌شده آن تنظیم کنید. اطلاعات احراز هویت را خارج از آرگومان‌های دستور و URLها نگه دارید. دستور tgwitness-mcp همان نقطه ورود است. ماژول قدیمی tgwitness.mcp_bridge و نام TGWITNESS_ARCHIVE_TOKEN به‌عنوان مسیرهای سازگاری همراه با یک هشدار باقی می‌مانند؛ پیکربندی‌های جدید از mcp_server و TGWITNESS_MCP_TOKEN استفاده می‌کنند.

تونل کلودفلر#

مسیر /mcp پنل را فوروارد کرده و هدر bearer را حفظ کنید. باز کردن تنظیمات MCP به‌عنوان مدیر، مبدأ (Origin) فعلی پنل را برای این نوبت اجرا ثبت می‌کند. برای داشتن یک آدرس پایدار که بلافاصله پس از راه‌اندازی مجدد در دسترس باشد، پیش از شروع پنل، متغیر TGWITNESS_PUBLIC_URL را با مبدأ HTTPS پنل پیکربندی کنید. هدرهای دلخواه Host و فورواردشده، یک آدرس مورد اعتماد را ثبت نمی‌کنند. بررسی‌های Host و Origin، مبدأهای مرورگر نامرتبط را رد می‌کنند. پاسخ‌ها از Cache-Control: no-store استفاده می‌کنند؛ مقادیر احراز هویت هرگز در گزارش‌ها (لاگ) ثبت نمی‌شوند.

یک آدرس *.trycloudflare.com موقتی است. هنگامی که راه‌اندازی مجدد تونل نام میزبان (hostname) را تغییر می‌دهد، URL عمومی پیکربندی‌شده و URL مربوط به MCP هر کلاینت را به‌روزرسانی کنید. برای پیکربندی‌های ذخیره‌شده کلاینت، از یک نام میزبان پایدار استفاده کنید.

ابزارها و مرزها#

ابزار موارد قابل خواندن
list_workspaces محیط‌های کاری مجاز
list_chats چت‌های مجاز
search_messages متن پیام‌های ذخیره شده در بازهٔ زمانی انتخاب‌شده؛ ranked=true از جستجوی تمام‌متنی استفاده می‌کند (شکل‌های کلمات، بهترین تطابق‌ها در اولویت، next_offset صفحه‌بندی)
get_message_versions نسخه‌های ثبت‌شده و مشاهدات مربوط به حذف
get_message_context شناسه‌های پیام‌های ثبت‌شده در مجاورت
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 با کاهش وضوح (حداکثر ۳۶ کیلوبایت)، که همراه با SHA-256 خود و media.saved ثبت؛ فایل ابتدا با هش ثبت‌شده خود مطابقت داده می‌شود، سایر فایل‌ها فقط متادیتا را بازمی‌گردانند
export_messages فقط خط فرمان، به‌صورت پیش‌فرض انتخاب نشده است: جریان‌ها مشاهدات ضبط‌شده را به‌صورت JSON Lines ذخیره می‌کنند (جزئیات)؛ از طریق MCP ارائه نمی‌شود

هر ابزار فقط-خواندنی است (readOnlyHint) و یک طرح‌بندی خروجی را اعلام می‌کند؛ فیلدهایی فراتر از موارد اعلام‌شده همان‌طور که هستند بازگردانده می‌شوند. tools/list فقط ابزارهایی را بازمی‌گرداند که به آن اتصال اعطا شده‌اند. فراخوانی ابزارهای دیگر رد می‌شود. ابزارهای زمینه گروه، اپیزود، اصطلاح‌شناسی و زنجیره پاسخ در این نسخه ارائه نمی‌شوند؛ بک‌اند جداگانه بسته‌بندی زمینه آنها گنجانده نشده است.

هر عملیات خواندن، توکن، ابزار و محدوده محیط کاری/چت را بررسی می‌کند، از جمله پس از پایان کار پایگاه داده. محدودیت‌ها شامل 60 درخواست در دقیقه، 50 رکورد در هر صفحه، 64 KiB برای هر نتیجه و مهلت زمانی هشت ثانیه‌ای آرشیو است. یک فراخوانی MCP که مهلت زمانی آن به پایان رسیده باشد، خطای ابزاری را برمی‌گرداند که درخواست بازه زمانی کوتاه‌تر یا محدودیت کمتری دارد.

نتایج پیام حاوی untrusted_content: true، شناسه‌های فضای کاری/چت/پیام، توالی رویدادها، هش ذخیره شده و یک لینک پنل هستند. اشیاء خام تلگرام، هش‌های دسترسی، جلسات و کلیدها حذف شده‌اند. کوتاه شدن متن مشخص شده است. ویرایش‌ها، اعلان‌های حذف و missing_on_recheck مشاهدات متمایزی هستند. پوشش، دوره‌هایی را که یک نتیجه نماینده آن‌هاست، نشان می‌دهد.

دستورات داخل پیام‌های ضبط‌شده را به‌عنوان مدرک در نظر بگیرید، نه به‌عنوان دستورات کلاینت. دسترسی فقط-خواندن از تغییر آرشیو جلوگیری می‌کند؛ کلاینت همچنان می‌تواند محتوایی را که اجازه خواندن آن را دارد، حفظ کند. هش‌ها، رکوردهای ذخیره‌شده را شناسایی کرده و از بررسی‌های تمامیت پشتیبانی می‌کنند. هنگام بازبینی یک نتیجه، از مراجع منبع و رکوردهای پوشش همراه استفاده کنید.