keenetic-mcp

keenetic-mcp

Controle seu roteador Keenetic a partir do Claude, Codex, Cursor ou qualquer agente MCP.

Pergunte ao seu agente sobre sua rede em linguagem natural. Sem pendrive, sem Entware, nada instalado no roteador.

> who is using the most bandwidth right now?

  Three devices are active. Sorted by traffic:

  work-laptop      wifi:HomeNet   -46 dBm    7.7 GB down
  living-room-tv   wired:Home                3.2 GB down
  hallway-camera   wifi:HomeNet   -48 dBm    5.4 MB down

  The laptop is on the 2.4 GHz radio at -46 dBm, which is a strong
  signal, so the throughput is not a coverage problem.

> block the camera until tomorrow morning

  Blocked hallway-camera (02:00:00:00:00:14).

  Applied to the running configuration and verified, but NOT saved.
  A reboot discards it. Backup taken before the change:
  ~/Library/Application Support/keenetic-mcp/backups/…txt

  Say the word and I will make it permanent, or leave it and it
  reverts on the next restart.

Por quê

• Nada no roteador. Ele conversa com a API HTTP do próprio roteador pela sua LAN. Sem pendrive, sem Entware, sem modificação de firmware.
• Funciona em qualquer Keenetic. O conjunto de ferramentas se adapta ao que seu modelo e firmware específicos realmente suportam.
• Seguro por construção. As alterações nunca são salvas a menos que você peça, um backup é feito antes da primeira alteração, e cada alteração é relida e verificada antes de ser reportada como concluída.
• Somente leitura, se você quiser. Uma única flag e o agente fisicamente não consegue alterar nada.

Instalação

Claude Code

/plugin marketplace add salatmaster/keenetic-mcp
/plugin install keenetic@keenetic

Em seguida, execute o assistente de configuração no seu terminal:

npx -y keenetic-mcp init

Codex

codex plugin marketplace add salatmaster/keenetic-mcp
codex plugin add keenetic@keenetic
npx -y keenetic-mcp init

Isso traz as habilidades junto com o servidor. Para o servidor isoladamente:

codex mcp add keenetic -- npx -y keenetic-mcp

Qualquer outra coisa

{
  "mcpServers": {
    "keenetic": { "command": "npx", "args": ["-y", "keenetic-mcp"] }
  }
}

O assistente encontra seu roteador a partir do gateway padrão, confirma que realmente é um Keenetic, verifica a senha contra ele e armazena a senha no chaveiro do seu sistema operacional. Apenas o endereço e o login vão para um arquivo de configurações.

Prefere variáveis de ambiente? KEENETIC_HOST, KEENETIC_USER e KEENETIC_PASSWORD substituem tudo, que é o que você quer em um contêiner.

O que ele pode fazer

Leitura

Ferramenta
list_devices	todos os dispositivos, filtrados por ativo, com fio, sem fio ou bloqueado, ordenados por tráfego ou sinal
get_device	um dispositivo completo: concessão, taxa Wi-Fi, política, agendamento, tráfego
list_interfaces	links WAN, bridges, pontos de acesso, túneis VPN
get_interface	uma interface completa, incluindo peers WireGuard
get_wifi_status	rádios por banda, com contagens de clientes
get_internet_status	alcançabilidade e qual verificação falhou
list_routes	tabela de roteamento, ou apenas a rota padrão
list_policies	políticas de conexão para roteamento seletivo
get_system_info	modelo, firmware, CPU, memória, componentes instalados
get_config_state	alterações não salvas, quem alterou o quê e quando
list_segments	todas as bridges e se a interface web as lista como um segmento
backup_config	baixar a configuração para um arquivo local

Alteração

Ferramenta
update_device	renomear, bloquear ou permitir, atribuir uma política de roteamento, agendamento ou prioridade
set_interface_state	ativar ou desativar uma interface
create_segment	uma rede de convidados ou IoT que a interface web realmente lista, com Wi-Fi, DHCP e roteamento VPN opcional
delete_segment	remover um segmento e tudo o que foi criado com ele
save_config	fazer as alterações pendentes sobreviverem a uma reinicialização

Saída de emergência

Ferramenta
rci_call	qualquer caminho da API do roteador, para o que as ferramentas acima não cobrirem

Habilidades incluídas

O plugin inclui quatro habilidades, para que o agente saiba como seu roteador se comporta em vez de adivinhar. Um único diretório de plugin atende tanto ao Claude Code quanto ao Codex: eles leem manifestos diferentes, mas compartilham as mesmas habilidades e a mesma definição de servidor.

• keenetic-rci ensina a árvore da API do roteador: quais caminhos existem, quais retornam 100 KB e como recuperar a sintaxe exata de um comando a partir da configuração do próprio roteador.
• keenetic-safe-changes ensina o fluxo de trabalho de alterações: o que o fail-safe do roteador protege e não protege, e quais interfaces cortarão seu próprio acesso.
• keenetic-segments cobre a construção de uma rede isolada que o roteador admitirá que existe. A maneira óbvia produz uma rede de convidados que transporta tráfego perfeitamente e nunca aparece na interface web, porque um segmento é baseado em VLAN e a VLAN é a parte que todos deixam de fora.
• keenetic-troubleshoot é um manual de diagnóstico ordenado para "a internet está fora", "o Wi-Fi está ruim" e "um dispositivo não consegue se conectar".

Segurança

• Nada é salvo a menos que você peça. As alterações se aplicam à configuração em execução e são descartadas na reinicialização até que save_config seja chamado. O servidor nunca o chama por conta própria.
• Um backup é feito automaticamente antes da primeira alteração de uma sessão.
• Cada alteração é verificada. O roteador aceita alguns comandos errados silenciosamente e não altera nada, então cada escrita é relida e comparada antes de ser reportada como bem-sucedida.
• O modo somente leitura é realmente somente leitura. Com --read-only, as ferramentas de escrita não são registradas, em vez de registradas e recusando, então o agente nunca as vê.
• Sua senha vai para o chaveiro do sistema, não em um arquivo de configuração, e nunca em um log ou resposta de ferramenta.
• Somente LAN. Sem nuvem, sem telemetria, sem conexão de saída para nada além de seu roteador.

Onde a senha é armazenada em cada plataforma e como reportar algo privadamente estão em SECURITY.md.

Roteadores suportados

RCI, a API usada, é uma parte padrão do KeeneticOS em vez de um recurso de modelos caros, então isso funciona em toda a linha. Verificado em um Keenetic Ultra (KN-1811) com KeeneticOS 5.1.3.

Modelos no ramo atual 5.1: Giga (KN-1010), Hero (KN-1011, KN-1012), Start e Starter (KN-1111, KN-1112, KN-1121), Air e Explorer (KN-1613, KN-1621), Extra e Carrier (KN-1713, KN-1714, KN-1721), Ultra e Titan (KN-1810, KN-1811, KN-1812). Hardware mais antigo em 4.x e anteriores também tem RCI; o conjunto de ferramentas se adapta aos componentes que cada roteador realmente tem.

Como funciona

Os roteadores Keenetic expõem RCI, um espelho JSON de sua árvore de linha de comando, via HTTP. Este servidor autentica com o esquema de desafio-resposta do roteador, mantém uma sessão ativa durante as perguntas do agente e molda as respostas para que caibam no contexto de um modelo: a listagem bruta de interfaces sozinha tem 32 KB, e a tabela NAT tem mais de 100 KB.

Não há documentação pública coerente para RCI, então docs/rci-api.md são as anotações feitas durante a construção disso: o handshake de autenticação, os caminhos que existem, as armadilhas e como recuperar a sintaxe de um comando do próprio roteador.

Desenvolvimento

npm install
npm test          # no router required
npm run typecheck
npm run build

Um checkout reporta sua versão como 0.0.0-dev, porque não há versão escrita em nenhum lugar nos fontes. Coloque KEENETIC_MCP_VERSION em um .env na raiz do repositório para dizer o contrário; o mesmo arquivo pode conter KEENETIC_HOST e KEENETIC_PASSWORD para que você não precise exportá-los. Uma variável de ambiente real sempre vence esse arquivo, e uma cópia instalada nunca lê um.

Os testes rodam contra fixtures sanitizadas capturadas de um roteador real. Para atualizá-las e para rodar um teste de fumaça somente leitura contra o seu próprio:

KEENETIC_HOST=… KEENETIC_PASSWORD=… npm run capture:fixtures
KEENETIC_TEST_HOST=… KEENETIC_TEST_PASSWORD=… npm run smoke

As fixtures são anonimizadas deterministicamente e um teste varre todo o repositório por qualquer coisa que pareça um endereço MAC real, IP privado ou chave.

O assistente de configuração lê uma senha do terminal, que nenhum teste de unidade consegue alcançar: entrada canalizada usa um caminho de código completamente diferente. Essa parte é verificada com um script que dirige um pty real, então precisa de um terminal e não pode rodar em CI:

KEENETIC_TEST_PASSWORD=… ./scripts/verify-wizard.exp

Lançamento

Um lançamento é uma tag e nada mais. Não há commit de versão para escrever, porque não há versão no repositório para alterar: package.json carrega 0.0.0-dev, os manifestos do plugin não carregam nenhum, e o fluxo de trabalho de lançamento carimba a tag em package.json imediatamente antes de publicar, sem commitá-la.

git tag v0.2.2 && git push origin v0.2.2

O fluxo de trabalho recusa uma tag que não nomeia uma versão, e um teste recusa uma árvore que tem uma versão escrita nela, então os dois nunca podem discordar. Os plugins fixam keenetic-mcp@^0, que rastreia apenas a major e deve ser editado uma vez, em 1.0.

Licença

MIT