Servidor de terminales MCP

Un servidor FastAPI liviano que puede ejecutarse como un servicio de Windows y expone un punto final para ejecutar comandos de shell y transmitir su salida.

Características

Ejecutar como un servicio de Windows o en modo de depuración
Ejecutar comandos de shell y transmitir su salida en tiempo real
Autenticación de clave API
Limitación de velocidad
Configurable mediante variables de entorno o archivo de configuración
Manejo y registro de errores robustos
Reinicio automático del proceso en caso de fallo

Instalación

Prerrequisitos

Sistema operativo Windows
Python 3.7 o superior
Privilegios de administrador (para la instalación del servicio)

Pasos de instalación

Clona este repositorio o descarga el código fuente
Abra PowerShell como administrador
Navegar al directorio del proyecto
Ejecute el script de instalación:

.\install_service.ps1

Esto hará lo siguiente:

Instalar las dependencias de Python necesarias
Generar una clave API aleatoria (o utilizar la que proporciones)
Crear un archivo de configuración
Instalar e iniciar el servicio de Windows

Opciones de instalación

Puede personalizar la instalación con los siguientes parámetros:

.\install_service.ps1 -ApiKey "your-api-key" -Port 8080 -Host "127.0.0.1" -LogLevel "debug"

Parámetros disponibles:

-ApiKey : Clave API personalizada para autenticación
-Port : Número de puerto para el servidor (predeterminado: 8000)
-Host : Dirección de host a la que vincularse (predeterminado: 0.0.0.0)
-LogLevel : Nivel de registro (depuración, información, advertencia, error, crítico)
-ConfigFile : Ruta a un archivo de configuración personalizado

Configuración

El servidor se puede configurar a través de:

Variables de entorno
Archivo de configuración (config.json)
Argumentos de la línea de comandos durante la instalación

Archivo de configuración

Se proporciona un archivo de configuración de ejemplo ( config.json.sample ). Puede copiarlo a config.json y modificarlo:

{
    "host": "0.0.0.0",
    "port": 8000,
    "log_level": "info",
    "log_file": "mcp_terminal_server.log",
    "max_log_size_mb": 10,
    "log_backup_count": 5,
    "restart_on_failure": true,
    "max_restart_attempts": 5,
    "restart_delay_seconds": 10,
    "shutdown_timeout_seconds": 30,
    "working_directory": null
}

Variables de entorno

También puedes configurar el servidor utilizando variables de entorno:

MCP_TERMINAL_API_KEY : Clave API para autenticación
MCP_HOST : Dirección de host a la que vincularse
MCP_PORT : Número de puerto del servidor
MCP_LOG_LEVEL : Nivel de registro
MCP_LOG_FILE : Ruta al archivo de registro
MCP_MAX_LOG_SIZE_MB : Tamaño máximo del archivo de registro en MB
MCP_LOG_BACKUP_COUNT : Número de archivos de respaldo de registro a conservar
MCP_RESTART_ON_FAILURE : Si se debe reiniciar el servidor en caso de falla
MCP_MAX_RESTART_ATTEMPTS : Número máximo de intentos de reinicio
MCP_RESTART_DELAY_SECONDS : Retraso entre intentos de reinicio
MCP_SHUTDOWN_TIMEOUT_SECONDS : Tiempo de espera para un apagado ordenado
MCP_WORKING_DIRECTORY : Directorio de trabajo del servidor

Gestión de servicios

Comandos de servicio

El servicio se puede gestionar mediante los siguientes comandos:

# Install the service
python service.py install

# Start the service
python service.py start

# Stop the service
python service.py stop

# Restart the service
python service.py restart

# Remove the service
python service.py remove

# Update the service configuration
python service.py update

# Run in debug mode (not as a service)
python service.py debug

Registros

Los registros se almacenan en el archivo de registro configurado (predeterminado: mcp_terminal_server.log ). Los registros incluyen:

Eventos de inicio/parada de servicio
Ejecución de comandos
Errores y advertencias
Resultados del control de salud

Uso de la API

Cliente de prueba

Se proporciona un cliente de prueba robusto para interactuar con el servidor con las siguientes características:

Argumentos de línea de comandos para una mejor usabilidad
Compatibilidad con autenticación de clave API
Salida en color para una mejor legibilidad.
Soporte para guardar la salida en un archivo
Manejo y registro de errores robustos
Modo interactivo con historial de comandos
Funcionalidad de comprobación del estado del servidor

Uso básico

# Run a command
python test_client.py -c "dir" -k "your-api-key"

# Check server health
python test_client.py --health

# Interactive mode
python test_client.py -k "your-api-key"

# Save output to a file
python test_client.py -c "systeminfo" --save-output output.txt

# Specify server URL
python test_client.py -s "http://example.com:8000" -c "dir"

# Enable verbose output
python test_client.py -v -c "dir"

# Show version
python test_client.py --version

Archivo de configuración

El cliente de prueba se puede configurar mediante un archivo de configuración JSON. Cree un archivo client_config.json basado en el ejemplo proporcionado:

{
    "server_url": "http://localhost:8000",
    "api_key": "your-api-key-here",
    "timeout": 60,
    "verbose": false
}

Luego úsalo con:

python test_client.py --config client_config.json

Variables de entorno

El cliente de prueba también admite la configuración a través de variables de entorno:

MCP_TERMINAL_API_KEY : Clave API para autenticación
MCP_TERMINAL_SERVER_URL : URL del servidor

Puntos finales de API

POST /run : Ejecutar un comando
- Requiere clave API en el encabezado X-API-Key
- Cuerpo de la solicitud: {"command": "your command"}
- Devuelve una respuesta de transmisión con salida de comando
GET /health : Verificar el estado del servidor
- Devuelve {"status": "healthy", "active_sessions": 0}

Consideraciones de seguridad

Cambie siempre la clave API predeterminada en producción
Restrinja el host a 127.0.0.1 si el servidor solo debe ser accesible localmente
Considere usar HTTPS en producción
El servidor bloquea comandos potencialmente peligrosos, pero pueden ser necesarias medidas de seguridad adicionales

Solución de problemas

Compruebe el archivo de registro para ver si hay errores
Ejecute en modo de depuración para ver la salida de la consola: python service.py debug
Verifique que el servicio se esté ejecutando: Get-Service -Name "MCP_Terminal_Server"
Compruebe el Visor de eventos de Windows para detectar errores relacionados con el servicio

Licencia

Instituto Tecnológico de Massachusetts (MIT)

MCP Terminal Server

Integrations