Serial Web Terminal MCP

Un servidor Model Context Protocol que brinda a los asistentes de codificación con IA (Claude Code, Cursor, Windsurf, etc.) la capacidad de interactuar con dispositivos de puerto serie.

Los agentes de IA pueden conectarse a dispositivos serie, enviar comandos y capturar la salida, mientras los usuarios observan todo el proceso en tiempo real a través de un terminal basado en navegador.

✨ Características

• 🔌 Conexión Serie — Conéctese a puertos COM, /dev/ttyUSB*, /dev/ttyS*, etc. con inicio de sesión automático

• 🖥️ Terminal Web — Terminal xterm.js en navegador que muestra E/S serie en tiempo real (como Xshell)

• 🤖 Servidor MCP — Integración nativa de herramientas; los agentes de IA llaman directamente mediante el protocolo MCP

• 📝 Registros con Marca de Tiempo — Cada línea se registra con marca de tiempo, rotación diaria, coincide exactamente con la visualización del terminal

• ⌨️ Bidireccional — La IA envía comandos + el usuario puede escribir manualmente en el terminal del navegador

• 🌐 Inicio de Sesión Multilingüe — Detecta automáticamente los mensajes de inicio de sesión/contraseña en inglés, chino y japonés

• ⏱️ Esperar y Enviar — Espera una salida específica y luego envía datos inmediatamente (p. ej., ventanas de contraseña de uboot)

• 🛡️ Recuperación por Tiempo de Espera — Ctrl+C automático en caso de tiempo de espera, sin sesiones colgadas

📦 Instalación

pip install mcp pyserial aiohttp

O desde los requisitos:

pip install -r requirements.txt

🚀 Inicio Rápido

1. Configure su cliente de IA

Claude Code (.mcp.json en la raíz del proyecto o ~/.claude/claude_config.json):

{
  "mcpServers": {
    "serial-terminal": {
      "command": "python",
      "args": ["/path/to/serial_mcp_server.py"]
    }
  }
}

Cursor (Configuración → MCP → Añadir Servidor):

{
  "mcpServers": {
    "serial-terminal": {
      "command": "python",
      "args": ["/path/to/serial_mcp_server.py"]
    }
  }
}

Consulte examples/ para archivos de configuración listos para usar.

2. Hable con su asistente de IA

> List available serial ports
AI: [calls serial_list_ports] → Found COM3, COM4...

> Connect to COM3, username admin, password ****
AI: [calls serial_connect(port="COM3", login_user="admin", login_pass="****")]
    → Serial connected, Web terminal: http://localhost:8080

> Run uname -a
AI: [calls serial_send(command="uname -a")]
    → Linux device 4.19.246 aarch64 GNU/Linux

Abra http://localhost:8080 en su navegador para ver las operaciones serie de la IA en tiempo real.

🔧 Herramientas MCP

serial_connect

Conecta a un dispositivo serie con inicio de sesión automático opcional.

serial_send

Envía un comando shell y captura la salida.

serial_wait_send

Espera una cadena específica en la salida serie, luego envía datos inmediatamente. Ideal para:

• Entrar en uboot durante un reinicio (ventana de contraseña de 3 segundos)

• Responder a mensajes de inicio de sesión

• Cualquier automatización de "esperar X, luego enviar Y"

🖥️ Uso Independiente (sin MCP)

serial_web.py puede ejecutarse de forma independiente mediante API HTTP:

# Start with auto-login
python serial_web.py --port COM3 --baud 115200 \
  --login-user admin --login-pass secret \
  --init-cmd "unset TMOUT"

# List available ports
python serial_web.py --list

API HTTP

# Send a command
curl -s -X POST http://localhost:8080/api/send \
     -H "Content-Type: application/json" \
     -d '{"command":"ls /","timeout":5}'

# Send raw data (Ctrl+C)
curl -s -X POST http://localhost:8080/api/raw \
     -H "Content-Type: application/json" \
     -d '{"data":"\x03"}'

# Wait-and-send
curl -s -X POST http://localhost:8080/api/wait-send \
     -H "Content-Type: application/json" \
     -d '{"wait_for":"login:","send_data":"admin","timeout":30}'

# Check status
curl -s http://localhost:8080/api/status

# Get logs
curl -s "http://localhost:8080/api/log?lines=50"

Argumentos de CLI

📝 Formato de Registro

Los registros se guardan en logs/serial_YYYYMMDD.log (rotación diaria):

2026-08-06 15:32:22  device # uname -a
2026-08-06 15:32:22  Linux device 4.19.246 aarch64 GNU/Linux
2026-08-06 15:32:23  device # cat /proc/cpuinfo | head -5
2026-08-06 15:32:23  processor	: 0
2026-08-06 15:32:23  >>> 自动登录流程完成

• Salida del terminal: marca de tiempo contenido (extraída del búfer de xterm.js — coincide exactamente con la visualización del navegador)

• Eventos del sistema: marca de tiempo >>> mensaje (inicio de sesión, arranque, etc.)

Fidelidad de las líneas del registro:

• Sin división por ajuste — las líneas con ajuste suave del terminal (ajuste de 80 columnas) se fusionan de nuevo en una sola línea lógica

• Consciente de barras de progreso — las secuencias de sobrescritura \r (10%\r20%\r30%) se colapsan al estado visible final (30%)

• Consciente de retroceso — las ediciones manuales con retroceso se registran como la línea final editada

• Cada línea siempre lleva un prefijo de marca de tiempo

🏗️ Arquitectura

AI Agent (Claude Code / Cursor / ...)
  └─ MCP Protocol (stdio)
      └─ serial_mcp_server.py
          └─ HTTP API
              └─ serial_web.py (aiohttp)
                  ├─ Serial Port (pyserial)
                  ├─ Web Terminal (xterm.js + WebSocket)
                  └─ Log Recording

Browser
  └─ http://localhost:8080
      ├─ xterm.js terminal (real-time serial data)
      └─ Log panel (timestamped logs)

📁 Estructura del Proyecto

serial-web-terminal/
├── serial_web.py              # Core: Web terminal + HTTP API
├── serial_mcp_server.py       # MCP Server (wraps HTTP API)
├── tests/
│   └── test_regression.py     # Regression test suite (68 tests)
├── examples/
│   ├── claude-code.json       # Claude Code MCP config
│   └── cursor.json            # Cursor MCP config
├── requirements.txt
├── LICENSE
└── README.md

🧪 Pruebas

Ejecute el conjunto de pruebas de regresión (no requiere dispositivo serie físico):

python tests/test_regression.py -v

Las pruebas cubren:

• Limpieza de salida (eliminación de ANSI, eliminación de eco, eliminación de mensajes)

• Detección de mensajes (mensajes de shell, mensajes conocidos)

• Almacenamiento en búfer de líneas de registro (manejo de retroceso, líneas parciales, limpieza ANSI)

• Detección de palabras clave de inicio de sesión automático (inglés, chino, japonés)

• Envío/recepción de comandos (serie simulada, tiempo de espera, recuperación con Ctrl+C)

• Esperar y enviar (coincidencia inmediata, coincidencia dinámica, tiempo de espera, disparador)

• Estructura de página HTML (sin IDs duplicados, elementos requeridos)

• Registro de herramientas del servidor MCP

• Puntos finales de la API HTTP (estado, envío, en bruto, registro — manejo de errores)

• Seguridad (sin credenciales codificadas, cobertura de .gitignore)

🌐 Inicio de Sesión Automático

El flujo de inicio de sesión automático admite mensajes en varios idiomas:

Flujo de inicio de sesión:

1. Enviar Enter para despertar el terminal

2. Detectar mensaje login: → enviar nombre de usuario

3. Detectar mensaje Password: → enviar contraseña

4. Esperar mensaje de shell

5. Ejecutar stty cols 200 (terminal ancho, evita el ajuste de 80 columnas)

6. Ejecutar --init-cmd (por defecto: unset TMOUT)

Si ya ha iniciado sesión (no se detecta mensaje de inicio de sesión), salta al paso 5.

📄 Licencia

MIT