REPL MCP Server

Um gerenciador universal de sessões REPL compatível com Python, Node.js, Ruby e outros, com gerenciamento de sessões e recuperação assistida por LLM.

GitHub
3
Experimente este MCPPatrocinado

Documentação

repl-mcp

REPL MCP

Um servidor MCP simples para gerenciar sessões de REPL. Fornece ferramentas básicas para criar e executar comandos em vários REPLs e shells, com uma Interface Web integrada para monitoramento de sessão baseado em navegador.

Motivação

Trabalhar com REPLs remotos (como o console do Rails em servidores de produção) muitas vezes força você a compactar operações complexas em comandos únicos, já que perder a conexão significa perder o estado da sessão. Esta ferramenta permite sessões REPL persistentes que sobrevivem a execuções individuais de comandos, permitindo que você trabalhe naturalmente com ambientes interativos por meio de agentes de IA. A Interface Web integrada fornece monitoramento baseado em navegador para observação de sessões.

Recursos

Recursos Principais

  • Suporte a Múltiplos REPLs: Python, IPython, Node.js, Ruby (pry, irb), bash, zsh
  • Gerenciamento de Sessão: Criar, executar comandos e destruir sessões REPL
  • Integração com Interface Web: Monitoramento de terminal baseado em navegador para observação de sessões
  • Configuração Personalizável: Configure comandos de setup e variáveis de ambiente
  • Multiplataforma: Funciona em Windows, macOS e Linux

Recursos Adicionais

  • Recuperação por Timeout: Assistência de LLM quando comandos expiram
  • Aprendizado de Sessão: Lembra padrões de prompt nas sessões

Monitoramento de Sessão Baseado em Navegador

  • URLs de Sessão: http://localhost:8023/session/SESSION_ID - Monitore sessões no navegador
  • Portas Dinâmicas: Seleciona automaticamente portas disponíveis a partir de 8023
  • Multiplataforma: Funciona em qualquer dispositivo com navegador moderno
  • Tempo Real: Saída de terminal ao vivo via conexão WebSocket

Instalação

npm version Install in VS Code
Install MCP Server

VS Code

Clique no botão acima ou adicione ao seu .vscode/mcp.json:

{
  "servers": {
    "repl-mcp": {
      "command": "npx",
      "args": ["-y", "repl-mcp@latest"]
    }
  }
}

Claude Code

claude mcp add repl-mcp -- npx -y repl-mcp@latest

Configuração Manual do MCP

Adicione ao seu arquivo de configurações MCP:

{
  "mcpServers": {
    "repl-mcp": {
      "command": "npx",
      "args": ["-y", "repl-mcp@latest"]
    }
  }
}

A Partir do Código Fonte

  1. Clone este repositório
  2. Instale as dependências: npm install
  3. Compile o projeto: npm run build
  4. Adicione às suas configurações MCP:
{
  "mcpServers": {
    "repl-mcp": {
      "command": "node",
      "args": ["path/to/repl-mcp/build/index.js"]
    }
  }
}

Ferramentas Disponíveis

create_session

Cria uma nova sessão REPL com configuração predefinida ou personalizada. Use displayName para definir um nome personalizado que aparece no título da aba do navegador. Retorna uma webUrl que pode ser aberta em um navegador para monitorar a sessão via Interface Web.

Parâmetros:

  • presetConfig (opcional): Nome da configuração predefinida
  • displayName (opcional): Nome de exibição personalizado para a sessão (mostrado na aba do navegador)
  • customConfig (opcional): Objeto de configuração personalizado

Exemplo com predefinição:

{
  "presetConfig": "pry",
  "displayName": "My Ruby Session"
}

Exemplo com configuração personalizada:

{
  "displayName": "Custom Python Session",
  "customConfig": {
    "type": "python",
    "shell": "bash",
    "commands": ["python3"],
    "timeout": 10000
  }
}

Resposta:

{
  "success": true,
  "sessionId": "abc123",
  "config": "Ruby Pry REPL",
  "webUrl": "http://localhost:8023/session/abc123"
}

A resposta inclui:

  • sessionId: Identificador único da sessão (formato de 6 caracteres)
  • webUrl: URL do navegador para monitoramento da sessão
  • config: Nome da configuração utilizada

send_input_to_session

Envia entrada para uma sessão REPL.

Parâmetros:

  • sessionId: O ID da sessão
  • input: Texto de entrada para enviar à sessão
  • options (opcional): Objeto de opções de entrada
    • wait_for_prompt (padrão: false): Aguardar o prompt retornar
    • timeout (padrão: 30000): Timeout em milissegundos
    • add_newline (padrão: true): Adicionar nova linha à entrada

Exemplo:

{
  "sessionId": "abc123",
  "input": "puts 'Hello, World!'",
  "options": {
    "wait_for_prompt": true
  }
}

list_repl_sessions

Lista todas as sessões REPL ativas. Cada sessão inclui uma webUrl para acesso pelo navegador.

A resposta inclui:

  • sessions: Matriz de objetos de sessão com webUrl para cada uma
  • Cada sessão inclui: id, name, type, status, webUrl, etc.

get_session_details

Obtém informações detalhadas sobre uma sessão específica. Inclui webUrl para acesso pelo navegador.

Parâmetros:

  • sessionId: O ID da sessão

A resposta inclui:

  • session: Informações detalhadas da sessão
  • webUrl: URL do navegador para monitoramento da sessão

destroy_repl_session

Destrói uma sessão REPL existente.

Parâmetros:

  • sessionId: O ID da sessão

list_repl_configurations

Lista todas as configurações REPL predefinidas disponíveis.

send_signal_to_session

Envia um sinal (como Ctrl+C, Ctrl+Z) para interromper ou controlar o processo de uma sessão REPL.

Parâmetros:

  • sessionId: O ID da sessão
  • signal: Sinal a enviar (SIGINT, SIGTSTP, SIGQUIT)

Exemplo:

{
  "sessionId": "abc123",
  "signal": "SIGINT"
}

Observação sobre Windows: No Windows, apenas SIGINT é efetivamente funcional. Ele é enviado como um evento Ctrl+C e pode ser usado para interromper comandos em execução ou encerrar processos compatíveis, como REPLs do Node.js. SIGTSTP e SIGQUIT não têm efeito.

set_session_ready

Marca uma sessão como pronta com um padrão de prompt específico. Usado durante a recuperação da sessão.

Parâmetros:

  • sessionId: O ID da sessão
  • pattern: Padrão de prompt (regex ou string literal)

Exemplo:

{
  "sessionId": "abc123",
  "pattern": "❯ "
}

wait_for_session

Aguarda mais tempo para que uma sessão fique pronta.

Parâmetros:

  • sessionId: O ID da sessão
  • seconds: Número de segundos para aguardar

Exemplo:

{
  "sessionId": "abc123",
  "seconds": 5
}

mark_session_failed

Marca uma sessão como falha com um motivo.

Parâmetros:

  • sessionId: O ID da sessão
  • reason: Motivo da falha

Exemplo:

{
  "sessionId": "abc123",
  "reason": "Process crashed"
}

Configurações Predefinidas

Observação: Cada ferramenta REPL deve estar instalada e disponível no seu PATH.

Configurações de REPL

  • pry: REPL Ruby Pry com recursos avançados de depuração
  • irb: REPL Ruby IRB com funcionalidade padrão
  • ipython: REPL Python aprimorado com recursos ricos
  • node: REPL JavaScript do Node.js
  • python: REPL Python padrão

Configurações de Shell

  • bash: Ambiente de shell Bash
  • zsh: Ambiente de shell Zsh (com suporte a Oh My Zsh)

Configurações Avançadas

  • rails_console: Console Rails com bundle exec
  • rails_console_production: Console Rails de produção

Recuperação de Sessão

Quando sessões expiram ou ficam sem resposta, você pode usar ferramentas de recuperação:

  • send_signal_to_session - Envie Ctrl+C, Ctrl+Z ou outros sinais para interromper processos
  • set_session_ready - Marque a sessão como pronta quando detectar um prompt funcional
  • wait_for_session - Aguarde mais tempo para comandos lentos serem concluídos
  • mark_session_failed - Marque a sessão como falha quando a recuperação não for possível

Padrões de prompt aprendidos durante a recuperação são lembrados durante a duração da sessão.

Exemplos de Uso

Uso Básico do REPL

Criar uma Sessão Python

{
  "tool": "create_session",
  "arguments": {
    "presetConfig": "python",
    "displayName": "My Python Session"
  }
}

Resposta:

{
  "success": true,
  "sessionId": "xyz789",
  "config": "Python REPL",
  "webUrl": "http://localhost:8023/session/xyz789"
}

Executar Código Python

{
  "tool": "send_input_to_session",
  "arguments": {
    "sessionId": "xyz789",
    "input": "print('Hello from REPL!')",
    "options": {
      "wait_for_prompt": true
    }
  }
}

Monitoramento de Sessão na Interface Web

Para monitorar uma sessão, crie-a usando as ferramentas MCP e abra o webUrl da resposta em um navegador. Isso permite observar a atividade do terminal em tempo real.

Fluxo de Trabalho de Exemplo:

  1. Crie a sessão via MCP para obter um webUrl.
  2. Abra a URL em um navegador (por exemplo, http://localhost:8023/session/xyz789), manualmente ou usando ferramentas de automação como Playwright MCP.
  3. Observe o terminal ao vivo.

Exemplo de Recuperação de Sessão

Quando um comando expira ou trava, você pode recuperar a sessão:

Interromper com Ctrl+C:

{
  "tool": "send_signal_to_session",
  "arguments": {
    "sessionId": "xyz789",
    "signal": "SIGINT"
  }
}

Marcar sessão como pronta:

{
  "tool": "set_session_ready",
  "arguments": {
    "sessionId": "xyz789",
    "pattern": "❯ "
  }
}

Gerenciamento de Sessão

Cada sessão mantém:

  • ID de sessão único: Formato de 6 caracteres para fácil identificação e gerenciamento
  • Detalhes da configuração: Tipo de REPL, shell, comandos de setup, etc.
  • Status atual: inicializando, pronto, executando, erro, encerrado
  • Histórico de comandos: Registro de comandos executados
  • Última saída e erros: Resultados de execução mais recentes
  • Registros de data e hora de criação e atividade: Rastreamento do ciclo de vida da sessão
  • Padrões de prompt aprendidos: Padrões personalizados descobertos por meio de assistência de LLM
  • Acesso à Interface Web: URL do navegador para monitoramento da sessão

Ciclo de Vida da Sessão

  1. Inicialização: Sessão criada com a configuração especificada
  2. Pronto: Sessão preparada para execução de comandos
  3. Executando: Comando sendo processado
  4. Aprendizado: Assistência de LLM para detecção de prompt (quando necessário)
  5. Otimizado: Padrões aprendidos permitem execução rápida

Tratamento de Erros

O servidor fornece tratamento abrangente de erros com recuperação inteligente:

Tratamento de Erros Tradicional

  • Falhas na criação de sessão: Mensagens de erro claras com informações de diagnóstico
  • Timeouts na execução de comandos: Tratamento gracioso de timeout com opções de nova tentativa
  • Crashs de REPL e recuperação: Detecção automática e gerenciamento de estado da sessão
  • Detecção de comandos inválidos: Validação de entrada e relatório de erros

Recuperação Aprimorada por LLM

  • Falhas na detecção de prompt: Consulta automática ao LLM para prompts desconhecidos
  • Tratamento de timeout adaptativo: Espera inteligente com base na complexidade do comando
  • Suporte a ambientes personalizados: Aprendizado dinâmico para shells não padrão
  • Análise de erros contextual: Informações ricas de erro para solução de problemas

Formato de Resposta de Erro

Erro Padrão:

{
  "success": false,
  "error": "Session not found",
  "executionTime": 0
}

Erro Assistido por LLM:

{
  "success": false,
  "error": "Timeout - LLM guidance needed",
  "question": "Session timed out. What should I do?",
  "questionType": "timeout_analysis",
  "canContinue": true,
  "context": { "sessionId": "...", "rawOutput": "..." }
}

Desenvolvimento

Compilação

npm run build

Modo de Desenvolvimento

npm run dev

Isso iniciará o TypeScript em modo de observação para desenvolvimento.

Notas Específicas da Plataforma

Windows

  • Usa cmd ou powershell como shell padrão
  • Alguns recursos de REPL podem se comportar de forma diferente
  • Tratamento de Sinais: Apenas SIGINT é suportado efetivamente. Ele é traduzido para um evento Ctrl+C, que pode interromper a maioria das ferramentas de linha de comando e encerrar REPLs como o do Node.js. SIGTSTP (Ctrl+Z) e SIGQUIT (Ctrl+\) não são suportados pelo console do Windows e não terão efeito.

macOS/Linux

  • Usa bash ou zsh como shell padrão
  • Suporte completo de recursos

Solução de Problemas

Problemas Comuns

  1. A criação de sessão falha: Verifique se o comando REPL necessário está instalado e acessível
  2. Comandos expiram consistentemente: Aumente o valor do timeout ou verifique a resposta do REPL
  3. REPL não encontrado: Garanta que o executável do REPL esteja no seu PATH

Problemas com a Interface Web

  1. Conflitos de porta: O servidor encontra automaticamente portas disponíveis a partir de 8023
  2. Terminal do navegador sem resposta: Verifique se o JavaScript está habilitado e tente atualizar
  3. URL da sessão não funciona: Verifique se a sessão ainda está ativa e se a porta está correta
  4. Problemas de tamanho do terminal: O terminal usa tamanho 132x43 para melhor compatibilidade com aplicativos

Problemas com Recuperação de Sessão

  1. Sessão travada: Use send_signal_to_session com SIGINT para interromper processos travados
  2. Padrão não funciona: Use set_session_ready com o padrão de prompt correto
  3. Comandos expiram: Tente wait_for_session para comandos lentos ou send_signal_to_session para interromper

Boas Práticas

Para Shells Complexos

  • Prompts personalizados: Use set_session_ready para especificar seu padrão de prompt
  • Ambientes aninhados: Use wait_for_session para ambientes que precisam de tempo para estabilizar
  • Processos travados: Use send_signal_to_session para interromper comandos de longa duração

Dicas de Performance

  • Aprendizado de sessão: Padrões aprendidos durante a assistência de LLM melhoram comandos subsequentes
  • Múltiplas sessões: Cada sessão aprende de forma independente

Informações de Depuração

Variáveis de Ambiente

  • REPL_MCP_DEBUG=1: Habilita registro de depuração detalhado para solução de problemas de performance e desenvolvimento

Habilite a depuração detalhada verificando o campo debugLogs nas respostas:

{
  "success": true,
  "output": "...",
  "debugLogs": [
    "2025-06-22T15:31:15.504Z: [DEBUG session_xxx] Prompt detected: true",
    "2025-06-22T15:31:15.505Z: [DEBUG session_xxx] Learned new prompt pattern: '∙'"
  ]
}

Contribuindo

Contribuições são bem-vindas! Os recursos assistidos por LLM facilitam a adição de suporte para novos ambientes de shell e tipos de REPL. Ao contribuir:

  1. Teste com diferentes shells: Garanta compatibilidade em bash, zsh e outros ambientes
  2. Considere variações de prompt: Teste com prompts e temas personalizados
  3. Atualize configurações: Adicione novas configurações predefinidas para setups comuns
  4. Documente padrões de LLM: Compartilhe padrões de prompt bem-sucedidos para outros

Licença

Licença MIT