Kontomanager

Um servidor não oficial para gerenciar contas móveis austríacas de marcas como yesss!, Georg e XOXO.

GitHub
2

Documentação

Servidor MCP para Kontomanager

Um servidor MCP não oficial para as marcas austríacas de telefonia móvel yesss!, Georg e XOXO.

Este servidor atua como uma ponte, expondo as funcionalidades da interface web do Kontomanager por meio de um conjunto estruturado de ferramentas MCP. Ele permite que você leia programaticamente informações da conta, verifique o uso, baixe faturas e modifique configurações como desvios de chamadas.

✨ Recursos

Este servidor é projetado com uma abordagem ferramenta-primeiro para amplo suporte a clientes. Ele fornece um conjunto abrangente de funções que espelham o portal web:

  • Ler Dados da Conta: Obtenha uso, crédito, detalhes do plano, números de telefone e histórico de chamadas.
  • Gerenciar Faturas: Liste faturas anteriores e baixe o conteúdo em PDF.
  • Modificar Configurações: Altere configurações do SIM, como roaming, e configure regras detalhadas de desvio de chamadas.
  • Fluxos de Trabalho de Alto Nível: Use ferramentas simples para ações comuns, como desativar o correio de voz.

🛠️ Ferramentas Disponíveis

O servidor expõe toda a funcionalidade por meio de ferramentas, que podem ser chamadas por um cliente MCP ou um LLM.

Ferramentas de Recuperação de Dados

  • get_account_usage(): Recupera a visão geral principal da conta, incluindo detalhes do plano, estatísticas de uso e saldo de crédito.
  • get_phone_numbers(): Lista todos os números de telefone associados à conta conectada.
  • list_bills(): Obtém uma lista de faturas disponíveis (somente metadados).
  • download_bill(bill_number, document_type): Obtém uma fatura específica ou seu registro detalhado (EGN) e retorna seu conteúdo binário (PDF).
  • get_call_history(): Recupera uma lista de chamadas e mensagens SMS recentes.
  • get_sim_settings(): Lê o estado atual de todas as configurações relacionadas ao SIM (ex.: status de roaming, bloqueio de dados).
  • get_call_forwarding_settings(): Lê as configurações atuais de desvio de chamadas e correio de voz.

Ferramentas de Ação e Fluxo de Trabalho

  • switch_active_phone_number(subscriber_id): Alterna o número de telefone ativo para a sessão.
  • toggle_roaming(enabled): Uma ferramenta simples para ativar ou desativar o roaming internacional.
  • set_sim_setting(setting_name, enabled): Uma ferramenta de baixo nível para ativar ou desativar uma configuração específica do SIM.
  • set_call_forwarding_rule(...): Uma ferramenta de baixo nível para configurar uma regra específica de desvio de chamadas (ex.: desviar quando ocupado para um número específico).

🗣️ Exemplo de Uso

Você pode interagir com este servidor usando linguagem natural em um cliente MCP compatível. O LLM do cliente selecionará e executará as ferramentas apropriadas.

  • "Qual é o meu uso de dados e crédito atuais?"
    • → Chama get_account_usage()
  • "Mostre-me minhas últimas faturas."
    • → Chama list_bills()
  • "Baixe minha fatura número 8177 e o registro detalhado dela."
    • → Chama download_bill(bill_number='8177', document_type='bill')
    • → Chama download_bill(bill_number='8177', document_type='egn')
  • "Ative o roaming para minha viagem."
    • → Chama toggle_roaming(enabled=True)
  • "Desvie todas as minhas chamadas para +436811234567 quando minha linha estiver ocupada."
    • → Chama set_call_forwarding_rule(condition='wtel', target='a', target_number='+436811234567')

⚙️ Configuração

O servidor requer suas credenciais do Kontomanager. Elas devem ser fornecidas por meio de variáveis de ambiente, que você definirá no arquivo de configuração do seu cliente MCP.

As variáveis necessárias são:

  • KONTOMANAGER_BRAND: A marca da sua operadora móvel. Valores suportados: "yesss", "georg", "xoxo".
  • KONTOMANAGER_USERNAME: Seu número de telefone de login ou nome de usuário.
  • KONTOMANAGER_PASSWORD: Sua senha da conta Kontomanager.

🚀 Configuração e Uso

Este projeto é um servidor MCP e é projetado para ser iniciado e gerenciado por um cliente MCP. Você não o executa de forma independente.

  1. Clone o repositório:

    git clone https://github.com/dhofer/mcp-server-kontomanager.git

  2. Configure seu cliente MCP: Adicione uma nova definição de servidor ao arquivo de configuração do seu cliente MCP. O comando usará uv run para executar o servidor a partir do seu diretório local. Certifique-se de usar o caminho absoluto para o repositório clonado.

    {
  "mcpServers": {
    "kontomanager": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/mcp-server-kontomanager",
        "python",
        "src/server.py"
      ],
      "env": {
        "KONTOMANAGER_BRAND": "yesss",
        "KONTOMANAGER_USERNAME": "43681...",
        "KONTOMANAGER_PASSWORD": "your_secret_password"
      }
    }
  }
}

⚠️ Avisos Importantes: Leia Antes de Usar

Privacidade de Dados

Quando você usa este servidor MCP, quaisquer dados recuperados pelas ferramentas (como uso da conta, números de telefone ou detalhes de fatura) são enviados ao Modelo de Linguagem Grande (LLM) que alimenta seu cliente MCP. Isso significa que uma empresa terceirizada (ex.: OpenAI, Google, Anthropic) processará essas informações potencialmente sensíveis. Esteja ciente das implicações de privacidade e revise as políticas do seu provedor de LLM antes de usar este servidor.

Risco Financeiro

Este servidor fornece ferramentas que podem alterar as configurações da sua conta móvel em tempo real. Ações como toggle_roaming ou set_call_forwarding_rule podem levar a cobranças significativas e reais na sua conta de telefone, especialmente se mal configuradas. Você é o único responsável por todos e quaisquer custos incorridos como resultado do uso dessas ferramentas. Use-as com extrema cautela.

🧑‍💻 Filosofia de Desenvolvimento

Este projeto é, para todos os efeitos, codado por vibração (vibe coded). Foi construído com base na intuição e nas necessidades específicas do desenvolvedor. Embora tenha como objetivo ser funcional, pode não seguir as práticas de engenharia mais rigorosas e possui testes limitados. Pull requests para melhorar a robustez, adicionar testes ou refinar o código são altamente incentivados!

Aviso Legal: Este é um projeto não oficial e não é afiliado, endossado ou apoiado pela A1 Telekom Austria AG ou qualquer uma de suas marcas. A estrutura do site Kontomanager pode mudar a qualquer momento, o que pode quebrar a funcionalidade deste servidor. Use por sua conta e risco.