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

Canonical page: https://phishdestroy.github.io/TgWitness/fa/docs/reference/mcp/

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

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

[راهنمای گردش کار](https://phishdestroy.github.io/TgWitness/docs/archive/) · [ویکی](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Archive-and-Integrations.md)

## نصب و بررسی

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

```
# 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](https://github.com/modelcontextprotocol/python-sdk) رسمی استفاده می‌کند. فایل `deploy/constraints-mcp.txt` نسخه تست‌شده SDK و وابستگی‌ها را ثابت نگه می‌دارد. این قابلیت‌ها نیازمند سورس فعلی هستند؛ پیش‌نمایش قابل حمل 0.7.0 پیش از آن‌ها منتشر شده است.

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

1. یک برچسب وارد کنید و محیط‌های کاری و چت‌هایی را که کلاینت مجاز به خواندن آن‌هاست انتخاب کنید.
2. ابزارها را به‌صورت تکی انتخاب کنید یا از یک پیش‌تنظیم استفاده کنید. تنها ابزارهای پیاده‌سازی‌شده ارائه می‌شوند.
3. مدت 1، 7، 30 یا 90 روز، یا یک زمان انقضای سفارشی بین یک دقیقه تا 90 روز را انتخاب کنید.
4. دکمه **Create connection** را فشار دهید. توکن یک بار در کنار پیکربندی کلاینت ظاهر می‌شود.
5. توکن و پیکربندی را کپی کنید، سپس **Check connection** را اجرا کنید. این کار MCP را مقداردهی اولیه کرده و ابزارهای مجاز را فهرست می‌کند؛ **هیچ پیامی خوانده نمی‌شود**. نتیجه، نسخه پروتکل، نام ابزارها، تعداد و زمان سپری‌شده را نشان می‌دهد.
6. زمانی که اطلاعات احراز هویت ذخیره شد، **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](https://code.claude.com/docs/en/mcp)، [Cursor](https://prod.cursor.com/docs/mcp)، [VS Code](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).

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

```
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` مشاهداتی متمایز هستند. نبود رکوردها ثابت نمی‌کند که یک رویداد هرگز رخ نداده است.

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