# Telegram · MCP للقراءة فقط

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

قم بتوصيل عميل MCP بمساحات العمل والدردشات المحددة مع وصول قابل للانتهاء وقابل للإلغاء.

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

[Documentation index](https://phishdestroy.io/tgwitness/ar/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/ar/docs/reference/cli/)

![تكاملات الأرشيف](https://phishdestroy.io/tgwitness/assets/chapter-integrations.svg)

قم بتوصيل عميل المحلل بمساحات العمل والدردشات المحددة. تقدم TgWitness خدمة **Streamable HTTP على `/mcp` في عملية اللوحة**. لكل اتصال رمز مميز خاص به، وتاريخ انتهاء صلاحية، وأدوات مسموح بها. لا يمكن لـ MCP إرسال رسائل Telegram، أو تغيير الإعدادات، أو تعديل السجل الموقّع. تعمل نفس الاتصالات مع [سطر الأوامر](https://phishdestroy.io/tgwitness/ar/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/ar/docs/reference/mcp/#install-and-check)
- [إنشاء اتصال](https://phishdestroy.io/tgwitness/ar/docs/reference/mcp/#issue-a-connection)
- [قم بتوصيل عميلك](https://phishdestroy.io/tgwitness/ar/docs/reference/mcp/#connect-your-client)
- [Cloudflare Tunnel](https://phishdestroy.io/tgwitness/ar/docs/reference/mcp/#cloudflare-tunnel)
- [الأدوات والحدود](https://phishdestroy.io/tgwitness/ar/docs/reference/mcp/#tools-and-boundaries)

## التثبيت والتحقق

استخدم بيئة Python التي تُشغِّل لوحة التحكم. من نسخة الكود المصدري:

```
# 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** تعرض حالة وقت التشغيل وأمر التثبيت باستخدام ملف Python القابل للتنفيذ الفعلي لذلك الخادم. تؤدي **إعادة التحقق** إلى تحديث هذه الحالة دون إعادة تحميل الصفحة؛ ولا تقوم بتثبيت الحزم أو إعادة تشغيل الخادم.

يستخدم المكون الإضافي MCP حزمة [SDK الرسمية لـ MCP بلغة Python](https://github.com/modelcontextprotocol/python-sdk). يحدد ملف`deploy/constraints-mcp.txt` إصدار SDK الذي تم اختباره والتبعيات.

## إصدار اتصال

1. أدخل تسمية واختر مساحات العمل والمحادثات التي يُسمح للعميل بقراءتها.
2. حدد الأدوات بشكل فردي أو استخدم إعدادًا مسبقًا. يتم عرض الأدوات المُنفَّذة فقط.
3. اختر يومًا واحدًا أو 7 أو 30 أو 90 يومًا، أو تاريخ انتهاء صلاحية مخصص يتراوح بين دقيقة واحدة و90 يومًا.
4. اضغط على **Create connection**. يظهر الرمز مرة واحدة بجانب إعدادات العميل.
5. انسخ الرمز والإعدادات، ثم شغِّل **Check connection**. سيقوم بتهيئة MCP وسرد الأدوات المسموح بها؛ **ولا تتم قراءة أي رسائل**. تعرض النتيجة إصدار البروتوكول وأسماء الأدوات وعددها والوقت المنقضي.
6. اضغط على **Done** عند حفظ بيانات الاعتماد. يحافظ الاستطلاع الدوري على النموذج وعلى البطاقة التي تُعرَض لمرة واحدة. يؤدي قفل لوحة التحكم إلى مسح الأسرار المعروضة.

تعرض القائمة الاستخدام الأخير وآخر أداة استُخدمت والعنوان والطلبات خلال الدقيقة الأخيرة. يُنهي الزر **Revoke** صلاحية الوصول. أما الزر **Rotate token** فيُلغي بيانات الاعتماد القديمة ويُصدر بديلاً بنفس النطاق والأدوات وتاريخ الانتهاء؛ انسخ البديل لمرة واحدة. لا تعمل رموز تسجيل الدخول إلى لوحة التحكم ولا بيانات اعتماد تيليجرام كرموز لـ MCP.

## ربط العميل الخاص بك

حدد العميل في لوحة التحكم وانسخ إعداداته المُولَّدة. تستخدم الإعدادات مراجع الأسرار أو عناصر نائبة صريحة؛ ويتم نسخ الرمز بشكل منفصل.

| العميل | الإعدادات | الارتباط |
| --- | --- | --- |
| كود كلود | `.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 | HTTP القابل للبث |

يستخدم TgWitness رموز bearer دون اكتشاف OAuth. استخدم جسر stdio المحلي للعملاء الذين يتطلب موصلهم البعيد استخدام OAuth. بالنسبة لـ 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
```

استخدم بيئة Python المحلية الخاصة بالعميل مع تثبيت إضافة 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` مؤقتًا. عندما تؤدي إعادة تشغيل النفق إلى تغيير اسم المضيف، قُم بتحديث عنوان URL العام المُعَدّ وعنوان URL الخاص بـ MCP لكل عميل. استخدم اسم مضيف مستقرًا لإعدادات العملاء المحفوظة.

## الأدوات والحدود

| الأداة | ما تقرؤه |
| --- | --- |
| `list_workspaces` | مساحات العمل الممنوحة |
| `list_chats` | المحادثات الممنوحة |
| `search_messages` | نص الرسائل المحفوظة خلال الفترة المحددة؛ `ranked=true` يستخدم [البحث عن النص الكامل](https://phishdestroy.io/tgwitness/ar/docs/reference/search/) (أشكال الكلمات، أفضل النتائج أولاً، `next_offset` التصفح) |
| `get_message_versions` | الإصدارات الملتقطة وملاحظات الحذف |
| `get_message_context` | مُعرِّفات الرسائل الملتقطة المجاورة |
| `get_journal_event` | سجل واحد مُنقّى مع مرجع مصدره |
| `get_capture_status` | حالة التجميع، وسجلات التغطية المسموح بها، و `gap_summary`: أرقام الرسائل التي لم يتم رصدها مطلقًا، لكل قناة أو مجموعة فرعية وعلى مستوى التسلسل الخاص بالحساب ([التفاصيل](https://phishdestroy.io/tgwitness/ar/docs/reference/evidence/#missing-message-numbers-gap_summary))؛ اختر محادثة لترى الفجوات المدرجة فيها |
| `get_activity_stats` | الرسائل حسب الساعة وفقًا للتوقيت العالمي المنسق (UTC) ويوم الأسبوع، وأيام الذروة، ونسب التعديل والحذف، والمرسلين، والمجالات، و `@handles`، مع التغطية ([التفاصيل](https://phishdestroy.io/tgwitness/ar/docs/reference/cli/#activity-statistics)) |
| `get_messages_by_date` | الرسائل المحفوظة ليوم تقويمي واحد في منطقة زمنية محددة من IANA (`Europe/Kyiv`, `UTC`)، وفقًا للوقت الذي يبلغ عنه Telegram؛ `from_utc` و `until_utc` اذكر اليوم المحسوب، بما في ذلك التوقيت الصيفي |
| `get_pinned_messages` | الرسائل المثبتة في أحدث لقطة لحالة الدردشة مع نسخها المحفوظة، وإشعارات التثبيت وإلغاء التثبيت التي يتم رصدها في الوقت الفعلي |
| `get_chat_stats` | عدد السجلات المحفوظة لكل دردشة أو لكل الدردشات المشمولة، والملاحظة الأولى والأخيرة، و `gap_summary`؛ استخدمها قبل القراءة الكبيرة |
| `get_topics` | مواضيع المنتدى من رسائل خدمة المواضيع المحفوظة: سجل العناوين، والمواضيع المغلقة أو المخفية، وعدد الرسائل المحفوظة |
| `get_media` | صورة محفوظة كمعاينة JPEG مخفضة الدقة (بحد أقصى 36 كيلوبايت)، تُعاد كصورة مع قيمة SHA-256 الخاصة بها و `media.saved` السجل؛ يتم التحقق من الملف أولاً بمقارنته بـ«هاش» المسجل الخاص به، بينما تُرجع الملفات الأخرى البيانات الوصفية فقط |
| `export_messages` | تعمل عبر سطر الأوامر فقط، وليست محددة بشكل افتراضي: تقوم ببث الملاحظات المحفوظة كسطور JSON ([التفاصيل](https://phishdestroy.io/tgwitness/ar/docs/reference/cli/#export))؛ ولا تتوفر عبر MCP |

كل أداة هي للقراءة فقط (`readOnlyHint`) وتعلن عن مخطط إخراج؛ أما الحقول التي تتجاوز تلك المعلنة فيتم إرجاعها كما هي. `tools/list` تُرجع فقط الأدوات الممنوحة لهذا الاتصال. يتم رفض استدعاءات الأدوات الأخرى. لا تتوفر أدوات سياق المجموعة، والحلقة، والمصطلحات، وسلسلة الردود في هذا الإصدار؛ حيث لم يتم تضمين الخلفية المنفصلة لحزمة السياق الخاصة بها.

تتحقق كل عملية قراءة من الرمز والأداة ونطاق مساحة العمل/المحادثة، بما في ذلك بعد انتهاء عمل قاعدة البيانات. تبلغ الحدود 60 طلبًا في الدقيقة، و50 سجلاً لكل صفحة، و64 KiB لكل نتيجة، ومهلة ثماني ثوانٍ للأرشيف. يُعيد استدعاء MCP الذي انتهت مهلته خطأ أداة يطلب فترة أضيق أو حدًا أقل.

تحتوي نتائج الرسائل على `untrusted_content: true`، ومعرّفات مساحة العمل/الدردشة/الرسالة، وتسلسل الأحداث، والتجزئة المحفوظة، ورابط اللوحة. يتم حذف كائنات Telegram الأولية، وتجزئات الوصول، والجلسات، والمفاتيح. يتم تمييز النصوص المقطوعة. تعتبر التعديلات وإشعارات الحذف و`missing_on_recheck` ملاحظات منفصلة. تُظهر التغطية الفترات التي تمثلها النتيجة.

تعامل مع التعليمات الموجودة داخل الرسائل الملتقطة كأدلة، ولا تعاملها أبدًا على أنها تعليمات خاصة بالعميل . يمنع الوصول للقراءة فقط إجراء تغييرات على الأرشيف؛ ولا يزال بإمكان العميل الاحتفاظ بالمحتوى المسموح له بقراءته. تحدد التجزئات السجلات المحفوظة وتدعم عمليات التحقق من السلامة. استخدم المراجع المصدرية المصاحبة وسجلات التغطية عند مراجعة أي نتيجة.
