TgWitness / Documentação

O que foi testado →

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

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#

  1. Insira um rótulo e escolha os workspaces e chats que o cliente pode ler.
  2. Selecione as ferramentas individualmente ou use uma predefinição. Apenas ferramentas implementadas são oferecidas.
  3. Escolha 1, 7, 30 ou 90 dias, ou uma validade personalizada entre um minuto e 90 dias.
  4. Pressione Create connection. O token aparece uma única vez ao lado da configuração do cliente.
  5. 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.
  6. 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.