MCP Hot-Reload

Um servidor proxy de Hot Module Replacement (HMR) para servidores MCP que reinicia automaticamente em alterações de arquivos, armazena mensagens em buffer e gerencia conexões.

GitHub
10
Experimente este MCPPatrocinado

Documentação

mcpmon

Node.js License: MIT Tests Code Style

Monitor de hot-reload para servidores MCP - como o nodemon, mas para o Model Context Protocol

Faça alterações no código do seu servidor MCP e veja-as instantaneamente sem reiniciar seu cliente MCP. Assim como o nodemon reinicia automaticamente aplicações Node.js, o mcpmon reinicia automaticamente servidores MCP.

O que é

O mcpmon é um proxy transparente que fica entre seu cliente MCP (Claude Code, Claude Desktop, MCP Inspector, etc.) e seu servidor MCP. Quando você modifica o código do seu servidor, o mcpmon reinicia automaticamente o servidor enquanto mantém seu cliente conectado.

Principais benefícios:

  • Como nodemon, mas para MCP - Interface de linha de comando simples que você já conhece
  • Zero configuração - Basta envolver seu comando de servidor com o mcpmon
  • Desenvolvimento sem interrupções - Seu cliente MCP permanece conectado enquanto o servidor recarrega
  • Zero perda de mensagens - Requisições são armazenadas em buffer durante a reinicialização do servidor
  • Compatibilidade universal - Funciona com qualquer servidor MCP (Node.js, Python, Deno, etc.)
  • Suporte a biblioteca - Importe como dependência para soluções de monitoramento personalizadas

Início Rápido

  1. Instale globalmente:

    npm install -g mcpmon

  2. Use com seu servidor MCP:

    # Instead of: node server.js
mcpmon node server.js

# Instead of: python server.py  
mcpmon python server.py

# Instead of: deno run --allow-all server.ts
mcpmon deno run --allow-all server.ts

  3. Use com clientes MCP:

    # MCP Inspector
npx @modelcontextprotocol/inspector mcpmon node server.js

# For existing Claude Code/Desktop servers, use setup:
mcpmon setup my-server

    A configuração automática prepara seus servidores MCP existentes para hot-reload! ✨

É isso! Seu servidor MCP agora tem hot-reload habilitado. Edite o código do seu servidor e as alterações serão aplicadas instantaneamente.

Exemplos de Uso

Uso Básico

# Node.js server
mcpmon node server.js

# Python server
mcpmon python -m mcp_server

# Python with args
mcpmon python server.py --port 3000

# Deno server
mcpmon deno run --allow-all server.ts

# With debugging
mcpmon node --inspect server.js

Com MCP Inspector

# Direct command
npx @modelcontextprotocol/inspector mcpmon node server.js

# With environment variables
API_KEY=your-key npx @modelcontextprotocol/inspector mcpmon node server.js

Com Claude Code ou Claude Desktop

Forma mais fácil: Use o comando de configuração automática para servidores existentes:

# Setup hot-reload for an existing server
mcpmon setup my-server

# Setup all stdio servers for hot-reload
mcpmon setup --all

# List available servers
mcpmon setup --list

# Restore original config if needed
mcpmon setup --restore

O comando de configuração automaticamente:

  • ✅ Faz backup da sua configuração original
  • ✅ Detecta e usa versões modernas do Node.js para compatibilidade
  • ✅ Envolve o comando do seu servidor com o mcpmon
  • ✅ Preserva todas as variáveis de ambiente e argumentos
  • ✅ Habilita hot-reload instantaneamente
  • ✅ Idempotente - seguro para executar várias vezes

🔥 Dicas de Hot-Reload para Claude Desktop

Após configurar o hot-reload:

  • Alterações de código: Seu servidor reinicia automaticamente - nenhuma ação necessária!
  • Alterações de esquema (novas ferramentas/recursos): Alterne o servidor MCP desligado/ligado nas configurações do Claude Desktop
    • Vá para Configurações do Claude Desktop → Recursos → Model Context Protocol
    • Alterne seu servidor para desligado e depois para ligado
    • Nenhuma reinicialização necessária - apenas o alternar!
  • Alterações de configuração: Reinicie o Claude Desktop somente se você modificar o arquivo de configuração diretamente

Dica profissional: Para a melhor experiência de desenvolvimento, faça alterações de código primeiro e depois alterações de esquema. O Claude Desktop captará chamadas de ferramentas do código hot-reloaded mais recente mesmo após atualizações de esquema!

Configuração manual: Você também pode atualizar sua configuração manualmente:

Claude Code (~/.claude_code_config):

{
  "mcpServers": {
    "my-server": {
      "command": "mcpmon",
      "args": ["node", "server.js"],
      "env": {
        "API_KEY": "your-key"
      }
    }
  }
}

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "my-server": {
      "command": "/Users/username/.nvm/versions/node/v22.15.0/bin/node",
      "args": ["/usr/local/bin/mcpmon", "python", "server.py"],
      "env": {
        "PYTHONPATH": "/path/to/your/modules"
      }
    }
  }
}

Nota: O comando de configuração detecta automaticamente sua versão mais recente do Node.js e o caminho do mcpmon. O exemplo acima mostra como a configuração gerada se parece - raramente você precisará escrever isso manualmente!

Configuração

O mcpmon funciona perfeitamente com zero configuração. Ele detecta automaticamente o arquivo do seu servidor e começa a monitorar alterações.

Para monitorar arquivos adicionais:

# Watch multiple files
MCPMON_WATCH="server.js,config.json" mcpmon node server.js

É isso! O mcpmon foi projetado para funcionar com zero configuração.

Variáveis de Ambiente

  • MCPMON_WATCH - Substitui arquivos/diretórios a monitorar (separados por vírgula)
  • MCPMON_DELAY - Atraso de reinicialização em milissegundos (padrão: 1000)
  • MCPMON_VERBOSE - Habilita registro detalhado (verbose)

Como Funciona

O mcpmon atua como um proxy transparente entre seu cliente MCP e servidor, fornecendo capacidades automáticas de hot-reload:

sequenceDiagram
    participant Client as MCP Client
    participant mcpmon
    participant Server as MCP Server
    
    Client->>mcpmon: Request
    mcpmon->>Server: Request
    Server->>mcpmon: Response
    mcpmon->>Client: Response
    
    Server->>Server: File changed
    Note right of Server: Auto restart
    
    Client->>mcpmon: Request
    mcpmon->>Server: Request
    Server->>mcpmon: Response
    mcpmon->>Client: Response

A mágica: Seu cliente MCP permanece conectado enquanto seu servidor recarrega. Sem necessidade de reconectar o Claude Code ou reiniciar o MCP Inspector!

RecursoSem mcpmonCom mcpmon
Alterações de arquivosReinicialização manual necessáriaReinicialização automática
Conexão do clienteDeve reconectarPermanece conectado
Mensagens perdidasPossívelNunca (buffer)
Complexidade de configuraçãoAlterações manuais de configuraçãoApenas adicione mcpmon

Precisa de Ajuda?

Habilite o registro detalhado (verbose) para ver o que está acontecendo:

MCPMON_VERBOSE=1 mcpmon node server.js

Problemas comuns:

  • "ReadableStream is not defined"? O mcpmon requer Node.js 16+. Use mcpmon setup para detectar automaticamente versões modernas do Node.js
  • O servidor não inicia? Verifique as mensagens de erro para dependências ausentes
  • Sem hot-reload? Verifique se o arquivo do seu servidor está sendo detectado nos logs
  • Alterações de esquema não visíveis? Alterne seu servidor MCP desligado/ligado nas configurações do Claude Desktop
  • Precisa de ajuda? Veja nosso Guia de Solução de Problemas

Desenvolvimento

# Run tests (includes clean and build)
npm test

# Development mode
npm run dev

Veja o Guia de Contribuição para mais detalhes.

Instalação

Requisitos: Node.js 16+ (detectado automaticamente pelo comando de configuração)

# Install globally (recommended)
npm install -g mcpmon

# Or use without installing
npx mcpmon node server.js

Contribuindo

Aceitamos contribuições! Veja o Guia de Contribuição para detalhes.

Documentação

Licença

Licença MIT - veja o arquivo LICENSE para detalhes.

Gosta do nodemon? Você vai adorar o mcpmon. Hot-reload simples, rápido e confiável para desenvolvimento MCP.