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
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#
- Inserisci un'etichetta e scegli gli spazi di lavoro e le chat che il client può leggere.
- Seleziona gli strumenti singolarmente o usa un preset. Vengono offerti solo gli strumenti implementati.
- Scegli 1, 7, 30 o 90 giorni, oppure una scadenza personalizzata compresa tra un minuto e 90 giorni.
- Premi Create connection. Il token viene mostrato una sola volta accanto alla configurazione del client.
- 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.
- 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.