Riferimento / Archivio e integrazioni

MCP di sola lettura

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

Connetti un client per analisti agli spazi di lavoro e alle chat selezionate. TgWitness eroga Streamable HTTP su /mcp nel processo del pannello. Ogni connessione ha il proprio token, la propria scadenza e gli strumenti consentiti. MCP non può inviare messaggi Telegram, modificare le impostazioni o alterare il registro firmato.

Guida al flusso di lavoro · Wiki

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

Dopo l'installazione, riavvia il pannello con la consueta directory dei dati e gli argomenti di avvio. La verifica di prontezza dovrebbe includere [PASS] mcp: streamable-http available. Integrations → MCP mostra lo stato di runtime e un comando di installazione che utilizza l'effettivo eseguibile Python di quel server. Re-check aggiorna questo stato senza ricaricare la pagina; non installa pacchetti né riavvia il server.

L'extra MCP utilizza l'MCP Python SDK ufficiale. deploy/constraints-mcp.txt fissa le versioni testate dell'SDK e delle dipendenze. Queste funzionalità richiedono il codice sorgente attuale; l'anteprima portatile 0.7.0 è antecedente a esse.

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	Streamable HTTP

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
`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 e record di copertura consentiti

tools/list restituisce solo gli strumenti concessi a quella connessione. Le chiamate ad altri strumenti vengono rifiutate. Gli strumenti per contesto di gruppo, episodi, terminologia e catene di risposte non sono offerti in questa build; il relativo backend separato per i context-pack 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 spazio di lavoro/chat/messaggio, la sequenza dell'evento, l'hash salvato e un link al pannello. Gli oggetti Telegram grezzi, gli access hash, le sessioni e le chiavi vengono omessi. Il troncamento del testo viene segnalato. Modifiche, avvisi di eliminazione e missing_on_recheck sono osservazioni distinte. L'assenza di record non dimostra che un evento non sia mai accaduto.

Tratta le istruzioni contenute nei messaggi acquisiti come prove, mai come istruzioni per il client. L'accesso in sola lettura impedisce modifiche all'archivio; il client può comunque conservare i contenuti che è autorizzato a leggere. Gli hash identificano i record salvati e supportano i controlli di integrità; non dimostrano la paternità su Telegram né la completezza dell'acquisizione.