Human-In-the-Loop MCP Server

Permite que los asistentes de IA interactúen con humanos a través de diálogos GUI para entrada, opciones y confirmaciones.

GitHub

163

Prueba este MCPPatrocinado

Documentación

Human-In-the-Loop MCP Server

Un potente Servidor de Protocolo de Contexto de Modelo (MCP) que permite a asistentes de IA como Claude interactuar con humanos a través de diálogos GUI intuitivos. Este servidor une la brecha entre los procesos automatizados de IA y la toma de decisiones humana al proporcionar herramientas de entrada de usuario en tiempo real, opciones, confirmaciones y mecanismos de retroalimentación.

demo

🚀 Características

💬 Herramientas de Diálogo Interactivo

Entrada de Texto: Obtenga texto, números u otros datos de los usuarios con validación
Opción Múltiple: Presente opciones para selecciones únicas o múltiples
Entrada Multilínea: Recoja contenido de texto más largo, código o descripciones detalladas
Diálogos de Confirmación: Solicite decisiones de sí/no antes de proceder con acciones
Mensajes de Información: Muestre notificaciones, actualizaciones de estado y resultados
Verificación de Salud: Monitoree el estado del servidor y la disponibilidad de la GUI

🎨 GUI Moderna Multiplataforma

Windows: Interfaz moderna estilo Windows 11 con estilos hermosos, efectos de desplazamiento y diseño visual mejorado
macOS: Experiencia nativa de macOS con fuentes SF Pro Display y gestión adecuada de ventanas
Linux: GUI compatible con Ubuntu con estilos modernos y fuentes del sistema

⚡ Características Avanzadas

Operación No Bloqueante: Todos los diálogos se ejecutan en hilos separados para evitar bloqueos
Protección de Tiempo de Espera: Tiempos de espera configurables de 5 minutos previenen operaciones colgadas
Detección de Plataforma: Optimización automática para cada sistema operativo
Diseño de UI Moderno: Interfaz hermosa con animaciones suaves y efectos de desplazamiento
Manejo de Errores: Reporte integral de errores y recuperación elegante
Navegación por Teclado: Soporte completo de atajos de teclado (Enter/Escape)

📦 Instalación y Configuración

Instalación Rápida con uvx (Recomendado)

La forma más fácil de usar este servidor MCP es con uvx:

# Install and run directly
uvx hitl-mcp-server

# Or use the underscore version
uvx hitl_mcp_server

Instalación Manual

Instale desde PyPI:
```
pip install hitl-mcp-server
```
Ejecute el servidor:
```
hitl-mcp-server
# or
hitl_mcp_server
```

Instalación para Desarrollo

Clone el repositorio:

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

Instale en modo de desarrollo:
```
pip install -e .
```

🔧 Configuración de Claude Desktop

Para usar este servidor con Claude Desktop, agregue la siguiente configuración a su claude_desktop_config.json:

Usando uvx (Recomendado)

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

Usando instalación con pip

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

Ubicaciones del Archivo de Configuración

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 Usuarios de macOS

Nota: Es posible que necesite permitir que Python controle su computadora en Preferencias del Sistema > Seguridad y Privacidad > Accesibilidad para que los diálogos GUI funcionen correctamente.

Después de actualizar la configuración, reinicie Claude Desktop para que los cambios surtan efecto.

🛠️ Herramientas Disponibles

1. `get_user_input`

Obtenga texto de una sola línea, números u otros datos de los usuarios.

Parámetros:

title (str): Título de la ventana del diálogo
prompt (str): Texto de la pregunta/solicitud
default_value (str): Valor prellenado (opcional)
input_type (str): "text", "integer" o "float" (predeterminado: "text")

Ejemplo 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`

Presente múltiples opciones para la selección del usuario.

Parámetros:

title (str): Título de la ventana del diálogo
prompt (str): Texto de la pregunta/solicitud
choices (List[str]): Opciones disponibles
allow_multiple (bool): Permitir selecciones múltiples (predeterminado: false)

Ejemplo 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`

Recoja contenido de texto más largo, código o descripciones detalladas.

Parámetros:

title (str): Título de la ventana del diálogo
prompt (str): Texto de la pregunta/solicitud
default_value (str): Texto prellenado (opcional)

Ejemplo de Uso:

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

4. `show_confirmation_dialog`

Solicite confirmación de sí/no antes de proceder.

Parámetros:

title (str): Título de la ventana del diálogo
message (str): Mensaje de confirmación

Ejemplo 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`

Muestre información, notificaciones o actualizaciones de estado.

Parámetros:

title (str): Título de la ventana del diálogo
message (str): Mensaje de información

Ejemplo de Uso:

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

6. `health_check`

Verifique el estado del servidor y la disponibilidad de la GUI.

Ejemplo de Uso:

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

📋 Formato de Respuesta

Todas las herramientas devuelven respuestas JSON estructuradas:

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

Campos de Respuesta Comunes:

success (bool): Si la operación se completó exitosamente
cancelled (bool): Si el usuario canceló el diálogo
platform (str): Plataforma del sistema operativo
error (str): Mensaje de error si la operación falló

Campos Específicos de Herramientas:

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

🧠 Mejores Prácticas para Integración con IA

Cuándo Usar Herramientas Human-In-the-Loop

Requisitos Ambiguos - Cuando las instrucciones del usuario no son claras
Puntos de Decisión - Cuando necesita la preferencia del usuario entre alternativas válidas
Entrada Creativa - Para elecciones subjetivas como diseño o estilo de contenido
Operaciones Sensibles - Antes de ejecutar acciones potencialmente destructivas
Información Faltante - Cuando necesita detalles específicos no proporcionados
Retroalimentación de Calidad - Para obtener validación del usuario sobre resultados intermedios

Patrones de Integración de Ejemplo

Operaciones de Archivos

# 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!")

Creación de Contenido

# 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!")

🔍 Solución de Problemas

Problemas Comunes

La GUI No Aparece

Verifique que está ejecutando en un entorno de escritorio (no servidor sin cabeza)
Compruebe si tkinter está instalado: python -c "import tkinter"
Ejecute la verificación de salud: herramienta health_check() para diagnosticar problemas

Errores de Permisos (macOS)

Otorgue permisos de accesibilidad en Preferencias del Sistema > Seguridad y Privacidad > Accesibilidad
Permita que Python controle su computadora
Reinicie la terminal después de otorgar permisos

Errores de Importación

Asegúrese de que el paquete esté instalado: pip install hitl-mcp-server
Verifique la compatibilidad de la versión de Python (se requiere >=3.8)
Verifique la activación del entorno virtual si está usando uno

Problemas de Integración con Claude Desktop

Verifique la sintaxis y ubicación del archivo de configuración
Reinicie Claude Desktop después de los cambios de configuración
Verifique que uvx esté instalado: pip install uvx
Pruebe el servidor manualmente: uvx hitl-mcp-server

Tiempo de Espera del Diálogo

El tiempo de espera predeterminado es de 5 minutos (300 segundos)
Los diálogos devolverán cancelled=true si el usuario no responde
Asegúrese de que el usuario esté presente cuando se activen los diálogos

Modo de Depuración

Habilite el registro detallado ejecutando el servidor con la variable de entorno:

HITL_DEBUG=1 uvx hitl-mcp-server

🏗️ Desarrollo

Estructura del Proyecto

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

Contribuciones

Haga un fork del repositorio
Cree una rama de características: git checkout -b feature-name
Haga sus cambios con pruebas adecuadas
Siga las pautas de estilo de código (Black, Ruff)
Agregue sugerencias de tipo y docstrings
Envíe una solicitud de extracción con descripción detallada

Calidad del Código

Formato: Black (longitud de línea: 88)
Linting: Ruff con conjunto integral de reglas
Verificación de Tipos: MyPy con configuración estricta
Pruebas: Pytest para pruebas unitarias y de integración

🌍 Soporte de Plataformas

Windows

Windows 10/11 con estilos de UI modernos
Diseño visual mejorado con efectos de desplazamiento
Integración de fuentes Segoe UI y Consolas
Soporte completo de navegación por teclado

macOS

Experiencia nativa de macOS
Fuentes del sistema SF Pro Display
Gestión adecuada de ventanas y enfoque
Manejo de permisos de accesibilidad

Linux

Compatible con Ubuntu/Debian
Estilos modernos con fuentes del sistema
Soporte GUI entre distribuciones
Requisitos mínimos de dependencias

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulte el archivo LICENSE para más detalles.

🤝 Agradecimientos

Construido con el framework FastMCP
Usa Pydantic para validación de datos
GUI multiplataforma impulsada por tkinter
Inspirado por la necesidad de colaboración humano-IA

🔗 Enlaces

Paquete PyPI: https://pypi.org/project/hitl-mcp-server/
Repositorio: https://github.com/GongRzhe/Human-In-the-Loop-MCP-Server
Problemas: Reporte errores o solicite características
Protocolo MCP: Aprenda sobre el Protocolo de Contexto de Modelo

📊 Estadísticas de Uso

Multiplataforma: Windows, macOS, Linux
Soporte de Python: 3.8, 3.9, 3.10, 3.11, 3.12+
Framework GUI: tkinter (integrado con Python)
Seguridad de Hilos: Soporte completo de operaciones concurrentes
Tiempo de Respuesta: < 100ms de inicialización de diálogo
Uso de Memoria: < 50MB de operación típica

Hecho con ❤️ para la comunidad de IA - Uniendo humanos e IA a través de interacción intuitiva

Human-In-the-Loop MCP Server

Documentación

Human-In-the-Loop MCP Server

🚀 Características

💬 Herramientas de Diálogo Interactivo

🎨 GUI Moderna Multiplataforma

⚡ Características Avanzadas

📦 Instalación y Configuración

Instalación Rápida con uvx (Recomendado)

Instalación Manual

Instalación para Desarrollo

🔧 Configuración de Claude Desktop

Usando uvx (Recomendado)

Usando instalación con pip

Ubicaciones del Archivo de Configuración

Nota Importante para Usuarios de macOS

🛠️ Herramientas Disponibles

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 Respuesta

🧠 Mejores Prácticas para Integración con IA

Cuándo Usar Herramientas Human-In-the-Loop

Patrones de Integración de Ejemplo

Operaciones de Archivos

Creación de Contenido

🔍 Solución de Problemas

Problemas Comunes

Modo de Depuración

🏗️ Desarrollo

Estructura del Proyecto

Contribuciones

Calidad del Código

🌍 Soporte de Plataformas

Windows

macOS

Linux

📄 Licencia

🤝 Agradecimientos

🔗 Enlaces

📊 Estadí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`