使用说明

Tornado MCP Client

Universal AI overlay client for video games using Model Context Protocol (MCP)

Tornado es un overlay transparente estilo “Discord overlay” que agrega IA a cualquier videojuego a través de MCPs específicos por juego. Carga contexto relevante (savefile, screenshot, guía) y lo envía a las herramientas del MCP para dar respuestas útiles en tiempo real.

¿Qué es MCP y cómo lo usamos?

MCP define cómo clientes y servidores de herramientas comparten contexto y se invocan de manera segura. Tornado actúa como cliente MCP y cada juego tiene su “MCP de juego” (servidor) que expone herramientas.

Estándar mínimo que debe cumplir un MCP de juego:

analyze_savefile: parsea el savefile y devuelve JSON utilizable
take_screenshot: captura/obtiene una referencia de screenshot del juego
download_guide: descarga o referencia una guía/compendio del juego

Tornado combina este contexto automáticamente antes de cada interacción.

Ejemplo de MCP de juego: hollow-knight-mcp (PR).

MCPs permitidos: política de uso

Permitido:

Lectura de archivos locales del usuario (savefiles), screenshots y guías/documentación
Automatizaciones externas que NO inyecten código en el proceso del juego
Uso educativo, personal y no comercial (ver licencia)

No permitido por Tornado (ni distribuiremos MCPs que lo hagan):

Inyección de memoria o código en el proceso del juego
Cheats, hacks, bypass de anti-cheat, o actividades que violen TOS de juegos
Ingeniería maliciosa o scraping que infrinja propiedad intelectual

Arquitectura (alto nivel)

Tornado es una app Electron con React + TypeScript. La ventana del overlay es transparente, sin marco, siempre on-top y con modo click-through; soporta multi-monitor y hotkeys globales.

flowchart LR
  U[Usuario] --> HK[Hotkeys Globales]
  HK --> M[Electron Main]
  M --> R[Renderer React Overlay]
  R --> M
  R -->|Interaccion| CB[Context Bundler]
  CB --> SF[Savefile Cache]
  CB --> SS[Screenshots Cache]
  CB --> GD[Guide Chunks]
  M --> CM[MCP Connection Manager]
  CM --> M
  CM --> S1[MCP Juego A]
  CM --> S2[MCP Juego B]
  CM --> AI[Modelos IA OpenAI/Anthropic/Local]
  DB[(SQLite)]
  SF --- DB
  SS --- DB
  GD --- DB
  style R fill:#e3f2fd,stroke:#64b5f6
  style M fill:#f3e5f5,stroke:#ba68c8
  style CM fill:#fff3e0,stroke:#ffb74d
  style CB fill:#e8f5e9,stroke:#81c784

Componentes:

Main (Electron): ciclo de vida, hotkeys, IPC, overlay
Renderer (React): UI (chat, selector de modelo, acciones, estado)
MCP Connection Manager: múltiples MCPs, reconexión, namespaces
Context Bundler: empaqueta savefile + screenshot + guía con chunking y sampling
SQLite DB: metadatos de MCPs, cachés y configuraciones por juego

Tecnologías

Electron: overlay transparente (setIgnoreMouseEvents), always-on-top, screen para monitores
React + TypeScript + Vite: UI y hot reload en desarrollo
SQLite (p. ej. better-sqlite3): persistencia de metadatos y cachés
@modelcontextprotocol/sdk: cliente MCP (transporte stdio u otros)
Empaquetado: electron-builder (Windows/macOS/Linux)
Captura: desktopCapturer (con consentimiento)
Hotkeys: globalShortcut (main) + atajos en UI (preload + contextBridge)
Modelos: API keys (OpenAI/Anthropic/otros) u opción local (Ollama/LM Studio)

Modos de sampling y modelos

Modo API Key: conexión directa a modelos con tu API key
Modo GitHub Free: integración con VS Code/GitHub para planes gratuitos (si aplica)

Detección de juegos

Detección de procesos/ventanas para asociar MCPs instalados
Auto-carga del MCP correcto al detectar el juego
Overrides de reglas por MCP (process name/window title)

Estructura de carpetas (propuesta)

src/
  main/        # Electron main (ventana, IPC, hotkeys)
  renderer/    # React UI (chat, selector, acciones)
  shared/      # Tipos y utilidades comunes
  db/          # Acceso SQLite y DAOs
mcps/          # MCPs instalados (npm/local)
cache/         # screenshots, guías chunked, parseos

Instalación y desarrollo

Requisitos: Node 18+ (recomendado Node 20 LTS), pnpm o npm/yarn.

pnpm install
pnpm dev   # arranca Electron con hot reload
pnpm build # genera binarios con electron-builder

Variables de entorno (ejemplo .env):

OPENAI_API_KEY=...
ANTHROPIC_API_KEY=...
TORNADO_SENTRY_DSN=...

Configuración de MCPs

Instalación desde npm o ruta local
Validación: el MCP debe exponer analyze_savefile, take_screenshot, download_guide
Config por MCP: rutas de savefile/guía, overrides de hotkeys, opciones avanzadas
Multi-MCP: cargar varios MCPs en paralelo con namespaces aislados

UI del overlay

Chat con render de markdown y estado “pensando”
Selector de modelo y parámetros (temperatura, tokens máx.)
Botones de acción rápida por MCP activo
Indicadores de estado: MCP conectado, contexto cargado (savefile/screenshot/guía)

Sistema de Hotkeys Globales

Tornado incluye un sistema de hotkeys globales personalizables para mejorar la experiencia de uso durante el juego.

Modo Activado (Activated Mode)

El overlay tiene dos modos de operación que se pueden alternar con un hotkey:

Modo Inactivo (por defecto): El overlay es click-through (los clics pasan a través) y tiene baja opacidad para no interferir con el juego
Modo Activado: El overlay se vuelve clickeable y aumenta su opacidad para permitir interacción completa

Hotkeys Configurables

Los siguientes hotkeys están disponibles y son personalizables desde la UI:

Toggle Activated Mode (por defecto: F1): Alterna entre modo inactivo y activado
Capture Screen (por defecto: F12): Captura una screenshot para análisis por el MCP

Configuración de Hotkeys

En la sección de Hotkey Settings puedes:

Cambiar las combinaciones de teclas para cada acción
Ajustar la opacidad del modo activado (rango: 50-100%, predeterminado: 100%)
Ajustar la opacidad del modo inactivo (rango: 10-70%, predeterminado: 30%)
Ver el estado actual del overlay (activado/inactivo)

Formatos de hotkey soportados:

Teclas simples: F1, F12, etc.
Combinaciones: CommandOrControl+Shift+I, Alt+Tab, etc.
Se recomienda evitar hotkeys que puedan conflictuar con el juego

Rendimiento y seguridad

Minimizar impacto en FPS: render ligero, throttling y lazy-load de UI
Permisos explícitos para captura de pantalla
IPC seguro con contextIsolation y preload (no exponer APIs sensibles)

Roadmap (milestones)

Foundation: setup + README + overlay base
Core MCP: cliente MCP, sampling, modos de conexión
Game Integration: detección de juegos, gestión de MCPs y DB
UI/UX: chat, modelos, acciones, estados
Context System: integración de tools obligatorias
Polish & Distribution: performance, empaquetado, documentación

Licencia

Licencia dual:

AGPL-3.0 (ver LICENSE.md)
Licencia comercial (ver LICENSE-COMMERCIAL.md) Incluye Excepción de Uso Personal No Comercial (detallada en LICENSE.md).

Para licencias comerciales: barbycus@gmail.com