Servidor MCP de DualStream

¡Nuestro primer proyecto de código abierto! El servidor oficial de Model Context Protocol para DualStream, el estudio de streaming que produce transmisiones de escritorio (16:9) y móvil (9:16) simultáneamente desde un solo pipeline.

Este servidor permite que asistentes de IA como Claude operen tu estudio DualStream: cambiar de escena, guardar clips de repetición instantánea, construir diseños de escena completos desde cero, rediseñar tus alertas y widgets, y reaccionar a lo que sucede en la transmisión. Todo se ejecuta localmente en tu máquina, con tu aprobación explícita, y cada cambio se renderiza tanto en tu lienzo de escritorio como en el móvil.

AI assistant (Claude Code, Claude Desktop, or any MCP client)
        |  MCP over stdio
        v
DualStream MCP server  (this package)
        |  JSON-RPC over WebSocket, 127.0.0.1 only
        v
DualStream desktop app

Lo que puedes pedir

Una vez conectado, hablas con tu asistente en lenguaje natural:

• "Cambia a mi escena BRB"

• "Recorta los últimos 30 segundos"

• "Crea una escena llamada MAIN con mi cámara web en la esquina inferior derecha, recortada en círculo, y mi pantalla principal a pantalla completa detrás"

• "Hazme una escena de 'empezando pronto' para una transmisión benéfica con mis colores de marca, en ambos lienzos"

• "Rediseña mis alertas para que coincidan con esta paleta"

• "Sube un poco la cámara y dale una sombra suave"

El asistente descubre tu hardware real (cámaras, pantallas, ventanas, micrófonos), compone diseños para los lienzos de escritorio y móvil de forma independiente, e itera contigo hasta que se vea bien.

Related MCP server: ATEM MCP Server

Antes de empezar

Necesitas tres cosas instaladas. Cada una es un instalador normal de descargar y ejecutar:

1. La aplicación de escritorio DualStream (Windows o macOS): el estudio que controla este servidor.

2. Node.js: elige el botón verde grande de LTS (versión 22 o superior). Este es el runtime que ejecuta el servidor; no interactuarás con él directamente.

3. Un asistente de IA que admita MCP, como Claude Desktop o la CLI de Claude.

Instalación

Paso 1: Descarga este proyecto en tu computadora

Haz clic en el botón verde Code en la parte superior de esta página de GitHub y elige Download ZIP, luego descomprímelo en un lugar que recuerdes, por ejemplo tu carpeta de Documentos. (Si te sientes cómodo con git, git clone también funciona.)

Paso 2: Compilarlo

Abre una terminal en la carpeta descomprimida:

• Windows: abre la carpeta en el Explorador de archivos, haz clic en la barra de direcciones, escribe cmd y presiona Enter.

• macOS: haz clic derecho en la carpeta y elige Nueva terminal en la carpeta (o arrastra la carpeta a Terminal).

Luego ejecuta estos dos comandos, uno después del otro:

npm install
npm run build

Cada uno imprime algo de texto y vuelve al prompt. Eso es todo; el servidor está compilado.

Paso 3: Informa a tu asistente

Necesitas la ruta completa a la carpeta del Paso 1. En el Explorador de archivos de Windows, haz clic en la barra de direcciones y cópiala (se ve como C:\Users\you\Documents\DualStreamMCP). En macOS, haz clic derecho en la carpeta, mantén presionada la tecla Opción y elige Copiar como nombre de ruta.

Claude Desktop: abre Configuración → Desarrollador → Editar configuración y agrega esto (reemplaza la ruta con la tuya; en Windows, usa dobles barras invertidas como se muestra):

{
  "mcpServers": {
    "dualstream": {
      "command": "node",
      "args": ["C:\\Users\\you\\Documents\\DualStreamMCP\\dist\\index.js"]
    }
  }
}

CLI de Claude: un comando (reemplaza la ruta con la tuya):

claude mcp add dualstream -- node "C:\Users\you\Documents\DualStreamMCP\dist\index.js"

Cualquier otro cliente MCP funciona de la misma manera: ejecuta node <carpeta>/dist/index.js como servidor stdio.

Paso 4: Saluda

Reinicia tu asistente, asegúrate de que DualStream esté en ejecución y pregunta: "¿En qué escena estoy en vivo en DualStream?" La primera vez, DualStream mostrará un aviso de aprobación; eso es el modelo de seguridad funcionando (ver más abajo). Apruébalo y listo.

Primera conexión y seguridad

La aplicación DualStream ejecuta un pequeño servidor de control vinculado solo a 127.0.0.1. Nada es accesible desde la red, y este servidor MCP debe ejecutarse en la misma máquina que la aplicación. No hay componente en la nube: la inteligencia es la del asistente de IA que conectes, y tu transmisión nunca sale de tu control.

El emparejamiento es automático. La aplicación publica un token de emparejamiento en su directorio de configuración, y este servidor lo recoge por sí solo; nunca escribes una contraseña. La primera vez que un asistente se conecta, DualStream muestra un aviso de consentimiento que nombra al cliente. Puedes elegir Permitir, Permitir siempre o Denegar. Hasta que apruebes, la conexión no puede hacer nada. Puedes ver cada cliente conectado, desconectar cualquiera de ellos y revocar aprobaciones recordadas en cualquier momento en Configuración, General, Control externo de la aplicación.

Si deniegas una conexión, el servidor la cierra. Si restableces el token de emparejamiento en la configuración de la aplicación, todos los clientes conectados se desconectan y deben volver a emparejarse.

Herramientas

Escenas y clips

Composición de escenas

Construye y edita escenas fuente por fuente. Los diseños en los lienzos de escritorio (1920x1080) y móvil (1080x1920) se controlan de forma independiente, por lo que una pequeña cámara facial redonda en el escritorio puede ser una cámara cuadrada de ancho completo en el móvil.

Recetas

Las recetas son plantillas de escena compartibles de DualStream: un fondo más fuentes posicionadas para ambos lienzos, guardadas como JSON en disco.

Widgets

Tarjeta de IA

Automatizaciones

Las automatizaciones emparejan un disparador de evento de transmisión (una incursión, un gran aplauso, el final de un hype train) con una instrucción permanente para tu asistente. Cuando ocurre un evento que coincide, DualStream lo retransmite al asistente con tu instrucción adjunta; el asistente compone y publica la tarjeta. Solo los eventos que coinciden con una automatización habilitada salen de la aplicación, y el asistente solo escucha mientras tienes una sesión abierta. El formato completo del documento, el vocabulario de eventos y el flujo de ensayo están en contract/automations-v1.md.

Una sesión en vivo típica: dile a tu asistente que vas a salir en vivo; lee tus automatizaciones, luego se repite en wait_for_event; esperar no cuesta nada, y cada evento manejado es un intercambio corto (da la bienvenida a los invasores, agradece a la ballena, publica la tarjeta).

Los errores de las herramientas son JSON estructurado con una bandera retryable, para que los asistentes sepan la diferencia entre "inténtalo de nuevo en un segundo" (el búfer de repetición aún se está calentando, la conexión espera tu aprobación) y "algo está realmente mal".

Configuración

Todo funciona con cero configuración cuando la aplicación y este servidor se ejecutan bajo la misma cuenta de usuario. Estas variables de entorno existen para configuraciones inusuales:

El descubrimiento lee ws-control.json del directorio de configuración de la aplicación (%APPDATA%\app.dualstream.io\ en Windows, ~/Library/Application Support/app.dualstream.io/ en macOS). La aplicación escribe este archivo en cada inicio, antes de que el servidor de control informe que está listo.

Solución de problemas

Las herramientas devuelven app_not_running. La aplicación DualStream no está abierta o no ha terminado de iniciarse. Ábrela; el servidor se reconecta solo en cuanto la aplicación está activa.

Las herramientas devuelven consent_pending. La conexión está esperando tu aprobación. Apruébala en el aviso de consentimiento dentro de DualStream (o en Configuración, General, Control externo).

Las herramientas devuelven authentication_required o authentication_failed. La aplicación tiene la autenticación habilitada, pero este servidor no pudo obtener el token. Asegúrate de que la aplicación y el servidor se ejecuten como el mismo usuario. Si restableciste recientemente el token de emparejamiento, la reconexión lo maneja automáticamente; un DUALSTREAM_CONTROL_PASSWORD obsoleto en tu entorno también puede causar esto.

Algo más falla. Llama primero a get_connection_status; distingue entre "aplicación no en ejecución" y problemas de autenticación, consentimiento y protocolo. El servidor registra JSON de una sola línea en stderr; establece DUALSTREAM_MCP_LOG_LEVEL=debug para obtener detalles.

Notas de diseño

• Local por diseño. El plano de control es solo de loopback. Un conector alojado o remoto no puede alcanzarlo, y nunca debería.

• Basado en eventos, sin temporizadores. Las solicitudes en curso se resuelven solo con una respuesta del servidor o el cierre del socket, nunca con un timeout de reloj. La reconexión se activa observando el archivo de descubrimiento que la aplicación reescribe al iniciar; no hay bucles de sondeo.

• stdout es el canal de protocolo. Todo el registro va a stderr como JSON de una sola línea.

• Anclado al contrato. Las respuestas se validan contra el contrato de control incluido (consulta contract/); una aplicación que hable una versión más reciente del protocolo falla de forma visible con un mensaje de actualización en lugar de comportarse mal silenciosamente.

• El consentimiento se aplica en el servidor. La puerta de aprobación vive en la aplicación DualStream, no en este paquete; un cliente modificado no gana nada.

El directorio contract/ también contiene referencias de autoría que un asistente puede usar directamente: el formato de manifiesto de recetas, la guía de composición de escenas (incluidos los patrones de diseño para el lienzo móvil), el formato de automatizaciones y PROTOCOL.md: una referencia completa de métodos, eventos y códigos de error generada a partir del fixture del contrato.

Desarrollo

npm run typecheck   # strict TypeScript over src and tests
npm test            # unit + full MCP round-trips against a wire-faithful mock of the app
npm run build       # emit dist/
npm run smoke       # live end-to-end against a running DualStream app
                    # (switches a scene and back, saves one 10-second clip pair)

El servidor de control simulado en test/ implementa el protocolo de cable real, incluido el protocolo de enlace de emparejamiento y el flujo de consentimiento, con una implementación independiente del algoritmo de autenticación, por lo que el conjunto de pruebas realmente verifica de forma cruzada al cliente.

Acerca de DualStream

DualStream es un estudio de streaming para creadores que transmiten en vivo en plataformas de escritorio y móviles al mismo tiempo: una canalización, dos lienzos, cada escena y widget renderizado de forma nativa para ambas. Descárgalo para Windows o macOS en dualstream.gg.

Licencia

Apache-2.0