مرجع / الأرشيف والتكاملات

MCP للقراءة فقط

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

اربط عميل محلل بمساحات عمل ومحادثات محددة. يُقدّم TgWitness Streamable HTTP عند المسار /mcp ضمن عملية لوحة التحكم. لكل اتصال رمزه الخاص وتاريخ انتهاء صلاحيته والأدوات المسموح بها. لا يستطيع MCP إرسال رسائل تيليجرام أو تغيير الإعدادات أو تعديل السجل الموقَّع.

دليل سير العمل · ويكي

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

استخدم بيئة 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. يعرض المسار Integrations → MCP حالة وقت التشغيل وأمر تثبيت يستخدم ملف Python التنفيذي الفعلي لذلك الخادم. يُحدِّث الزر Re-check هذه الحالة دون إعادة تحميل الصفحة؛ وهو لا يُثبِّت الحزم ولا يُعيد تشغيل الخادم.

تستخدم الإضافة الخاصة بـ MCP حزمة MCP Python SDK الرسمية. يُثبِّت الملف deploy/constraints-mcp.txt إصدارات SDK والتبعيات التي تم اختبارها. تتطلب هذه الميزات الكود المصدري الحالي؛ إذ إن النسخة التجريبية المحمولة 0.7.0 قد صدرت قبلها.

إصدار اتصال#

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

تعرض القائمة الاستخدام الأخير وآخر أداة استُخدمت والعنوان والطلبات خلال الدقيقة الأخيرة. يُنهي الزر 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. استخدم جسر stdio المحلي للعملاء الذين يتطلب موصلهم البعيد استخدام OAuth. بالنسبة لـ VS Code، تنطبق متغيرات الإدخال على بيئة التشغيل Local ولا تتم إعادة توجيهها إلى جلسات Copilot. مراجع الإعدادات: Claude Code، Cursor، VS Code.

نقطة الدخول المعتمدة لجسر محلي هي:

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`	نص الرسائل المحفوظة ضمن الفترة المحددة
`get_message_versions`	الإصدارات الملتقطة وملاحظات الحذف
`get_message_context`	مُعرِّفات الرسائل الملتقطة المجاورة
`get_journal_event`	سجل واحد مُنقّى مع مرجع مصدره
`get_capture_status`	حالة الجمع وسجلات التغطية المسموح بها

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

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

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

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