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

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

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

یک کلاینت تحلیل‌گر را به محیط‌های کاری و چت‌های انتخاب‌شده متصل کنید. TgWitness پروتکل Streamable 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 باشد. مسیر Integrations → MCP وضعیت زمان اجرا و دستور نصب را با استفاده از فایل اجرایی واقعی پایتون آن سرور نشان می‌دهد. گزینه Re-check این وضعیت را بدون بارگذاری مجدد صفحه به‌روزرسانی می‌کند؛ این گزینه بسته‌ها را نصب نمی‌کند و سرور را مجدداً راه‌اندازی نمی‌کند.

افزونه MCP از MCP Python SDK رسمی استفاده می‌کند. فایل deploy/constraints-mcp.txt نسخه تست‌شده SDK و وابستگی‌ها را ثابت نگه می‌دارد. این قابلیت‌ها نیازمند سورس فعلی هستند؛ پیش‌نمایش قابل حمل 0.7.0 پیش از آن‌ها منتشر شده است.

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

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

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

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

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

کلاینت	پیکربندی	اتصال
Claude Code	`.mcp.json`	HTTP، `type: "http"`، هدر bearer
Claude Desktop	`claude_desktop_config.json`	پل محلی stdio
Cursor	`.cursor/mcp.json`	HTTP با یک هدر متغیر محیطی
VS Code Local	`.vscode/mcp.json`	HTTP با یک ورودی رمز عبور `promptString`
Windsurf	`mcp_config.json`	HTTP با یک متغیر جایگزین هدر bearer
سایر کلاینت‌ها	URL و هدر Authorization	Streamable 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 استفاده می‌کنند.

Cloudflare Tunnel#

مسیر /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`	متن پیام‌های ذخیره‌شده در بازه زمانی انتخاب‌شده
`get_message_versions`	نسخه‌های ثبت‌شده و مشاهدات مربوط به حذف
`get_message_context`	شناسه‌های پیام‌های ثبت‌شده در مجاورت
`get_journal_event`	یک رکورد پاک‌سازی‌شده به همراه مرجع منبع آن
`get_capture_status`	وضعیت جمع‌آوری و رکوردهای پوشش مجاز

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

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

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

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