TgWitness / Documentazione

Cosa è stato testato →

Riferimento / Archivio e integrazioni

Telegram · MCP di sola lettura

Collega un client MCP agli spazi di lavoro e alle chat selezionati con un accesso a scadenza e revocabile.

TgWitness / Documentazione · Integrazioni con gli archivi

Integrazioni con gli archivi

Collegare un client di analisi a spazi di lavoro e chat selezionati. TgWitness fornisce un servizio HTTP Streamable all'indirizzo /mcp nel processo del pannello. Ogni connessione dispone di un proprio token, una scadenza e strumenti consentiti. MCP non può inviare messaggi Telegram, modificare le impostazioni né alterare il registro firmato. Le stesse connessioni funzionano anche dalla riga di comando.

Guida al flusso di lavoro · Wiki

In questa pagina

Installa e verifica#

Usa l'ambiente Python che esegue il pannello. Da un checkout dei sorgenti:

# 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

Riavviare il pannello con la sua consueta directory dei dati e gli argomenti di avvio dopo l’ installazione. Lo stato di prontezza dovrebbe includere [PASS] mcp: streamable-http available. Strumenti → Integrazioni → MCP mostra lo stato di esecuzione e un comando di installazione che utilizza l’eseguibile Python effettivo di quel server. La funzione Ricontrolla aggiorna questo stato senza ricaricare la pagina; non installa pacchetti né riavvia il server.

L'extra MCP utilizza l'SDK Python ufficiale di MCP.deploy/constraints-mcp.txt specifica la versione dell'SDK testato e delle dipendenze.

Emetti una connessione#

  1. Inserisci un'etichetta e scegli gli spazi di lavoro e le chat che il client può leggere.
  2. Seleziona gli strumenti singolarmente o usa un preset. Vengono offerti solo gli strumenti implementati.
  3. Scegli 1, 7, 30 o 90 giorni, oppure una scadenza personalizzata compresa tra un minuto e 90 giorni.
  4. Premi Create connection. Il token viene mostrato una sola volta accanto alla configurazione del client.
  5. Copia il token e la configurazione, quindi esegui Check connection. Questo inizializza MCP ed elenca gli strumenti consentiti; non viene letto alcun messaggio. Il risultato mostra la versione del protocollo, i nomi degli strumenti, il conteggio e il tempo trascorso.
  6. Premi Done una volta salvata la credenziale. Il polling preserva il modulo e la scheda mostrata una sola volta. Il blocco del pannello cancella i segreti visualizzati.

L'elenco mostra l'utilizzo recente, l'ultimo strumento, l'indirizzo e le richieste nell'ultimo minuto. Revoke interrompe l'accesso. Rotate token revoca la vecchia credenziale e ne emette una sostitutiva con lo stesso ambito, gli stessi strumenti e la stessa scadenza; copia il token sostitutivo quando viene mostrato. I token di accesso al pannello e le credenziali di Telegram non funzionano come token MCP.

Connetti il tuo client#

Seleziona il client nel pannello e copia la configurazione generata. Le configurazioni utilizzano riferimenti a segreti o segnaposto espliciti; il token viene copiato separatamente.

Client Configurazione Collegamento
Claude Code .mcp.json HTTP, type: "http", header bearer
Claude Desktop claude_desktop_config.json Bridge stdio locale
Cursor .cursor/mcp.json HTTP con header tramite variabile d'ambiente
VS Code Local .vscode/mcp.json HTTP con un input password promptString
Windsurf mcp_config.json HTTP con segnaposto per l'header bearer
Altri client URL e header Authorization HTTP streamabile

TgWitness utilizza token bearer, senza rilevamento OAuth. Usa il bridge stdio locale per i client il cui connettore remoto richiede OAuth. Per VS Code, le variabili di input si applicano all'ambiente Local e non vengono inoltrate alle sessioni di Copilot. Riferimenti per la configurazione: Claude Code, Cursor, VS Code.

Il punto di ingresso canonico per un bridge locale è:

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

Usa il Python locale del client con l'extra MCP installato. Imposta TGWITNESS_MCP_TOKEN nel suo ambiente protetto. Mantieni le credenziali fuori dagli argomenti dei comandi e dagli URL. tgwitness-mcp è lo stesso punto di ingresso. Il vecchio modulo tgwitness.mcp_bridge e il nome TGWITNESS_ARCHIVE_TOKEN rimangono percorsi di compatibilità che generano un avviso; le nuove configurazioni usano mcp_server e TGWITNESS_MCP_TOKEN.

Cloudflare Tunnel#

Inoltra la rotta /mcp del pannello e preserva l'header bearer. L'apertura delle impostazioni MCP come amministratore registra l'origine corrente del pannello per l'esecuzione in corso. Per avere un indirizzo stabile immediatamente disponibile dopo il riavvio, configura TGWITNESS_PUBLIC_URL con l'origine HTTPS del pannello prima di avviarlo. Header Host e di inoltro arbitrari non registrano un indirizzo attendibile. I controlli su Host e Origin rifiutano origini del browser non correlate. Le risposte usano Cache-Control: no-store; i valori di autorizzazione non vengono mai registrati nei log.

Un indirizzo *.trycloudflare.com è temporaneo. Quando il riavvio di un tunnel modifica l'hostname, aggiorna l'URL pubblico configurato e l'URL MCP di ciascun client. Usa un hostname stabile per le configurazioni salvate dei client.

Strumenti e limiti#

Strumento Cosa legge
list_workspaces Spazi di lavoro autorizzati
list_chats Chat autorizzate
search_messages Testo dei messaggi salvati nel periodo selezionato; ranked=true utilizza la ricerca full-text (forme delle parole, risultati più pertinenti per primi, next_offset impaginazione)
get_message_versions Versioni acquisite e osservazioni di eliminazione
get_message_context ID dei messaggi acquisiti circostanti
get_journal_event Un record sanificato con il relativo riferimento alla fonte
get_capture_status Stato della raccolta, record di copertura consentiti e gap_summary: numeri di messaggi mai osservati, per canale o supergruppo e per la sequenza a livello di account (dettagli); scegli una chat per visualizzarne le lacune elencate
get_activity_stats Messaggi per ora UTC e giorno della settimana, giorni di picco, percentuali di modifiche e cancellazioni, mittenti, domini e @handles, con copertura (dettagli)
get_messages_by_date Messaggi salvati relativi a un giorno di calendario in un fuso orario IANA specificato (Europe/Kyiv, UTC), in base all’ora riportata da Telegram; from_utc e until_utc indicare il giorno calcolato, ora legale inclusa
get_pinned_messages Messaggi fissati nell’ultima istantanea dello stato della chat con le relative versioni salvate, nonché le notifiche di fissaggio e sblocco osservate in tempo reale
get_chat_stats Conteggio approssimativo dei record salvati per una singola chat o per tutte le chat nell’ambito di analisi, prima e ultima osservazione, e gap_summary; utilizzarlo prima di una lettura di grandi dimensioni
get_topics Argomenti del forum dai messaggi del servizio argomenti salvati: cronologia dei titoli, argomenti chiusi o nascosti, numero di messaggi salvati
get_media Un'immagine conservata come anteprima JPEG ridimensionata (al massimo 36 KB), restituita come immagine insieme al suo SHA-256 e al media.saved record; il file viene prima verificato rispetto al proprio hash registrato, mentre gli altri file restituiscono solo i metadati
export_messages Solo da riga di comando, non selezionato per impostazione predefinita: salva le osservazioni in formato JSON Lines (dettagli); non disponibile tramite MCP

Ogni strumento è di sola lettura (readOnlyHint) e dichiara uno schema di output; i campi che non rientrano in quello dichiarato vengono restituiti così come sono. tools/list Restituisce solo gli strumenti concessi a quella connessione. Le chiamate ad altri strumenti vengono rifiutate. Gli strumenti relativi al contesto di gruppo, all’episodio, alla terminologia e alla catena di risposte non sono disponibili in questa build; il relativo backend separato per i pacchetti di contesto non è incluso.

Ogni lettura verifica il token, lo strumento e l'ambito di spazio di lavoro/chat, anche al termine dell'operazione sul database. I limiti sono di 60 richieste al minuto, 50 record per pagina, 64 KiB per risultato e una scadenza di otto secondi per l'archivio. Una chiamata MCP scaduta restituisce un errore dello strumento richiedendo un periodo più ristretto o un limite inferiore.

I risultati dei messaggi riportano untrusted_content: true, gli ID di workspace/chat/messaggio, la sequenza degli eventi, l’hash salvato e un link al pannello. Gli oggetti Telegram grezzi, gli hash di accesso, le sessioni e le chiavi vengono omessi. Il troncamento del testo è contrassegnato. Modifiche, avvisi di cancellazione e missing_on_recheck sono osservazioni distinte. La copertura indica i periodi a cui si riferisce un risultato.

Considerare le istruzioni contenute nei messaggi acquisiti come prove, mai come istruzioni del client. L’accesso in sola lettura impedisce modifiche all’archivio; il client può comunque conservare il contenuto che è autorizzato a leggere. Gli hash identificano i record salvati e supportano i controlli di integrità. Utilizzare i riferimenti alle fonti e i record di copertura allegati durante la revisione di un risultato.