TgWitness / Belgeler

Neler test edildi →

Referans / Arşiv ve entegrasyonlar

Telegram · Salt okunur MCP

Bir MCP istemcisini, süresi dolan ve iptal edilebilir erişim izniyle seçilen çalışma alanlarına ve sohbetlere bağlayın.

TgWitness / Belgeler · Arşiv entegrasyonları

Arşiv entegrasyonları

Bir analist istemcisini seçilen çalışma alanlarına ve sohbetlere bağlayın. TgWitness, panel sürecinde /mcp adresinde Streamable HTTP hizmeti sunar. Her bağlantının kendine ait bir token'ı, geçerlilik süresi ve izin verilen araçları vardır. MCP, Telegram mesajları gönderemez, ayarları değiştiremez veya imzalı günlüğü düzenleyemez. Aynı bağlantılar komut satırı ile de çalışır.

İş akışı kılavuzu · Wiki

Bu sayfada

Kurulum ve kontrol#

Paneli çalıştıran Python ortamını kullanın. Kaynak kod dizininden:

# 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

Kurulumdan sonra paneli normal veri dizini ve başlatma argümanlarıyla yeniden başlatın. Hazırlık durumu [PASS] mcp: streamable-http available ifadesini içermelidir. Diğer araçlar → Entegrasyonlar → MCP, çalışma zamanı durumunu ve söz konusu sunucunun gerçek Python yürütülebilir dosyasını kullanan bir kurulum komutunu gösterir. Yeniden Kontrol seçeneği, sayfayı yeniden yüklemeden bu durumu günceller; paketleri yüklemez veya sunucuyu yeniden başlatmaz.

MCP eklentisi, resmi MCP Python SDK'sını kullanır.deploy/constraints-mcp.txt, test edilmiş SDK'yı ve bağımlılıkları sabitler.

Bağlantı oluşturma#

  1. Bir etiket girin ve istemcinin okuyabileceği çalışma alanlarını ve sohbetleri seçin.
  2. Araçları tek tek seçin veya bir ön ayar kullanın. Yalnızca uygulanmış araçlar sunulur.
  3. 1, 7, 30 veya 90 günü ya da bir dakika ile 90 gün arasında özel bir geçerlilik süresi seçin.
  4. Create connection düğmesine basın. Belirteç, istemci yapılandırmasının yanında bir kez görüntülenir.
  5. Belirteci ve yapılandırmayı kopyalayın, ardından Check connection işlemini çalıştırın. Bu işlem MCP'yi başlatır ve izin verilen araçları listeler; hiçbir mesaj okunmaz. Sonuçta protokol sürümü, araç adları, araç sayısı ve geçen süre gösterilir.
  6. Kimlik bilgisi kaydedildiğinde Done düğmesine basın. Yoklama (polling), formu ve bir kez gösterilen kartı korur. Panelin kilitlenmesi görüntülenen gizli bilgileri temizler.

Liste; son kullanımı, son aracı, adresi ve son dakikadaki istekleri gösterir. Revoke erişimi sonlandırır. Rotate token eski kimlik bilgisini iptal eder ve aynı kapsam, araçlar ve geçerlilik süresiyle yeni bir belirteç oluşturur; yeni belirteci bir kez kopyalayın. Panel oturum açma belirteçleri ve Telegram kimlik bilgileri MCP belirteci olarak çalışmaz.

İstemcinizi bağlama#

Panelde istemciyi seçin ve oluşturulan yapılandırmayı kopyalayın. Yapılandırmalar gizli bilgi referansları veya açık yer tutucular kullanır; belirteç ayrı olarak kopyalanır.

İstemci Yapılandırma Bağlantı
Claude Kodu .mcp.json HTTP, type: "http", bearer üstbilgisi
Claude Desktop claude_desktop_config.json Yerel stdio köprüsü
Cursor .cursor/mcp.json Ortam değişkeni üstbilgili HTTP
VS Code Local .vscode/mcp.json Parola promptString girdili HTTP
Windsurf mcp_config.json Bearer üstbilgisi yer tutuculu HTTP
Diğer istemciler URL ve Authorization üstbilgisi Akışlanabilir HTTP

TgWitness, OAuth keşfi olmadan bearer belirteçleri kullanır. Uzak bağlayıcısı OAuth gerektiren istemciler için yerel stdio köprüsünü kullanın. VS Code için girdi değişkenleri Local çalışma ortamına uygulanır ve Copilot oturumlarına iletilmez. Yapılandırma referansları: Claude Code, Cursor, VS Code.

Yerel bir köprü için standart giriş noktası şudur:

python -m tgwitness.mcp_server --url https://your-panel.example/mcp

İstemcinin MCP ekstrası kurulmuş yerel Python ortamını kullanın. Korumalı ortamında TGWITNESS_MCP_TOKEN değişkenini ayarlayın. Kimlik bilgilerini komut argümanlarından ve URL'lerden uzak tutun. tgwitness-mcp aynı giriş noktasıdır. Eski tgwitness.mcp_bridge modülü ve TGWITNESS_ARCHIVE_TOKEN adı bir uyarıyla birlikte uyumluluk yolu olarak kalmaya devam eder; yeni yapılandırmalar mcp_server ve TGWITNESS_MCP_TOKEN kullanır.

Cloudflare Tüneli#

Panelin /mcp rotasını yönlendirin ve bearer üstbilgisini koruyun. MCP ayarlarını yönetici olarak açmak, bu çalışma için panelin mevcut kaynağını (origin) kaydeder. Yeniden başlatmanın hemen ardından kullanılabilecek sabit bir adres için paneli başlatmadan önce TGWITNESS_PUBLIC_URL değişkenini panelin HTTPS kaynağıyla yapılandırın. Rastgele Host ve yönlendirilmiş (forwarded) üstbilgiler güvenilir bir adres kaydetmez. Host ve Origin kontrolleri ilgisiz tarayıcı kaynaklarını reddeder. Yanıtlar Cache-Control: no-store kullanır; yetkilendirme değerleri asla günlüğe kaydedilmez.

Bir *.trycloudflare.com adresi geçicidir. Bir tünel yeniden başlatması ana bilgisayar adını (hostname) değiştirdiğinde, yapılandırılmış genel URL'yi ve her istemcinin MCP URL'sini güncelleyin. Kayıtlı istemci yapılandırmaları için sabit bir ana bilgisayar adı kullanın.

Araçlar ve sınırlar#

Araç Okunan veriler
list_workspaces İzin verilen çalışma alanları
list_chats İzin verilen sohbetler
search_messages Seçilen dönem içindeki kaydedilmiş mesaj metinleri; ranked=true tam metin araması kullanır (kelime biçimleri, en iyi eşleşmeler önce, next_offset sayfalama)
get_message_versions Yakalanan sürümler ve silme gözlemleri
get_message_context Yakındaki yakalanmış mesaj kimlikleri (ID'leri)
get_journal_event Kaynak referansıyla birlikte temizlenmiş (sanitized) tek bir kayıt
get_capture_status Toplama durumu, izin verilen kapsama kayıtları ve gap_summary: kanal veya süper grup bazında ve hesap genelindeki sıra numarası için (ayrıntılar) hiç gözlemlenmemiş mesaj numaraları; listelenen boşlukları görmek için bir sohbet seçin
get_activity_stats UTC saatine ve hafta gününe göre mesajlar, en yoğun günler, düzenleme ve silme oranları, gönderenler, etki alanları ve @handles, kapsama alanı (ayrıntılar) ile birlikte
get_messages_by_date Telegram'ın raporlama yaptığı zamana kadar, belirli bir IANA saat diliminde (Europe/Kyiv, UTC), Telegram'ın bildirdiği zamana göre; from_utc ve until_utc hesaplanan günü, yaz saati uygulaması dahil olmak üzere belirtin
get_pinned_messages En son sohbet durumu anlık görüntüsünde sabitlenmiş mesajlar ile bunların kaydedilmiş sürümleri ve canlı olarak gözlemlenen sabitleme ve sabitlemeyi kaldırma bildirimleri
get_chat_stats Kapsamdaki bir sohbet veya tüm sohbetler için kaydedilen kayıtların sayısını, ilk ve son gözlemi ve gap_summary; büyük bir okuma işleminden önce kullanın
get_topics Kaydedilmiş konu hizmeti mesajlarından alınan forum konuları: başlık geçmişi, kapatılmış veya gizlenmiş konular, kaydedilmiş mesaj sayısı
get_media Küçültülmüş bir JPEG önizlemesi olarak saklanan bir görüntü (en fazla 36 KB), SHA-256 değeri ve media.saved kayıtla birlikte bir resim olarak döndürülür; dosya öncelikle kaydedilmiş hash değeriyle karşılaştırılır, diğer dosyalar ise yalnızca meta verileri döndürür
export_messages Yalnızca komut satırı, varsayılan olarak seçili değildir: gözlemleri JSON Lines biçimi olarak akışa kaydeder (ayrıntılar); MCP üzerinden sunulmaz

Her araç salt okunurdur (readOnlyHint) ve bir çıktı şeması bildirir; bildirilenlerin dışındaki alanlar olduğu gibi döndürülür. tools/list Yalnızca o bağlantıya izin verilen araçları döndürür. Diğer araçlara yapılan çağrılar reddedilir. Grup bağlamı, olay, terminoloji ve yanıt zinciri araçları bu sürümde sunulmamaktadır; bunların ayrı bağlam paketi arka ucu dahil edilmemiştir.

Her okuma işlemi, veritabanı çalışması bittikten sonrası da dahil olmak üzere belirteci, aracı ve çalışma alanı/sohbet kapsamını kontrol eder. Sınırlar dakikada 60 istek, sayfa başına 50 kayıt, sonuç başına 64 KiB ve sekiz saniyelik arşiv zaman sınırıdır. Zaman aşımına uğrayan bir MCP çağrısı, daha dar bir dönem veya daha düşük bir sınır isteyen bir araç hatası döndürür.

Mesaj sonuçları untrusted_content: true değerini, çalışma alanı/sohbet/mesaj kimliklerini, olay dizisini, kaydedilmiş hash değerini ve bir panel bağlantısını içerir. Ham Telegram nesneleri, erişim hash'leri, oturumlar ve anahtarlar hariç tutulur. Metin kesintileri işaretlenir. Düzenlemeler, silme bildirimleri ve missing_on_recheck ayrı gözlemlerdir. Kapsam, bir sonucun hangi dönemleri temsil ettiğini gösterir.

Yakalanan mesajlardaki talimatları kanıt olarak değerlendirin, asla istemci talimatları olarak değerlendirmeyin. Salt okunur erişim, arşivde değişiklik yapılmasını engeller; istemci yine de okumaya izin verilen içeriği saklayabilir. Hash değerleri, kaydedilen kayıtları tanımlar ve bütünlük kontrollerini destekler. Bir sonucu incelerken, beraberindeki kaynak referanslarını ve kapsam kayıtlarını kullanın.