interactive-mcp

interactive-mcp

Um servidor MCP implementado em Node.js/TypeScript, facilitando a comunicação interativa entre LLMs e usuários. Nota: Este servidor foi projetado para ser executado localmente junto ao cliente MCP (ex.: Claude Desktop, VS Code), pois precisa de acesso direto ao sistema operacional do usuário para exibir notificações e prompts de linha de comando.

(Nota: Este projeto está em estágio inicial.)

Quer uma visão geral rápida? Confira o post introdutório no blog: Impeça seu Assistente de IA de Adivinhar — Apresentando o interactive-mcp

Vídeo de Demonstração

Ferramentas

Este servidor expõe as seguintes ferramentas por meio do Model Context Protocol (MCP):

• request_user_input: Pergunta ao usuário e retorna a resposta. Pode exibir opções predefinidas.
• message_complete_notification: Envia uma notificação simples do sistema operacional.
• start_intensive_chat: Inicia uma sessão de chat persistente na linha de comando.
• ask_intensive_chat: Faz uma pergunta dentro de uma sessão de chat intensiva ativa.
• stop_intensive_chat: Encerra uma sessão de chat intensiva ativa.

Demonstração

Aqui estão demonstrações dos recursos interativos:

Pergunta Normal	Notificação de Conclusão

Início do Chat Intensivo	Fim do Chat Intensivo

Cenários de Uso

Este servidor é ideal para cenários em que um LLM precisa interagir diretamente com o usuário em sua máquina local, como:

• Processos interativos de instalação ou configuração.
• Coleta de feedback durante a geração ou modificação de código.
• Esclarecimento de instruções ou confirmação de ações em programação em par.
• Qualquer fluxo de trabalho que exija entrada ou confirmação do usuário durante a operação do LLM.

Configuração do Cliente

Esta seção explica como configurar clientes MCP para usar o servidor interactive-mcp.

Por padrão, os prompts do usuário expiram após 30 segundos. Você pode personalizar opções do servidor, como tempo limite ou ferramentas desabilitadas, adicionando flags de linha de comando diretamente ao array args ao configurar seu cliente.

Certifique-se de ter o comando npx disponível.

Uso com Claude Desktop / Cursor

Adicione a seguinte configuração mínima ao seu claude_desktop_config.json (Claude Desktop) ou mcp.json (Cursor):

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

Com versão específica

{
  "mcpServers": {
    "interactive": {
      "command": "npx",
      "args": ["-y", "interactive-mcp@1.9.0"]
    }
  }
}

Exemplo com tempo limite personalizado (30s):

{
  "mcpServers": {
    "interactive": {
      "command": "npx",
      "args": ["-y", "interactive-mcp", "-t", "30"]
    }
  }
}

Uso com VS Code

Adicione a seguinte configuração mínima ao seu arquivo de Configurações do Usuário (JSON) ou .vscode/mcp.json:

{
  "mcp": {
    "servers": {
      "interactive-mcp": {
        "command": "npx",
        "args": ["-y", "interactive-mcp"]
      }
    }
  }
}

Recomendações para macOS

Para uma experiência mais fluida no macOS usando o Terminal.app padrão, considere esta configuração de perfil:

• (Aba Shell): Em "Quando o shell sair" (Terminal > Configurações > Perfis > [Seu Perfil] > Shell), selecione "Fechar se o shell sair corretamente" ou "Fechar a janela". Isso ajuda a gerenciar janelas quando o servidor MCP inicia e para.

Configuração de Desenvolvimento

Esta seção é principalmente para desenvolvedores que desejam modificar ou contribuir com o servidor. Se você apenas deseja usar o servidor com um cliente MCP, consulte a seção "Configuração do Cliente" acima.

Pré-requisitos

• Node.js: Verifique package.json para compatibilidade de versão.
• pnpm: Usado para gerenciamento de pacotes. Instale via npm install -g pnpm após instalar o Node.js.

Instalação (Desenvolvedores)

1. Clone o repositório:

   git clone https://github.com/ttommyth/interactive-mcp.git
   cd interactive-mcp
   

2. Instale as dependências:

   pnpm install
   

Executando o Aplicativo (Desenvolvedores)

pnpm start

Opções de Linha de Comando

O servidor interactive-mcp aceita as seguintes opções de linha de comando. Elas normalmente devem ser configuradas nas configurações JSON do seu cliente MCP, adicionando-as diretamente ao array args (veja os exemplos em "Configuração do Cliente").

Opção	Alias	Descrição
--timeout	-t	Define o tempo limite padrão (em segundos) para prompts de entrada do usuário. O padrão é 30 segundos.
--disable-tools	-d	Desabilita ferramentas ou grupos específicos (lista separada por vírgulas). Impede que o servidor os anuncie ou registre. Opções: request_user_input, message_complete_notification, intensive_chat.

Exemplo: Definindo múltiplas opções no array args da configuração do cliente:

// Example combining options in client config's "args":
"args": [
  "-y", "interactive-mcp",
  "-t", "30", // Set timeout to 30 seconds
  "--disable-tools", "message_complete_notification,intensive_chat" // Disable notifications and intensive chat
]

Comandos de Desenvolvimento

• Build: pnpm build
• Lint: pnpm lint
• Format: pnpm format

Princípios Orientadores para Interação

Ao interagir com este servidor MCP (ex.: como cliente LLM), siga os seguintes princípios para garantir clareza e reduzir mudanças inesperadas:

• Priorize a Interação: Utilize as ferramentas MCP fornecidas (request_user_input, start_intensive_chat, etc.) com frequência para interagir com o usuário.
• Busque Esclarecimento: Se requisitos, instruções ou contexto não estiverem claros, sempre faça perguntas de esclarecimento antes de prosseguir. Não faça suposições.
• Confirme Ações: Antes de realizar ações significativas (como modificar arquivos, executar comandos complexos ou tomar decisões de arquitetura), confirme o plano com o usuário.
• Ofereça Opções: Sempre que possível, apresente ao usuário opções predefinidas por meio das ferramentas MCP para facilitar decisões rápidas.

Você pode fornecer estas instruções a um cliente LLM assim:

# Interaction

- Please use the interactive MCP tools
- Please provide options to interactive MCP if possible

# Reduce Unexpected Changes

- Do not make assumption.
- Ask more questions before executing, until you think the requirement is clear enough.

Contribuição

Contribuições são bem-vindas! Siga as práticas padrão de desenvolvimento. (Mais detalhes podem ser adicionados posteriormente).

Licença

MIT (Consulte o arquivo LICENSE para obter detalhes - se aplicável, ou especifique a licença diretamente).