Referencia / Archivo e integraciones

MCP de solo lectura

Conecta un cliente MCP a espacios de trabajo y chats seleccionados con acceso temporal y revocable.

Conecte un cliente de análisis a los espacios de trabajo y chats seleccionados. TgWitness sirve Streamable HTTP en /mcp en el proceso del panel. Cada conexión tiene su propio token, vencimiento y herramientas permitidas. MCP no puede enviar mensajes de Telegram, cambiar la configuración ni modificar el diario firmado.

Guía de flujo de trabajo · Wiki

Instalar y comprobar#

Use el entorno de Python que ejecuta el panel. Desde una descarga del código fuente:

# 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

Reinicie el panel con su directorio de datos habitual y sus argumentos de inicio después de la instalación. La comprobación de disponibilidad debe incluir [PASS] mcp: streamable-http available. Integrations → MCP muestra el estado del entorno de ejecución y un comando de instalación que utiliza el ejecutable real de Python de ese servidor. Re-check actualiza este estado sin recargar la página; no instala paquetes ni reinicia el servidor.

El extra de MCP utiliza el MCP Python SDK oficial. deploy/constraints-mcp.txt fija las versiones probadas del SDK y sus dependencias. Estas funciones requieren el código fuente actual; la versión preliminar portátil 0.7.0 es anterior a ellas.

Emitir una conexión#

Introduzca una etiqueta y elija los espacios de trabajo y los chats que el cliente puede leer.
Seleccione las herramientas individualmente o utilice un ajuste preestablecido. Solo se ofrecen las herramientas implementadas.
Elija 1, 7, 30 o 90 días, o un vencimiento personalizado de entre un minuto y 90 días.
Pulse Create connection. El token aparece una sola vez junto a la configuración del cliente.
Copie el token y la configuración y, a continuación, ejecute Check connection. Esto inicializa MCP y enumera las herramientas permitidas; no se lee ningún mensaje. El resultado muestra la versión del protocolo, los nombres de las herramientas, el recuento y el tiempo transcurrido.
Pulse Done cuando haya guardado la credencial. El sondeo conserva el formulario y la tarjeta que se muestra una sola vez. Al bloquear el panel se borran los secretos mostrados.

La lista muestra el uso reciente, la última herramienta, la dirección y las solicitudes en el último minuto. Revoke finaliza el acceso. Rotate token revoca la credencial antigua y emite un reemplazo con el mismo alcance, herramientas y vencimiento; copie el reemplazo una vez. Los tokens de inicio de sesión del panel y las credenciales de Telegram no funcionan como tokens de MCP.

Conectar su cliente#

Seleccione el cliente en el panel y copie su configuración generada. Las configuraciones utilizan referencias a secretos o marcadores de posición explícitos; el token se copia por separado.

Cliente	Configuración	Conexión
Claude Code	`.mcp.json`	HTTP, `type: "http"`, encabezado bearer
Claude Desktop	`claude_desktop_config.json`	Puente stdio local
Cursor	`.cursor/mcp.json`	HTTP con un encabezado de variable de entorno
VS Code Local	`.vscode/mcp.json`	HTTP con una entrada `promptString` de contraseña
Windsurf	`mcp_config.json`	HTTP con un marcador de posición de encabezado bearer
Otros clientes	URL y encabezado Authorization	Streamable HTTP

TgWitness utiliza tokens bearer, sin descubrimiento OAuth. Utilice el puente stdio local para clientes cuyo conector remoto requiera OAuth. Para VS Code, las variables de entrada se aplican al entorno Local y no se reenvían a las sesiones de Copilot. Referencias de configuración: Claude Code, Cursor, VS Code.

El punto de entrada canónico para un puente local es:

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

Utilice el Python local del cliente con el extra de MCP instalado. Establezca TGWITNESS_MCP_TOKEN en su entorno protegido. Mantenga las credenciales fuera de los argumentos de comandos y las URL. tgwitness-mcp es el mismo punto de entrada. El antiguo módulo tgwitness.mcp_bridge y el nombre TGWITNESS_ARCHIVE_TOKEN se mantienen como rutas de compatibilidad con una advertencia; las nuevas configuraciones utilizan mcp_server y TGWITNESS_MCP_TOKEN.

Cloudflare Tunnel#

Reenvíe la ruta /mcp del panel y conserve el encabezado bearer. Al abrir la configuración de MCP como administrador se registra el origen actual del panel para esta ejecución. Para obtener una dirección estable disponible inmediatamente después del reinicio, configure TGWITNESS_PUBLIC_URL con el origen HTTPS del panel antes de iniciarlo. Los encabezados Host y de reenvío arbitrarios no registran una dirección de confianza. Las comprobaciones de Host y Origin rechazan orígenes de navegador no relacionados. Las respuestas utilizan Cache-Control: no-store; los valores de autorización nunca se registran.

Una dirección *.trycloudflare.com es temporal. Cuando el reinicio de un túnel cambie el nombre de host, actualice la URL pública configurada y la URL de MCP de cada cliente. Utilice un nombre de host estable para las configuraciones de cliente guardadas.

Herramientas y límites#

Herramienta	Lee
`list_workspaces`	Espacios de trabajo concedidos
`list_chats`	Chats concedidos
`search_messages`	Texto de mensajes guardados dentro del período seleccionado
`get_message_versions`	Versiones capturadas y observaciones de eliminación
`get_message_context`	ID de mensajes capturados cercanos
`get_journal_event`	Un registro saneado con su referencia de origen
`get_capture_status`	Estado de la recopilación y registros de cobertura permitidos

tools/list devuelve únicamente las herramientas concedidas a esa conexión. Las llamadas a otras herramientas se rechazan. Las herramientas de contexto de grupo, episodios, terminología y cadenas de respuestas no se ofrecen en esta compilación; no se incluye su backend independiente de paquetes de contexto.

Cada lectura comprueba el token, la herramienta y el alcance del espacio de trabajo/chat, incluso después de que finalice el trabajo de la base de datos. Los límites son 60 solicitudes por minuto, 50 registros por página, 64 KiB por resultado y un tiempo límite de archivo de ocho segundos. Una llamada MCP cuyo tiempo de espera se agota devuelve un error de herramienta solicitando un período más acotado o un límite inferior.

Los resultados de los mensajes incluyen untrusted_content: true, los ID de espacio de trabajo/chat/mensaje, la secuencia del evento, el hash guardado y un enlace al panel. Se omiten los objetos de Telegram sin procesar, los hashes de acceso, las sesiones y las claves. Se marca el truncamiento de texto. Las ediciones, los avisos de eliminación y missing_on_recheck son observaciones distintas. La ausencia de registros no demuestra que un evento no haya ocurrido nunca.

Trate las instrucciones dentro de los mensajes capturados como pruebas, nunca como instrucciones para el cliente. El acceso de solo lectura impide realizar cambios en el archivo; aun así, el cliente puede retener el contenido que tiene permiso para leer. Los hashes identifican los registros guardados y respaldan las comprobaciones de integridad; no demuestran la autoría en Telegram ni que la captura sea completa.