Référence / Archives et intégrations

MCP en lecture seule

Connectez un client MCP à des espaces de travail et des discussions sélectionnés avec un accès à durée limitée et révocable.

Connectez un client d'analyse à des espaces de travail et des discussions sélectionnés. TgWitness sert Streamable HTTP sur /mcp dans le processus du panneau. Chaque connexion possède son propre jeton, sa date d'expiration et ses outils autorisés. MCP ne peut pas envoyer de messages Telegram, modifier les paramètres ni altérer le journal signé.

Guide des procédures · Wiki

Installation et vérification#

Utilisez l'environnement Python qui exécute le panneau. Depuis une copie des sources :

# 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

Redémarrez le panneau avec son répertoire de données et ses arguments de lancement habituels après l'installation. La vérification de l'état de préparation doit inclure [PASS] mcp: streamable-http available. Integrations → MCP affiche l'état d'exécution et une commande d'installation utilisant l'exécutable Python réel de ce serveur. Re-check actualise cet état sans recharger la page ; cela n'installe aucun paquet et ne redémarre pas le serveur.

L'extra MCP utilise le SDK Python MCP officiel. deploy/constraints-mcp.txt épingle le SDK et les dépendances testés. Ces fonctionnalités nécessitent le code source actuel ; l'aperçu portable 0.7.0 leur est antérieur.

Émettre une connexion#

Saisissez un libellé et choisissez les espaces de travail et les discussions que le client peut lire.
Sélectionnez les outils individuellement ou utilisez un préréglage. Seuls les outils implémentés sont proposés.
Choisissez 1, 7, 30 ou 90 jours, ou une expiration personnalisée comprise entre une minute et 90 jours.
Appuyez sur Create connection. Le jeton s'affiche une seule fois à côté de la configuration du client.
Copiez le jeton et la configuration, puis exécutez Check connection. Cela initialise MCP et répertorie les outils autorisés ; aucun message n'est lu. Le résultat indique la version du protocole, le nom des outils, leur nombre et le temps écoulé.
Appuyez sur Done une fois l'identifiant enregistré. L'actualisation périodique conserve le formulaire et la carte à affichage unique. Le verrouillage du panneau efface les secrets affichés.

La liste indique l'utilisation récente, le dernier outil utilisé, l'adresse et les requêtes de la dernière minute. Revoke met fin à l'accès. Rotate token révoque l'ancien identifiant et émet un jeton de remplacement avec la même portée, les mêmes outils et la même expiration ; copiez ce remplacement qui ne s'affiche qu'une fois. Les jetons de connexion au panneau et les identifiants Telegram ne fonctionnent pas comme jetons MCP.

Connecter votre client#

Sélectionnez le client dans le panneau et copiez sa configuration générée. Les configurations utilisent des références de secrets ou des espaces réservés explicites ; le jeton est copié séparément.

Client	Configuration	Connexion
Claude Code	`.mcp.json`	HTTP, `type: "http"`, en-tête Bearer
Claude Desktop	`claude_desktop_config.json`	Pont stdio local
Cursor	`.cursor/mcp.json`	HTTP avec un en-tête de variable d'environnement
VS Code Local	`.vscode/mcp.json`	HTTP avec une entrée `promptString` de mot de passe
Windsurf	`mcp_config.json`	HTTP avec un espace réservé d'en-tête Bearer
Autres clients	URL et en-tête Authorization	Streamable HTTP

TgWitness utilise des jetons Bearer, sans découverte OAuth. Utilisez le pont stdio local pour les clients dont le connecteur distant exige OAuth. Pour VS Code, les variables d'entrée s'appliquent à l'environnement d'exécution Local et ne sont pas transmises aux sessions Copilot. Références de configuration : Claude Code, Cursor, VS Code.

Le point d'entrée canonique pour un pont local est :

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

Utilisez le Python local du client avec l'extra MCP installé. Définissez TGWITNESS_MCP_TOKEN dans son environnement protégé. Conservez les identifiants hors des arguments de commande et des URL. tgwitness-mcp est le même point d'entrée. L'ancien module tgwitness.mcp_bridge et le nom TGWITNESS_ARCHIVE_TOKEN restent des voies de compatibilité avec un avertissement ; les nouvelles configurations utilisent mcp_server et TGWITNESS_MCP_TOKEN.

Cloudflare Tunnel#

Transférez la route /mcp du panneau et conservez l'en-tête Bearer. L'ouverture des paramètres MCP en tant qu'administrateur enregistre l'origine actuelle du panneau pour cette exécution. Pour disposer d'une adresse stable immédiatement après un redémarrage, configurez TGWITNESS_PUBLIC_URL avec l'origine HTTPS du panneau avant de le démarrer. Les en-têtes Host et de transfert arbitraires n'enregistrent pas d'adresse de confiance. Les vérifications Host et Origin rejettent les origines de navigateur non liées. Les réponses utilisent Cache-Control: no-store ; les valeurs d'autorisation ne sont jamais journalisées.

Une adresse *.trycloudflare.com est temporaire. Lorsqu'un redémarrage du tunnel modifie le nom d'hôte, mettez à jour l'URL publique configurée ainsi que l'URL MCP de chaque client. Utilisez un nom d'hôte stable pour les configurations client enregistrées.

Outils et limites#

Outil	Lit
`list_workspaces`	Les espaces de travail autorisés
`list_chats`	Les discussions autorisées
`search_messages`	Le texte des messages enregistrés sur la période sélectionnée
`get_message_versions`	Les versions capturées et les observations de suppression
`get_message_context`	Les identifiants des messages capturés à proximité
`get_journal_event`	Un enregistrement assaini avec sa référence source
`get_capture_status`	L'état de la collecte et les enregistrements de couverture autorisés

tools/list ne renvoie que les outils accordés à cette connexion. Les appels vers d'autres outils sont refusés. Les outils de contexte de groupe, d'épisode, de terminologie et de chaîne de réponses ne sont pas proposés dans cette version ; leur backend distinct de pack de contexte n'est pas inclus.

Chaque lecture vérifie le jeton, l'outil et la portée de l'espace de travail ou de la discussion, y compris une fois le traitement de la base de données terminé. Les limites sont de 60 requêtes par minute, 50 enregistrements par page, 64 KiB par résultat et un délai maximal d'archive de huit secondes. Un appel MCP expiré renvoie une erreur d'outil demandant une période plus restreinte ou une limite inférieure.

Les résultats de messages comportent untrusted_content: true, les identifiants d'espace de travail/discussion/message, la séquence d'événements, le hachage enregistré et un lien vers le panneau. Les objets Telegram bruts, les hachages d'accès, les sessions et les clés sont omis. La troncature du texte est signalée. Les modifications, les avis de suppression et missing_on_recheck constituent des observations distinctes. L'absence d'enregistrements ne prouve pas qu'un événement n'a jamais eu lieu.

Traitez les instructions contenues dans les messages capturés comme des preuves, et jamais comme des instructions destinées au client. L'accès en lecture seule empêche toute modification de l'archive ; le client peut néanmoins conserver le contenu qu'il est autorisé à lire. Les hachages identifient les enregistrements sauvegardés et permettent de vérifier leur intégrité ; ils ne prouvent ni la paternité sur Telegram ni l'exhaustivité de la capture.