hamster-bot novo: MCP

RU EN PT

Quem faz o quê#

O caminho de um comando: “feche a posição de BTC”#

1. 1A pessoa escreve uma mensagem no app do Claude. Ela vai para a nuvem da Anthropic por HTTPS.
2. 2O Claude Code no VPS consulta a nuvem por conta própria e pega a mensagem. O modelo decide qual ferramenta chamar.
3. 3O agente chama close_position em /mcp com o api_token. O bot verifica o token.
4. 4O servidor MCP transforma a chamada em uma requisição comum a /api/* do mesmo bot e repassa o mesmo token. Por isso o MCP e a API têm a mesma lógica e as mesmas verificações.
5. 5A API passa o comando ao núcleo do bot. O núcleo pega a chave dessa conta.
6. 6O conector assina a requisição e a envia à corretora. O resultado volta pela mesma cadeia e aparece no celular.

O que acontece se uma das partes cair#

O que o agente pode fazer pelo MCP#

Das 87 ferramentas, 42 apenas leem dados (readOnlyHint), e 25 são marcadas como perigosas (destructiveHint): negociam, iniciam bots ou alteram dados de forma irreversível. São ordens a mercado, fechamento de posições, cancelamento de ordens, início de bots, salvamento e exclusão de estratégias e chaves, alteração da configuração, desligamento e atualização do programa. O testador trabalha com dados históricos e não negocia na corretora.

Limites de acesso#

• O token dá direitos de proprietário. Com o api_token, as 87 ferramentas ficam disponíveis, inclusive negociação, exclusão de contas e desligamento do programa. Não existe modo somente leitura.
• A confirmação depende do cliente. As ferramentas perigosas são apenas marcadas; quem deve perguntar à pessoa é o cliente MCP. No modo autônomo as permissões são dadas com antecedência, e o agente age sem perguntar.
• O CLAUDE.md define regras, mas não protege. O agente segue os limites de risco e a proibição de sair da pasta como instruções. Se ele tiver um shell com o mesmo usuário do bot, tecnicamente pode ler os arquivos do bot.
• O token nem sempre é necessário. Com o login pelo Telegram desativado, requisições a /mcp da mesma máquina passam sem token. Isso vale para qualquer processo local.
• A interface web, a API e o MCP usam a mesma porta. Para um agente no mesmo VPS, o endereço 127.0.0.1 basta. De outra máquina o token trafega em texto puro, por isso pela internet é preciso um proxy HTTPS ou um túnel SSH.

Como executar no VPS#

1. No settings_program.json do bot, sem reiniciar:

   Copiar

   "use_mcp": true

2. Uma sessão que sobrevive ao fechamento do SSH:

   Copiar

   tmux new -s agent

3. Conectar o agente ao bot:

   Copiar

   claude mcp add --transport http hamster-bot http://127.0.0.1:<porta>/mcp --header "Authorization: Bearer <api_token>"

4. Abrir a sessão para o celular:

   Copiar

   claude remote-control --name "hamster-bot"

5. No chat da sessão: trabalho autônomo por agendamento:

   Copiar

   /loop 6h Continue o trabalho conforme o CLAUDE.md

Detalhes da conexão#

O MCP vem desativado por padrão. Em vez de editar o arquivo, é possível ativá-lo pela API: POST /api/settings/config com o corpo { "use_mcp": true }.

Endereço: http://127.0.0.1:<porta>/mcp, transporte Streamable HTTP. De outra máquina, use o endereço do servidor em vez de 127.0.0.1.

Em vez de claude mcp add, a conexão pode ser descrita no arquivo .mcp.json do projeto:

{
  "mcpServers": {
    "hamster-bot": {
      "type": "http",
      "url": "http://127.0.0.1:5000/mcp",
      "headers": { "Authorization": "Bearer <api_token>" }
    }
  }
}

Outros clientes se conectam ao mesmo endereço se suportarem Streamable HTTP e cabeçalhos de requisição personalizados.

As regras de acesso são as mesmas da API (veja Acesso). Além do token, o cookie hamster-bot-token funciona com o login ativado. Uma requisição sem nenhum deles recebe 401.

Nomes de argumentos#

Todas as ferramentas usam os mesmos nomes: strategy — nome da estratégia do bot, account — nome da conta, folder — pasta de configurações do testador. Os nomes antigos são aceitos como sinônimos: name em vez de strategy em get_strategy, copy_strategy, delete_strategy, name em vez de account em get_account, get_account_symbols, delete_account, get_account_info, get_balance_history, compact_balance_history, path em vez de folder em set_tester_settings_folder, create_tester_settings_folder, delete_tester_settings_folder. Se não houver nem o nome principal nem o sinônimo, o erro indica o campo esperado. strategy em draft_strategy, draft_tester_settings e get_settings_schema é um código de estratégia (zigzag, mrs2), não um nome. Para configurações do testador, name é o nome do conjunto de configurações.

Um erro da API é devolvido ao agente como erro da ferramenta com o código e o texto, por exemplo HTTP 404: {"success":false,"error":"Strategy not found"}. Respostas muito longas são cortadas em 200.000 caracteres. read_tester_file devolve arquivos de texto em linhas inteiras: uma resposta longa termina com a dica ... [lines A-B of N; continue with offset=B]. Para CSV longos existem os parâmetros offset e limit (uma página de linhas), tail_lines (últimas N linhas), contains (apenas linhas com o texto) e columns (apenas as colunas necessárias); o cabeçalho do CSV é sempre mantido. list_tester_files aceita contains, offset e limit. Relatórios HTML são grandes, por isso para comparar execuções é melhor tester_report_summaries, e para detalhes de uma execução, read_tester_report.

Pesquisa no testador#

O agente pode pesquisar uma estratégia por conta própria. Uma ordem típica:

1. get_field_hints — entender os campos das configurações da estratégia e da configuração do testador, inclusive a sintaxe de parameter_mining; get_settings_schema — quais campos a estratégia realmente lê: minerar um campo sem efeito gera linhas idênticas.
2. create_tester_settings_folder — criar sua própria pasta para o experimento; copy_tester_settings_to_folder — copiar para ela as configurações necessárias. Depois, passar folder a todas as ferramentas do testador.
3. draft_tester_settings e save_tester_settings — criar novas configurações para a corretora, o par e o timeframe desejados. Variantes de configurações existentes não precisam ser salvas: overrides as define na execução.
4. save_tester_config — definir o período, as taxas, parameter_mining e um novo name_comment para o experimento; ativar report.enable_json_report. Para comparar com um bot real, coloque o início do período (StartDate) em um limite do time_frame da estratégia e não antes do início do bot: a estratégia trabalha a partir do primeiro candle do seu timeframe que abre em StartDate ou depois, então um início no meio de um candle de 4h adia as primeiras ordens para o candle seguinte. WarmupDays (padrão 30) apenas aquece os indicadores com o histórico anterior a StartDate: nesses dias a estratégia não negocia nem acumula estado, e a posição e as ordens do bot real não são restauradas do histórico. Se o par tiver menos dados que WarmupDays, a negociação começa mais tarde (com um aviso na resposta).
5. tester_download_data — baixar os candles e aguardar o término em tester_status. O período pode ser definido com start e end, por padrão: início da configuração com aquecimento .. agora (não é preciso alterar a configuração). download.result mostra até que dia cada par realmente tem dados.
6. tester_run_single — verificar uma combinação; tester_wait (ou wait_seconds ao iniciar) aguarda a execução e retorna métricas, avisos e caminhos dos relatórios. tester_run_batch — comparar várias variantes e verificá-las em vários períodos com uma chamada. Ou tester_run_mining — percorrer todas as combinações: resultados em <name_comment>/reports_history.csv (read_tester_file); queue=true coloca a mineração na fila após a atual.
7. read_tester_report — analisar uma execução: a seção summary para comparação, resultados por par, meses, trades. Para um conjunto de estratégias — tester_portfolio_analysis: grupos T/CT, correlação, piores dias, contribuição de cada estratégia para o drawdown.
8. tester_report_summaries, tester_run_stress e walk_forward na configuração — comparar as melhores variantes e verificar sua robustez.
9. send_tester_report_to_telegram — enviar o relatório final ao usuário no Telegram, se ele pedir.

Uma estratégia por par#

Em uma conta, um par (basic.symbol) pode ter apenas uma estratégia, tanto na negociação real quanto no testador. Uma conta pode ter quantos pares quiser (até 200), e as estratégias neles podem ser diferentes ou iguais, mas o símbolo deve ser único entre as estratégias da conta. Uma estratégia em um par ocupado é salva, mas não inicia (no log aparece DUBLICATE SUMBOL ON API); verifique list_strategies por conta e par antes de save_strategy, copy_strategy (copie para outro par) e create_strategy_from_tester. Configurações do testador que rodam na mesma execução também precisam estar em pares diferentes; para comparar várias configurações em um par, execute cada uma separadamente (itens de tester_run_batch ou mineração com single_mode).

Reinvestimento e comparação de variantes#

O tamanho da posição por basic.balance_percentage_long/_short é calculado sobre o saldo atual, então o lucro é reinvestido e o PnL % anual fica inflado. Para comparar variantes e períodos de forma justa, desative o crescimento do tamanho de uma destas formas:

1. basic.use_fix = true e basic.my_fix_balance = 50: cada ordem é calculada sobre 50 unidades da moeda de cotação (geralmente USDT), independentemente do saldo.
2. basic.max_balance = 2000: enquanto o saldo for menor, o bot trabalha com o saldo real; com saldo de 2350 o tamanho é calculado sobre 2000, e acima do limite o reinvestimento para.
3. basic.lot_long / basic.lot_short: um tamanho constante de ordem enviado à corretora.

Algumas estratégias podem mudar esse tamanho base pela própria lógica. Os parâmetros podem ser definidos pelos overrides da execução (set) ou minerados em parameter_mining.

As respostas de salvamento e execução contêm warnings: campos que as configurações não leem. check_tester_settings verifica assim a pasta inteira.

Passagem para a negociação e controle#

create_strategy_from_tester leva uma configuração verificada para o bot — a estratégia é criada pausada, e play_bot a inicia após a verificação. O agente avalia um bot real assim: depois que o dia fecha e os candles podem ser baixados, executa o testador com as mesmas configurações e no mesmo período (import_tester_settings copia a estratégia para a pasta do testador) e obtém as estatísticas completas — normalmente coincidem com a negociação real. O resultado efetivo é o histórico de saldo get_balance_history (gravado com monitoring.enabled ativado).

As instruções do servidor e as descrições das ferramentas explicam ao agente a regra principal da negociação real: a posição e as ordens não podem ficar sem controle. Uma estratégia pausada não as gerencia, por isso o desligamento segue apenas a ordem pausar → cancelar ordens → fechar a posição → excluir (delete_strategy com full=true faz isso sozinho).

Logs#

Cada bot (estratégia em um par) tem seu log: log_<data>_<Corretora> <conta> <par> <timeframe> <estratégia> <nome>.log — níveis, sinais, ordens colocadas e canceladas, preenchimentos, mudanças de posição e erros da estratégia; por ele se vê por que o bot negociou ou não. Cada conta tem log_<conta>_<data>.log: saldos e posições da corretora, respostas e erros da API da corretora, limitador de posições, close_by_margin. O log geral do programa é log_<data>.log (get_log), os logs do testador são TESTER_*.log. O formato da data nos nomes varia, por isso os arquivos são procurados pelo nome da estratégia ou da conta: list_log_files com contains, depois read_log_file.

Exemplos de uso#

Abaixo estão pedidos ao agente e as chamadas de ferramentas que ele faz. Os argumentos aparecem em JSON, como o cliente MCP os envia. A pasta lut_now, os nomes de configurações e as datas são exemplos.

tester_run_single {
  "settings": ["*"], "folder": "lut_now", "wait_seconds": 240,
  "overrides": [
    { "match": "T_*", "mul": { "basic.balance_percentage_long": 2, "basic.balance_percentage_short": 2 }, "cap_pct": 10 },
    { "match": "C_MU", "set": { "basic.use_short": false } }
  ],
  "periods": [["2026-05-01", "2026-08-01"], ["2026-08-01", "2026-10-26"]]
}

tester_run_batch {
  "folder": "lut_now", "parallel": 2, "wait_seconds": 240,
  "periods": [["2026-05-01", "2026-08-01"], ["2026-08-01", "2026-10-26"]],
  "runs": [
    { "name": "base", "settings": ["*"] },
    { "name": "T x2", "settings": ["*"], "overrides": [{ "match": "T_*", "mul": { "basic.balance_percentage_long": 2 } }] },
    { "name": "sem L_X", "settings": ["*"], "overrides": [{ "match": "L_X", "exclude": true }] },
    { "name": "apenas long", "settings": ["*"], "sides": "long" }
  ]
}

Exemplos: o que pedir ao agente

Fale com o agente em linguagem comum: ele escolhe as ferramentas, chama-as uma após a outra e explica o resultado.

Pesquisa no testador

Bot em operação: leitura e análise

Controle: com confirmação

Antes de ações reais o agente mostra o que vai fazer, e o cliente pede confirmação para cada ferramenta destrutiva, a menos que as permissões tenham sido dadas com antecedência (veja Limites de acesso).