Referans / Arşiv ve entegrasyonlar

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.

Bir analist istemcisini seçili çalışma alanlarına ve sohbetlere bağlayın. TgWitness, panel sürecinde /mcp adresinde Streamable HTTP sunar. Her bağlantının kendi belirteci (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üğü (journal) düzenleyemez.

İş akışı kılavuzu · Wiki

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 olağan veri dizini ve başlatma argümanlarıyla yeniden başlatın. Hazırlık kontrolü [PASS] mcp: streamable-http available çıktısını içermelidir. Integrations → MCP, çalışma zamanı durumunu ve sunucunun asıl Python yürütülebilir dosyasını kullanan bir kurulum komutunu gösterir. Re-check, sayfayı yeniden yüklemeden bu durumu yeniler; paket kurmaz veya sunucuyu yeniden başlatmaz.

MCP ekstrası, resmi MCP Python SDK paketini kullanır. deploy/constraints-mcp.txt, test edilmiş SDK ve bağımlılık sürümlerini sabitler. Bu özellikler güncel kaynak kodu gerektirir; 0.7.0 taşınabilir önizleme sürümü bunlardan daha eskidir.

Bağlantı oluşturma#

Bir etiket girin ve istemcinin okuyabileceği çalışma alanlarını ve sohbetleri seçin.
Araçları tek tek seçin veya bir ön ayar kullanın. Yalnızca uygulanmış araçlar sunulur.
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.
Create connection düğmesine basın. Belirteç, istemci yapılandırmasının yanında bir kez görüntülenir.
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.
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 Code	`.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	Streamable 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 Tunnel#

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 metni
`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 ve izin verilen kapsam kayıtları

tools/list yalnızca ilgili bağlantıya izin verilen araçları döndürür. Diğer araçlara yapılan çağrılar reddedilir. Grup bağlamı, bölüm (episode), terminoloji ve yanıt zinciri araçları bu derlemede 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, çalışma alanı/sohbet/mesaj kimliklerini, olay sırasını, kaydedilen karmayı (hash) ve bir panel bağlantısını taşır. Ham Telegram nesneleri, erişim karmaları, oturumlar ve anahtarlar çıkarılır. Metin kısaltmaları işaretlenir. Düzenlemeler, silme bildirimleri ve missing_on_recheck birbirinden ayrı gözlemlerdir. Eksik kayıtlar bir olayın asla gerçekleşmediğini kanıtlamaz.

Yakalanan mesajların içindeki talimatları her zaman kanıt olarak değerlendirin, asla istemci talimatı olarak ele almayın. Salt okunur erişim arşivde değişiklik yapılmasını önler; ancak istemci okumasına izin verilen içeriği yine de saklayabilir. Karmalar (hash'ler) kaydedilen kayıtları tanımlar ve bütünlük kontrollerini destekler; Telegram yazarlığını veya eksiksiz yakalamayı kanıtlamaz.