Referência / Arquivo e integrações
Telegram · MCP somente leitura
Conecte um cliente MCP a espaços de trabalho e chats selecionados com acesso temporário e revogável.
TgWitness / Documentação · Integrações com arquivos
Conecte um cliente de análise a espaços de trabalho e chats selecionados. O TgWitness disponibiliza
Streamable HTTP em /mcp no processo do painel. Cada conexão possui seu próprio
token, prazo de validade e ferramentas permitidas. O MCP não pode enviar mensagens do Telegram, alterar
configurações nem modificar o diário assinado. As mesmas conexões funcionam com a
linha de comando.
Guia de fluxo de trabalho · Wiki
Nesta página
Instalar e verificar#
Use o ambiente Python que executa o painel. A partir de um checkout do código-fonte:
# 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 o painel com seu diretório de dados habitual e os argumentos de inicialização após a
instalação. A indicação de prontidão deve incluir [PASS] mcp: streamable-http available.
Mais ferramentas → Integrações → MCP mostra o status de execução e um comando de instalação usando
o executável Python real daquele servidor. A opção Verificar novamente atualiza esse status sem
recarregar a página; ela não instala pacotes nem reinicia o servidor.
O MCP extra utiliza o SDK oficial do MCP para Python. O arquivodeploy/constraints-mcp.txt fixa a versão do SDK testado e suas dependências.
Emitir uma conexão#
- Insira um rótulo e escolha os workspaces e chats que o cliente pode ler.
- Selecione as ferramentas individualmente ou use uma predefinição. Apenas ferramentas implementadas são oferecidas.
- Escolha 1, 7, 30 ou 90 dias, ou uma validade personalizada entre um minuto e 90 dias.
- Pressione Create connection. O token aparece uma única vez ao lado da configuração do cliente.
- Copie o token e a configuração e, em seguida, execute Check connection. Ele inicializa o MCP e lista as ferramentas permitidas; nenhuma mensagem é lida. O resultado mostra a versão do protocolo, nomes das ferramentas, contagem e tempo decorrido.
- Pressione Done quando a credencial estiver salva. As atualizações automáticas preservam o formulário e o cartão exibido uma única vez. Bloquear o painel limpa os segredos exibidos.
A lista mostra o uso recente, a última ferramenta, o endereço e as requisições no último minuto. Revoke encerra o acesso. Rotate token revoga a credencial antiga e emite uma substituta com o mesmo escopo, ferramentas e validade; copie a substituta uma única vez. Tokens de login do painel e credenciais do Telegram não funcionam como tokens MCP.
Conecte seu cliente#
Selecione o cliente no painel e copie a configuração gerada. As configurações usam referências a segredos ou espaços reservados explícitos; o token é copiado separadamente.
| Cliente | Configuração | Conexão |
|---|---|---|
| Claude Code | .mcp.json |
HTTP, type: "http", cabeçalho bearer |
| Claude Desktop | claude_desktop_config.json |
Ponte stdio local |
| Cursor | .cursor/mcp.json |
HTTP com um cabeçalho de variável de ambiente |
| VS Code Local | .vscode/mcp.json |
HTTP com uma entrada promptString de senha |
| Windsurf | mcp_config.json |
HTTP com um espaço reservado para cabeçalho bearer |
| Outros clientes | URL e cabeçalho Authorization | HTTP com transmissão contínua |
O TgWitness usa tokens bearer, sem descoberta OAuth. Use a ponte stdio local para clientes cujo conector remoto exige OAuth. Para o VS Code, as variáveis de entrada aplicam-se ao ambiente Local e não são encaminhadas para sessões do Copilot. Referências de configuração: Claude Code, Cursor, VS Code.
O ponto de entrada canônico para uma ponte local é:
python -m tgwitness.mcp_server --url https://your-panel.example/mcp
Use o Python local do cliente com o extra MCP instalado. Defina
TGWITNESS_MCP_TOKEN em seu ambiente protegido. Mantenha as credenciais fora dos argumentos
de comando e URLs. tgwitness-mcp é o mesmo ponto de entrada. O módulo antigo
tgwitness.mcp_bridge e o nome TGWITNESS_ARCHIVE_TOKEN permanecem como caminhos de
compatibilidade com um aviso; novas configurações usam mcp_server e TGWITNESS_MCP_TOKEN.
Cloudflare Tunnel#
Encaminhe a rota /mcp do painel e preserve o cabeçalho bearer. Abrir as configurações de MCP
como administrador registra a origem atual do painel para esta execução.
Para ter um endereço estável disponível imediatamente após a reinicialização, configure
TGWITNESS_PUBLIC_URL com a origem HTTPS do painel antes de iniciá-lo.
Cabeçalhos Host e de encaminhamento arbitrários não registram um endereço confiável.
As verificações de Host e Origin rejeitam origens de navegador não relacionadas. As respostas usam
Cache-Control: no-store; valores de autorização nunca são registrados nos logs.
Um endereço *.trycloudflare.com é temporário. Quando uma reinicialização do túnel altera o
hostname, atualize a URL pública configurada e a URL do MCP de cada cliente. Use um
hostname estável para configurações de clientes salvas.
Ferramentas e limites#
| Ferramenta | Lê |
|---|---|
list_workspaces |
Workspaces concedidos |
list_chats |
Chats concedidos |
search_messages |
Texto das mensagens salvas dentro do período selecionado; ranked=true utiliza pesquisa de texto completo (formas de palavras, melhores correspondências primeiro, next_offset paginação) |
get_message_versions |
Versões capturadas e observações de exclusão |
get_message_context |
IDs de mensagens capturadas próximas |
get_journal_event |
Um registro higienizado com sua referência de origem |
get_capture_status |
Estado da coleta, registros de cobertura permitidos e gap_summary: números de mensagens nunca observadas, por canal ou supergrupo e para a sequência de toda a conta (detalhes); escolha um chat para ver as lacunas listadas |
get_activity_stats |
Mensagens por hora UTC e dia da semana, dias de pico, proporções de edições e exclusões, remetentes, domínios e @handles, com cobertura (detalhes) |
get_messages_by_date |
Mensagens salvas de um dia do calendário em um fuso horário IANA especificado (Europe/Kyiv, UTC), de acordo com a hora informada pelo Telegram; from_utc e until_utc indique o dia calculado, incluindo o horário de verão |
get_pinned_messages |
Mensagens fixadas no último instantâneo do estado do chat com suas versões salvas, além dos avisos de fixação e desfixação observados em tempo real |
get_chat_stats |
Contagens simples de registros salvos para um chat ou todos os chats no escopo, primeira e última observação, e gap_summary; use-a antes de uma leitura de grande volume |
get_topics |
Tópicos do fórum a partir de mensagens do serviço de tópicos salvos: histórico de títulos, tópicos fechados ou ocultos, contagem de mensagens salvas |
get_media |
Uma imagem preservada como uma pré-visualização JPEG reduzida (no máximo 36 KB), retornada como uma imagem juntamente com seu SHA-256 e o media.saved registro; o arquivo é verificado primeiro em relação ao seu hash registrado, enquanto outros arquivos retornam apenas metadados |
export_messages |
Apenas linha de comando, não selecionado por padrão: transmite as observações salvas como JSON Lines (detalhes); não disponível via MCP |
Todas as ferramentas são somente de leitura (readOnlyHint) e declara um esquema de saída; campos além dos declarados são retornados tal como estão. tools/list Retorna apenas as ferramentas concedidas a essa conexão. Chamadas para outras
ferramentas são recusadas. Ferramentas de contexto de grupo, episódio, terminologia e cadeia de respostas
não são oferecidas nesta versão; seu backend de pacote de contexto separado não está incluído.
Cada leitura verifica o token, a ferramenta e o escopo de workspace/chat, inclusive após a conclusão do trabalho no banco de dados. Os limites são de 60 requisições por minuto, 50 registros por página, 64 KiB por resultado e um tempo limite de oito segundos para o arquivo. Uma chamada MCP que exceda o tempo limite retorna um erro de ferramenta solicitando um período menor ou um limite mais baixo.
Os resultados das mensagens contêm untrusted_content: true, IDs de espaço de trabalho/bate-papo/mensagem,
sequência de eventos, hash salvo e um link para o painel. Objetos brutos do Telegram, hashes de acesso,
sessões e chaves são omitidos. O truncamento de texto é marcado. Edições, avisos de exclusão
e missing_on_recheck são observações distintas. A cobertura mostra os períodos aos quais um
resultado se refere.
Trate as instruções contidas nas mensagens capturadas como evidências, nunca como instruções do cliente. O acesso somente leitura impede alterações no arquivo; o cliente ainda pode manter o conteúdo que tem permissão para ler. Hashes identificam registros salvos e apoiam verificações de integridade. Use as referências de código-fonte e os registros de cobertura anexos ao revisar um resultado.