MCP somente leitura

Conecte um cliente analista aos workspaces e chats selecionados. O TgWitness serve Streamable HTTP em /mcp no processo do painel. Cada conexão possui seu próprio token, validade e ferramentas permitidas. O MCP não pode enviar mensagens do Telegram, alterar configurações ou modificar o diário assinado.

Guia de fluxo de trabalho · Wiki

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 argumentos de inicialização após a instalação. A verificação de prontidão deve incluir [PASS] mcp: streamable-http available. Integrations → MCP mostra o status de execução e um comando de instalação usando o executável Python real daquele servidor. Re-check atualiza esse status sem recarregar a página; isso não instala pacotes nem reinicia o servidor.

O extra MCP usa o MCP Python SDK oficial. deploy/constraints-mcp.txt fixa o SDK testado e as dependências. Esses recursos exigem o código-fonte atual; a versão prévia portátil 0.7.0 é anterior a eles.

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.

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#

tools/list retorna apenas as ferramentas concedidas àquela 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 compilação; o backend separado de pacote de contexto delas 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 de mensagens contêm untrusted_content: true, IDs de workspace/chat/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 é sinalizado. Edições, avisos de exclusão e missing_on_recheck são observações distintas. Registros ausentes não provam que um evento nunca aconteceu.

Trate instruções dentro de mensagens capturadas como evidência, nunca como instruções para o cliente. O acesso somente leitura impede alterações no arquivo; o cliente ainda pode reter o conteúdo que tem permissão para ler. Hashes identificam registros salvos e apoiam verificações de integridade; eles não provam autoria no Telegram nem captura completa.