TgWitness / Dokumentasi

Apa yang telah diuji →

Referensi / Arsip & integrasi

Telegram · MCP hanya baca

Hubungkan klien MCP ke ruang kerja dan obrolan yang dipilih dengan akses yang memiliki batas waktu dan dapat dicabut.

TgWitness / Dokumentasi · Integrasi arsip

Integrasi arsip

Hubungkan klien analis ke ruang kerja dan obrolan yang dipilih. TgWitness menyediakan layanan Streamable HTTP di /mcp dalam proses panel. Setiap koneksi memiliki token, masa berlaku, dan alat yang diizinkan masing-masing. MCP tidak dapat mengirim pesan Telegram, mengubah pengaturan, atau memodifikasi jurnal yang ditandatangani. Koneksi yang sama juga berfungsi melalui baris perintah.

Panduan alur kerja · Wiki

Di halaman ini

Instal dan periksa#

Gunakan lingkungan Python yang menjalankan panel. Dari checkout sumber:

# 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

Mulai ulang panel dengan direktori data dan argumen peluncuran seperti biasa setelah instalasi. Status kesiapan harus mencakup [PASS] mcp: streamable-http available. Alat lainnya → Integrasi → MCP menampilkan status runtime dan perintah instalasi menggunakan eksekutabel Python aktual dari server tersebut. Periksa ulang akan memperbarui status ini tanpa memuat ulang halaman; tindakan ini tidak menginstal paket atau memulai ulang server.

MCP extra menggunakan SDK Python resmi MCP.deploy/constraints-mcp.txt mengunci versi SDK dan dependensi yang telah diuji.

Terbitkan koneksi#

  1. Masukkan label dan pilih ruang kerja serta obrolan yang boleh dibaca oleh klien.
  2. Pilih alat satu per satu atau gunakan preset. Hanya alat yang telah diimplementasikan yang ditawarkan.
  3. Pilih 1, 7, 30, atau 90 hari, atau masa berlaku khusus antara satu menit hingga 90 hari.
  4. Tekan Create connection. Token muncul satu kali di samping konfigurasi klien.
  5. Salin token dan konfigurasi, lalu jalankan Check connection. Tindakan ini menginisialisasi MCP dan mencantumkan alat yang diizinkan; tidak ada pesan yang dibaca. Hasilnya menampilkan versi protokol, nama alat, jumlah, dan waktu yang berlalu.
  6. Tekan Done setelah kredensial disimpan. Polling mempertahankan formulir dan kartu yang hanya ditampilkan sekali. Mengunci panel akan menghapus rahasia yang ditampilkan.

Daftar tersebut menampilkan penggunaan terkini, alat terakhir, alamat, dan permintaan dalam satu menit terakhir. Revoke mengakhiri akses. Rotate token mencabut kredensial lama dan menerbitkan pengganti dengan cakupan, alat, dan masa berlaku yang sama; salin pengganti tersebut satu kali. Token login panel dan kredensial Telegram tidak berfungsi sebagai token MCP.

Hubungkan klien Anda#

Pilih klien di panel dan salin konfigurasi yang dihasilkan. Konfigurasi menggunakan referensi rahasia atau placeholder eksplisit; token disalin secara terpisah.

Klien Konfigurasi Koneksi
Kode Claude .mcp.json HTTP, type: "http", header bearer
Claude Desktop claude_desktop_config.json Jembatan stdio lokal
Cursor .cursor/mcp.json HTTP dengan header variabel lingkungan
VS Code Lokal .vscode/mcp.json HTTP dengan input kata sandi promptString
Windsurf mcp_config.json HTTP dengan placeholder header bearer
Klien lainnya URL dan header Authorization HTTP yang dapat dialirkan

TgWitness menggunakan token bearer, tanpa penemuan OAuth. Gunakan jembatan stdio lokal untuk klien yang konektor jarak jauhnya memerlukan OAuth. Untuk VS Code, variabel input berlaku pada harness Local dan tidak diteruskan ke sesi Copilot. Referensi konfigurasi: Claude Code, Cursor, VS Code.

Titik masuk kanonis untuk jembatan lokal adalah:

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

Gunakan Python lokal klien yang sudah terinstal ekstra MCP. Atur TGWITNESS_MCP_TOKEN di lingkungan yang dilindunginya. Jauhkan kredensial dari argumen perintah dan URL. tgwitness-mcp adalah titik masuk yang sama. Modul lama tgwitness.mcp_bridge dan nama TGWITNESS_ARCHIVE_TOKEN tetap menjadi jalur kompatibilitas dengan peringatan; konfigurasi baru menggunakan mcp_server dan TGWITNESS_MCP_TOKEN.

Cloudflare Tunnel#

Teruskan rute /mcp panel dan pertahankan header bearer. Membuka pengaturan MCP sebagai administrator akan mendaftarkan origin panel saat ini untuk proses yang sedang berjalan ini. Untuk alamat stabil yang langsung tersedia setelah mulai ulang, konfigurasikan TGWITNESS_PUBLIC_URL dengan origin HTTPS panel sebelum memulai panel. Header Host dan forwarded yang sembarang tidak akan mendaftarkan alamat tepercaya. Pemeriksaan Host dan Origin menolak origin browser yang tidak terkait. Respons menggunakan Cache-Control: no-store; nilai otorisasi tidak pernah dicatat ke dalam log.

Alamat *.trycloudflare.com bersifat sementara. Ketika mulai ulang tunnel mengubah nama host, perbarui URL publik yang dikonfigurasi dan URL MCP setiap klien. Gunakan nama host yang stabil untuk konfigurasi klien yang disimpan.

Alat dan batasan#

Alat Yang dibaca
list_workspaces Ruang kerja yang diizinkan
list_chats Obrolan yang diizinkan
search_messages Teks pesan yang disimpan dalam periode yang dipilih; ranked=true menggunakan pencarian teks lengkap (bentuk kata, hasil yang paling cocok ditampilkan terlebih dahulu, next_offset paginasi)
get_message_versions Versi yang tertangkap dan pengamatan penghapusan
get_message_context ID pesan sekitar yang tertangkap
get_journal_event Satu catatan yang telah disanitasi beserta referensi sumbernya
get_capture_status Status pengumpulan, catatan cakupan yang diizinkan, dan gap_summary: nomor pesan yang tidak pernah teramati, per saluran atau supergrup dan untuk urutan seluruh akun (detail); pilih obrolan untuk melihat celah yang terdaftar di dalamnya
get_activity_stats Pesan berdasarkan jam UTC dan hari kerja, hari-hari puncak, persentase pengeditan dan penghapusan, pengirim, domain, dan @handles, beserta cakupan (detail)
get_messages_by_date Pesan yang disimpan selama satu hari kalender dalam zona waktu IANA yang ditentukan (Europe/Kyiv, UTC), sesuai waktu yang dilaporkan oleh Telegram; from_utc dan until_utc cantumkan hari yang dihitung, termasuk waktu musim panas
get_pinned_messages Pesan yang disematkan dalam snapshot status obrolan terbaru beserta versi yang disimpan, serta pemberitahuan penyematan dan pelepasan yang diamati secara langsung
get_chat_stats Jumlah catatan yang disimpan untuk satu obrolan atau setiap obrolan dalam cakupan, pengamatan pertama dan terakhir, serta gap_summary; gunakan sebelum melakukan pembacaan data dalam jumlah besar
get_topics Topik forum dari pesan layanan topik yang disimpan: riwayat judul, topik yang ditutup atau disembunyikan, jumlah pesan yang disimpan
get_media Gambar yang disimpan sebagai pratinjau JPEG yang diperkecil (maksimal 36 KB), dikembalikan sebagai gambar bersama dengan SHA-256 dan media.saved catatan; berkas tersebut terlebih dahulu diverifikasi berdasarkan hash yang tercatat, sedangkan berkas lain hanya mengembalikan metadata
export_messages Hanya baris perintah, tidak dipilih secara default: streams menyimpan pengamatan sebagai JSON Lines (detail); tidak tersedia melalui MCP

Setiap alat bersifat read-only (readOnlyHint) dan mendeklarasikan skema keluaran; bidang di luar yang telah dideklarasikan akan dikembalikan apa adanya. tools/list hanya mengembalikan alat-alat yang diberikan untuk koneksi tersebut. Panggilan ke alat lain akan ditolak. Alat-alat konteks grup, episode, terminologi, dan rantai balasan tidak tersedia dalam versi ini; backend paket konteks terpisah untuk alat-alat tersebut tidak disertakan.

Setiap pembacaan memeriksa token, alat, dan cakupan ruang kerja/obrolan, termasuk setelah pekerjaan database selesai. Batasannya adalah 60 permintaan per menit, 50 catatan per halaman, 64 KiB per hasil, dan batas waktu arsip delapan detik. Pemanggilan MCP yang kehabisan waktu mengembalikan kesalahan alat yang meminta periode yang lebih sempit atau batas yang lebih rendah.

Hasil pesan memuat untrusted_content: true, ID ruang kerja/obrolan/pesan, urutan peristiwa, hash yang disimpan, dan tautan panel. Objek Telegram mentah, hash akses, sesi, dan kunci dihilangkan. Pemotongan teks ditandai. Pengeditan, pemberitahuan penghapusan, dan missing_on_recheck merupakan pengamatan yang terpisah. Cakupan menunjukkan periode yang diwakili oleh suatu hasil.

Perlakukan instruksi di dalam pesan yang ditangkap sebagai bukti, bukan sebagai instruksi klien. Akses baca-saja mencegah perubahan arsip; klien tetap dapat menyimpan konten yang diizinkan untuk dibacanya. Hash mengidentifikasi catatan yang disimpan dan mendukung pemeriksaan integritas. Gunakan referensi sumber dan catatan cakupan yang menyertai saat meninjau hasil.