Human-In-the-Loop MCP Server

Permite que assistentes de IA interajam com humanos por meio de diálogos GUI para entrada, escolhas e confirmações.

Documentação

Servidor MCP Human-In-the-Loop

Um Servidor de Protocolo de Contexto de Modelo (MCP) poderoso que permite que assistentes de IA como o Claude interajam com humanos por meio de diálogos GUI intuitivos. Este servidor preenche a lacuna entre processos de IA automatizados e a tomada de decisão humana, fornecendo ferramentas de entrada do usuário em tempo real, escolhas, confirmações e mecanismos de feedback.

demo

🚀 Recursos

💬 Ferramentas de Diálogo Interativo

Entrada de Texto: Obtenha texto, números ou outros dados dos usuários com validação
Múltipla Escolha: Apresente opções para seleções únicas ou múltiplas
Entrada Multilinha: Colete conteúdo de texto mais longo, código ou descrições detalhadas
Diálogos de Confirmação: Peça decisões de sim/não antes de prosseguir com ações
Mensagens de Informação: Exiba notificações, atualizações de status e resultados
Verificação de Saúde: Monitore o status do servidor e a disponibilidade da GUI

🎨 GUI Moderna Multiplataforma

Windows: Interface moderna estilo Windows 11 com bela estilização, efeitos de hover e design visual aprimorado
macOS: Experiência nativa do macOS com fontes SF Pro Display e gerenciamento adequado de janelas
Linux: GUI compatível com Ubuntu com estilização moderna e fontes do sistema

⚡ Recursos Avançados

Operação Não Bloqueante: Todos os diálogos são executados em threads separadas para evitar bloqueios
Proteção por Tempo Limite: Tempos limite configuráveis de 5 minutos evitam operações penduradas
Detecção de Plataforma: Otimização automática para cada sistema operacional
Design de UI Moderno: Interface bonita com animações suaves e efeitos de hover
Tratamento de Erros: Relatórios de erro abrangentes e recuperação graciosa
Navegação por Teclado: Suporte completo a atalhos de teclado (Enter/Escape)

📦 Instalação e Configuração

Instalação Rápida com uvx (Recomendado)

A maneira mais fácil de usar este servidor MCP é com uvx:

# Install and run directly
uvx hitl-mcp-server

# Or use the underscore version
uvx hitl_mcp_server

Instalação Manual

Instale a partir do PyPI:
```
pip install hitl-mcp-server
```
Execute o servidor:
```
hitl-mcp-server
# or
hitl_mcp_server
```

Instalação para Desenvolvimento

Clone o repositório:

git clone https://github.com/GongRzhe/Human-In-the-Loop-MCP-Server.git
cd Human-In-the-Loop-MCP-Server

Instale em modo de desenvolvimento:
```
pip install -e .
```

🔧 Configuração do Claude Desktop

Para usar este servidor com o Claude Desktop, adicione a seguinte configuração ao seu claude_desktop_config.json:

Usando uvx (Recomendado)

{
  "mcpServers": {
    "human-in-the-loop": {
      "command": "uvx",
      "args": ["hitl-mcp-server"]
    }
  }
}

Usando instalação via pip

{
  "mcpServers": {
    "human-in-the-loop": {
      "command": "hitl-mcp-server",
      "args": []
    }
  }
}

Locais do Arquivo de Configuração

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Nota Importante para Usuários de macOS

Nota: Você pode precisar permitir que o Python controle seu computador em Preferências do Sistema > Segurança e Privacidade > Acessibilidade para que os diálogos da GUI funcionem corretamente.

Após atualizar a configuração, reinicie o Claude Desktop para que as alterações tenham efeito.

🛠️ Ferramentas Disponíveis

1. `get_user_input`

Obtenha texto de linha única, números ou outros dados dos usuários.

Parâmetros:

title (str): Título da janela do diálogo
prompt (str): Texto da pergunta/solicitação
default_value (str): Valor pré-preenchido (opcional)
input_type (str): "text", "integer" ou "float" (padrão: "text")

Exemplo de Uso:

result = await get_user_input(
    title="Project Setup",
    prompt="Enter your project name:",
    default_value="my-project",
    input_type="text"
)

2. `get_user_choice`

Apresente múltiplas opções para seleção do usuário.

Parâmetros:

title (str): Título da janela do diálogo
prompt (str): Texto da pergunta/solicitação
choices (List[str]): Opções disponíveis
allow_multiple (bool): Permitir múltiplas seleções (padrão: false)

Exemplo de Uso:

result = await get_user_choice(
    title="Framework Selection",
    prompt="Choose your preferred framework:",
    choices=["React", "Vue", "Angular", "Svelte"],
    allow_multiple=False
)

3. `get_multiline_input`

Colete conteúdo de texto mais longo, código ou descrições detalhadas.

Parâmetros:

title (str): Título da janela do diálogo
prompt (str): Texto da pergunta/solicitação
default_value (str): Texto pré-preenchido (opcional)

Exemplo de Uso:

result = await get_multiline_input(
    title="Code Review",
    prompt="Please provide your detailed feedback:",
    default_value=""
)

4. `show_confirmation_dialog`

Peça confirmação de sim/não antes de prosseguir.

Parâmetros:

title (str): Título da janela do diálogo
message (str): Mensagem de confirmação

Exemplo de Uso:

result = await show_confirmation_dialog(
    title="Delete Confirmation",
    message="Are you sure you want to delete these 5 files? This action cannot be undone."
)

5. `show_info_message`

Exiba informações, notificações ou atualizações de status.

Parâmetros:

title (str): Título da janela do diálogo
message (str): Mensagem de informação

Exemplo de Uso:

result = await show_info_message(
    title="Process Complete",
    message="Successfully processed 1,247 records in 2.3 seconds!"
)

6. `health_check`

Verifique o status do servidor e a disponibilidade da GUI.

Exemplo de Uso:

status = await health_check()
# Returns detailed platform and functionality information

📋 Formato de Resposta

Todas as ferramentas retornam respostas JSON estruturadas:

{
    "success": true,
    "user_input": "User's response text",
    "cancelled": false,
    "platform": "windows",
    "input_type": "text"
}

Campos de Resposta Comuns:

success (bool): Se a operação foi concluída com sucesso
cancelled (bool): Se o usuário cancelou o diálogo
platform (str): Plataforma do sistema operacional
error (str): Mensagem de erro se a operação falhou

Campos Específicos da Ferramenta:

get_user_input: user_input, input_type
get_user_choice: selected_choice, selected_choices, allow_multiple
get_multiline_input: user_input, character_count, line_count
show_confirmation_dialog: confirmed, response
show_info_message: acknowledged

🧠 Melhores Práticas para Integração com IA

Quando Usar Ferramentas Human-In-the-Loop

Requisitos Ambíguos - Quando as instruções do usuário não estão claras
Pontos de Decisão - Quando você precisa da preferência do usuário entre alternativas válidas
Entrada Criativa - Para escolhas subjetivas como design ou estilo de conteúdo
Operações Sensíveis - Antes de executar ações potencialmente destrutivas
Informações Ausentes - Quando você precisa de detalhes específicos não fornecidos
Feedback de Qualidade - Para obter validação do usuário em resultados intermediários

Exemplos de Padrões de Integração

Operações com Arquivos

# Get target directory
location = await get_user_input(
    title="Backup Location",
    prompt="Enter backup directory path:",
    default_value="~/backups"
)

# Choose backup type
backup_type = await get_user_choice(
    title="Backup Options",
    prompt="Select backup type:",
    choices=["Full Backup", "Incremental", "Differential"]
)

# Confirm before proceeding
confirmed = await show_confirmation_dialog(
    title="Confirm Backup",
    message=f"Create {backup_type['selected_choice']} backup to {location['user_input']}?"
)

if confirmed['confirmed']:
    # Perform backup
    await show_info_message("Success", "Backup completed successfully!")

Criação de Conteúdo

# Get content requirements
requirements = await get_multiline_input(
    title="Content Requirements",
    prompt="Describe your content requirements in detail:"
)

# Choose tone and style
tone = await get_user_choice(
    title="Content Style",
    prompt="Select desired tone:",
    choices=["Professional", "Casual", "Friendly", "Technical"]
)

# Generate and show results
# ... content generation logic ...
await show_info_message("Content Ready", "Your content has been generated successfully!")

🔍 Solução de Problemas

Problemas Comuns

GUI Não Aparece

Verifique se você está executando em um ambiente de desktop (não servidor headless)
Verifique se o tkinter está instalado: python -c "import tkinter"
Execute a verificação de saúde: ferramenta health_check() para diagnosticar problemas

Erros de Permissão (macOS)

Conceda permissões de acessibilidade em Preferências do Sistema > Segurança e Privacidade > Acessibilidade
Permita que o Python controle seu computador
Reinicie o terminal após conceder as permissões

Erros de Importação

Certifique-se de que o pacote está instalado: pip install hitl-mcp-server
Verifique a compatibilidade da versão do Python (>=3.8 necessário)
Verifique a ativação do ambiente virtual, se estiver usando um

Problemas de Integração com o Claude Desktop

Verifique a sintaxe e o local do arquivo de configuração
Reinicie o Claude Desktop após alterações na configuração
Verifique se o uvx está instalado: pip install uvx
Teste o servidor manualmente: uvx hitl-mcp-server

Tempo Limite do Diálogo

O tempo limite padrão é de 5 minutos (300 segundos)
Os diálogos retornarão com cancelled=true se o usuário não responder
Certifique-se de que o usuário esteja presente quando os diálogos forem acionados

Modo de Depuração

Ative o registro detalhado executando o servidor com a variável de ambiente:

HITL_DEBUG=1 uvx hitl-mcp-server

🏗️ Desenvolvimento

Estrutura do Projeto

Human-In-the-Loop-MCP-Server/
├── human_loop_server.py       # Main server implementation
├── pyproject.toml            # Package configuration
├── README.md                 # Documentation
├── LICENSE                   # MIT License
├── .gitignore               # Git ignore rules
└── demo.gif                 # Demo animation

Contribuindo

Faça um fork do repositório
Crie um branch de recurso: git checkout -b feature-name
Faça suas alterações com testes adequados
Siga as diretrizes de estilo de código (Black, Ruff)
Adicione dicas de tipo e docstrings
Envie um pull request com descrição detalhada

Qualidade do Código

Formatação: Black (comprimento de linha: 88)
Linting: Ruff com conjunto abrangente de regras
Verificação de Tipos: MyPy com configuração estrita
Testes: Pytest para testes unitários e de integração

🌍 Suporte a Plataformas

Windows

Windows 10/11 com estilização de UI moderna
Design visual aprimorado com efeitos de hover
Integração de fontes Segoe UI e Consolas
Suporte completo à navegação por teclado

macOS

Experiência nativa do macOS
Fontes do sistema SF Pro Display
Gerenciamento adequado de janelas e foco
Tratamento de permissões de acessibilidade

Linux

Compatível com Ubuntu/Debian
Estilização moderna com fontes do sistema
Suporte GUI entre distribuições
Requisitos mínimos de dependências

📄 Licença

Este projeto está licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

🤝 Agradecimentos

Construído com o framework FastMCP
Usa Pydantic para validação de dados
GUI multiplataforma alimentada por tkinter
Inspirado pela necessidade de colaboração humano-IA

🔗 Links

Pacote PyPI: https://pypi.org/project/hitl-mcp-server/
Repositório: https://github.com/GongRzhe/Human-In-the-Loop-MCP-Server
Issues: Relate bugs ou solicite recursos
Protocolo MCP: Aprenda sobre o Protocolo de Contexto de Modelo

📊 Estatísticas de Uso

Multiplataforma: Windows, macOS, Linux
Suporte a Python: 3.8, 3.9, 3.10, 3.11, 3.12+
Framework GUI: tkinter (integrado ao Python)
Segurança de Threads: Suporte completo a operações concorrentes
Tempo de Resposta: < 100ms de inicialização do diálogo
Uso de Memória: < 50MB em operação típica

Feito com ❤️ para a comunidade de IA - Unindo humanos e IA por meio de interação intuitiva

Human-In-the-Loop MCP Server

Documentação

Servidor MCP Human-In-the-Loop

🚀 Recursos

💬 Ferramentas de Diálogo Interativo

🎨 GUI Moderna Multiplataforma

⚡ Recursos Avançados

📦 Instalação e Configuração

Instalação Rápida com uvx (Recomendado)

Instalação Manual

Instalação para Desenvolvimento

🔧 Configuração do Claude Desktop

Usando uvx (Recomendado)

Usando instalação via pip

Locais do Arquivo de Configuração

Nota Importante para Usuários de macOS

🛠️ Ferramentas Disponíveis

1. get_user_input

2. get_user_choice

3. get_multiline_input

4. show_confirmation_dialog

5. show_info_message

6. health_check

📋 Formato de Resposta

🧠 Melhores Práticas para Integração com IA

Quando Usar Ferramentas Human-In-the-Loop

Exemplos de Padrões de Integração

Operações com Arquivos

Criação de Conteúdo

🔍 Solução de Problemas

Problemas Comuns

Modo de Depuração

🏗️ Desenvolvimento

Estrutura do Projeto

Contribuindo

Qualidade do Código

🌍 Suporte a Plataformas

Windows

macOS

Linux

📄 Licença

🤝 Agradecimentos

🔗 Links

📊 Estatísticas de Uso

1. `get_user_input`

2. `get_user_choice`

3. `get_multiline_input`

4. `show_confirmation_dialog`

5. `show_info_message`

6. `health_check`