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

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

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

[Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/)

[Documentation index](https://phishdestroy.io/tgwitness/fa/llms.txt)

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

[TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [مستندسازی](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [یکپارچه‌سازی‌های آرشیو](https://phishdestroy.io/tgwitness/fa/docs/reference/cli/)

![یکپارچه‌سازی‌های آرشیو](https://phishdestroy.io/tgwitness/assets/chapter-integrations.svg?v=367d9d210074)

یک کلاینت تحلیلگر را به فضاهای کاری و چت‌های منتخب متصل کنید. TgWitness **در فرآیند پنل، HTTP قابل جریانی‌سازی را در `/mcp`** ارائه می‌دهد. هر اتصال دارای توکن، تاریخ انقضا و ابزارهای مجاز خاص خود است. MCP نمی‌تواند پیام‌های تلگرام ارسال کند، تنظیمات را تغییر دهد یا دفترچه یادداشت امضا شده را اصلاح کند. همین اتصالات با [خط فرمان](https://phishdestroy.io/tgwitness/fa/docs/reference/cli/)نیز کار می‌کنند.

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

**در این صفحه**

- [نصب و بررسی](https://phishdestroy.io/tgwitness/fa/docs/reference/mcp/#install-and-check)
- [ایجاد یک اتصال](https://phishdestroy.io/tgwitness/fa/docs/reference/mcp/#issue-a-connection)
- [کلاینت خود را وصل کنید](https://phishdestroy.io/tgwitness/fa/docs/reference/mcp/#connect-your-client)
- [تونل کلودفلر](https://phishdestroy.io/tgwitness/fa/docs/reference/mcp/#cloudflare-tunnel)
- [ابزارها و مرزها](https://phishdestroy.io/tgwitness/fa/docs/reference/mcp/#tools-and-boundaries)

## نصب و بررسی

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

```
# 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](https://github.com/modelcontextprotocol/python-sdk) استفاده می‌کند.`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](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` استفاده می‌کنند.

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

مسیر `/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` از [جستجوی تمام‌متنی](https://phishdestroy.io/tgwitness/fa/docs/reference/search/) استفاده می‌کند (شکل‌های کلمات، بهترین تطابق‌ها در اولویت، `next_offset` صفحه‌بندی) |
| `get_message_versions` | نسخه‌های ثبت‌شده و مشاهدات مربوط به حذف |
| `get_message_context` | شناسه‌های پیام‌های ثبت‌شده در مجاورت |
| `get_journal_event` | یک رکورد پاک‌سازی‌شده به همراه مرجع منبع آن |
| `get_capture_status` | وضعیت جمع‌آوری، سوابق پوشش مجاز و `gap_summary`: شماره‌های پیام‌هایی که هرگز مشاهده نشده‌اند، به تفکیک کانال یا ابرگروه و برای توالی در سطح حساب ([جزئیات](https://phishdestroy.io/tgwitness/fa/docs/reference/evidence/#missing-message-numbers-gap_summary))؛ یک چت را انتخاب کنید تا فواصل فهرست‌شده آن را ببینید |
| `get_activity_stats` | پیام‌ها بر اساس ساعت UTC و روز هفته، روزهای اوج، اشتراک‌گذاری ویرایش و حذف، فرستندگان، دامنه‌ها و `@handles`، همراه با پوشش ([جزئیات](https://phishdestroy.io/tgwitness/fa/docs/reference/cli/#activity-statistics)) |
| `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 ذخیره می‌کنند ([جزئیات](https://phishdestroy.io/tgwitness/fa/docs/reference/cli/#export))؛ از طریق MCP ارائه نمی‌شود |

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

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

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

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