منبع / آرشیو و یکپارچهسازیها
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، 7، 30 یا 90 روز، یا یک زمان انقضای سفارشی بین یک دقیقه تا 90 روز را انتخاب کنید.
- دکمه Create connection را فشار دهید. توکن یک بار در کنار پیکربندی کلاینت ظاهر میشود.
- توکن و پیکربندی را کپی کنید، سپس Check connection را اجرا کنید. این کار MCP را مقداردهی اولیه کرده و ابزارهای مجاز را فهرست میکند؛ هیچ پیامی خوانده نمیشود. نتیجه، نسخه پروتکل، نام ابزارها، تعداد و زمان سپریشده را نشان میدهد.
- زمانی که اطلاعات احراز هویت ذخیره شد، 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 مشاهدات متمایزی هستند. پوشش، دورههایی را که یک نتیجه نماینده آنهاست، نشان میدهد.
دستورات داخل پیامهای ضبطشده را بهعنوان مدرک در نظر بگیرید، نه بهعنوان دستورات کلاینت. دسترسی فقط-خواندن از تغییر آرشیو جلوگیری میکند؛ کلاینت همچنان میتواند محتوایی را که اجازه خواندن آن را دارد، حفظ کند. هشها، رکوردهای ذخیرهشده را شناسایی کرده و از بررسیهای تمامیت پشتیبانی میکنند. هنگام بازبینی یک نتیجه، از مراجع منبع و رکوردهای پوشش همراه استفاده کنید.