Telegram Client API (MTProto)

Resumo

A API de cliente do Telegram opera sobre o protocolo MTProto e permite acesso total aos recursos da conta de usuário de Yan (DMs, grupos privados, canais, histórico completo de mensagens e metadados de anexos sem necessidade de download prévio).

A integração roda localmente como um servidor FastMCP em transporte stdio, registrado no config.yaml do Hermes sob mcp_servers.telegram-user.

Relevância para Yan

• Busca em Grupos de Alto Fluxo: Executa buscas indexadas no servidor do Telegram por palavras-chave e termos específicos em milissegundos.
• Inspeção de Anexos: Lista nomes de arquivos, extensões, MIME types e tamanhos formatados (KB/MB) diretamente dos cabeçalhos das mensagens.
• Download Sob Demanda: Baixa documentos, imagens e mídias apenas quando solicitado explicitamente.
• Segurança: Sessão (yan_telegram.session) e credenciais (.env) isoladas localmente em C:\Users\Yanbd\dev\telegram-user-mcp e protegidas pelo .gitignore.

Status e Validação

• Autenticação: Validada com sucesso para a conta local, sem registrar identificadores da conta.
• Suíte de Testes: 11 testes automatizados em pytest cobrindo parsers de mídia, filtros MTProto, resolução de IDs de chats e schemas do MCP.
• Conectividade End-to-End: Validada via stdio com leitura de diálogos ao vivo, busca de mensagens e extração de anexos.

Diagnóstico e Resolução do Erro em my.telegram.org/apps

Evidência local (2026-08-27)

Durante a criação de aplicação, foi observada uma requisição POST https://my.telegram.org/apps/create com resposta HTTP 200 OK e corpo text/html curto. O corpo da resposta e os campos enviados não foram preservados no registro; portanto, o status HTTP, por si só, não identifica se a aplicação foi criada nem explica uma eventual mensagem exibida pela página.

Procedimento de diagnóstico

1. Em DevTools, registrar o conteúdo da aba Response e os campos não sensíveis da aba Payload da requisição POST /apps/create.
2. Não registrar nem compartilhar cookies, tokens CSRF (hash/stel_token), api_hash, números de telefone ou códigos de autenticação.
3. Confrontar os campos obrigatórios com o formulário atual do portal; a documentação oficial apenas orienta a entrar em my.telegram.org, abrir API development tools e preencher o formulário para obter api_id e api_hash.
4. Se o portal não fornecer uma causa acionável, registrar a mensagem literal exibida e buscar suporte/documentação oficial antes de atribuí-la a validação, reputação de IP ou antispam.

As alegações sobre limites de campos, rejeição de domínios, invalidação de CSRF, filtros de IP e códigos específicos foram removidas desta nota por não possuírem fonte oficial ou evidência local suficiente.

Diagnóstico de ApiIdInvalidError no Telethon

Evidência local (2026-08-27)

A chamada client.send_code_request(phone) do script local de autenticação terminou em ApiIdInvalidError, antes do envio do código de login. Não foram registrados nem devem ser registrados nesta nota o número de telefone, api_id, api_hash, código de login ou conteúdo do arquivo .session.

Interpretação confirmada

O Telegram documenta API_ID_INVALID como uma combinação inválida de api_id e api_hash. O método auth.sendCode recebe ambos os parâmetros; portanto, o diagnóstico deve começar pela combinação efetivamente carregada pelo cliente, e não por telefone, código de autenticação ou sessão.

Procedimento seguro

1. Conferir no painel API development tools de my.telegram.org que a aplicação ainda exibe o par correspondente.
2. Conferir localmente, sem imprimir valores ou enviar capturas, que o carregamento da configuração preserva API_ID como inteiro e API_HASH sem espaços ou aspas acidentais.
3. Copiar novamente o par do painel para o armazenamento local de segredos, se houver divergência, e repetir apenas a solicitação de código.
4. Se o par conferido continuar a falhar, preservar a exceção completa sem dados sensíveis e consultar a documentação/suporte oficial; não atribuir a falha a “tempo de replicação” ou à identificação de dispositivo sem evidência oficial.

Concorrência no arquivo de sessão

Evidência operacional local (2026-09-03): uma tentativa de abrir a mesma sessão Telethon por script enquanto o servidor MCP já a utilizava resultou em bloqueio SQLite. O nome do arquivo e os identificadores da conta não foram registrados.

O FAQ do Telethon confirma que sqlite3.OperationalError: database is locked ocorre quando dois ou mais clientes usam a mesma sessão. Em operação, manter um único processo proprietário da sessão; para uma segunda conexão simultânea, criar e autenticar uma sessão separada. Antes de intervir, identificar o processo que mantém o arquivo aberto (em Linux, fuser é a alternativa indicada pela documentação). Não copiar, mover ou publicar arquivos .session como tentativa de contorno.

Isolamento entre ambiente local e VM

Decisão operacional (2026-09-05): arquivos *.session do Telethon não são sincronizados, copiados ou compartilhados entre o PC local e a VM. Cada ambiente usa seu próprio valor de SESSION_NAME e uma sessão autenticada de forma independente.

Isso evita que processos em hosts distintos reutilizem a mesma chave de autorização. O Telegram informa que sessões principais paralelas com a mesma chave podem disparar AUTH_KEY_DUPLICATED e invalidar a chave; a documentação do Telethon também orienta não usar a mesma sessão em mais de um local. Se houver falha de autorização, revogar a sessão comprometida em um cliente oficial e autenticar novamente apenas no ambiente afetado — nunca tentar corrigir o problema copiando o arquivo de sessão.

Arquitetura do MCP Server Local

telegram-user-mcp/
├── .env                  # API_ID, API_HASH, SESSION_NAME (fora do git)
├── auth.py               # Script interativo 1-time para gerar .session
├── server.py             # Servidor FastMCP com ferramentas MTProto
└── tests/
    ├── conftest.py       # Fixtures e mocks de mensagens Telethon
    ├── test_parsers.py   # Testes unitários de extração de metadados de anexos
    ├── test_search.py    # Testes de paginação e filtros de busca em grupos
    └── test_server.py    # Testes de contrato das ferramentas MCP

Ferramentas Expostas ao Hermes

1. telegram_list_dialogs(limit, dialog_type): Lista conversas, grupos e canais.
2. telegram_get_group_messages(chat_id, limit, offset_id): Lê mensagens recentes estruturadas.
3. telegram_search_messages(chat_id, query, limit, filter_type): Busca indexada no servidor do Telegram.
4. telegram_list_attachments(chat_id, limit, extension): Lista arquivos sem baixá-los, extraindo nome, tamanho e MIME type.
5. telegram_download_attachment(chat_id, message_id, destination_path): Download sob demanda com verificação de integridade.

Plano de Testes Automatizados (TDD)

Antes da execução operacional, a suíte de testes em pytest valida:

• Parser de Anexos: Extração correta de file_name e size para DocumentAttributeFilename, fotos normais, áudios e mensagens de texto puro.
• Sanitização de Chats: Resolução consistente de IDs de supergrupos (-100...), grupos legados e usernames.
• Tratamento de Rate Limit: Captura de FloodWaitError sem queda do processo MCP.
• Isolamento de Segurança: Garantia de que ferramentas de leitura não executem ações de escrita ou download não solicitado.

Decisões Tomadas e Segurança

• Credenciais e arquivos .session permanecem restritos ao ambiente local (C:\Users\Yanbd\dev\telegram-user-mcp).
• O servidor roda em transporte stdio integrado diretamente ao config.yaml do Hermes.

Implantação e compatibilidade

Confirmado (registro operacional local, 2026-08-27): a integração foi configurada tanto no ambiente local quanto na VM. Nos dois ambientes, o requisito do SDK foi limitado a mcp<2 para manter compatibilidade com o servidor baseado na API FastMCP então instalada.

Esse pin é uma decisão de compatibilidade, não uma recomendação permanente: antes de removê-lo, atualizar o servidor e validar a migração para a linha 2.x do SDK em ambiente controlado. O repositório oficial do SDK registra mcp<2 como alternativa temporária para instalações afetadas pela mudança maior da linha 2.

Fontes

• Telegram — Creating your Telegram Application, consultado em 2026-08-27.
• Telegram — User Authorization, consultado em 2026-08-27.
• Telegram — Error handling: API_ID_INVALID, consultado em 2026-08-27.
• Telegram — auth.sendCode, consultado em 2026-08-27.
• Telethon — Signing In, consultado em 2026-08-27.
• Telethon — FAQ: sqlite3.OperationalError: database is locked, consultado em 2026-09-03.
• Telegram — Error handling: AUTH_KEY_DUPLICATED, consultado em 2026-09-05.
• Telethon — FAQ: sessão usada de outro local, consultado em 2026-09-05.
• Model Context Protocol Python SDK — Releases, consultado em 2026-08-27.
• Evidência local: captura de cabeçalhos da requisição POST /apps/create, sem corpo da resposta ou payload completo (2026-08-27).
• Evidência local: registro operacional da integração em ambiente local e VM, sem credenciais, identificadores de conta ou conteúdo de sessão (2026-08-27).
• Evidência local: bloqueio SQLite ao disputar uma sessão Telethon entre o servidor MCP e um script paralelo; sem nome de arquivo, identificadores de conta ou conteúdo de sessão (2026-09-03).
• Evidência local: decisão de manter sessões Telethon independentes no PC local e na VM, sem registrar nomes de sessão, credenciais, identificadores de conta ou conteúdo de arquivos (2026-09-05).