X-Plane Control

Controla e inspecciona un simulador de vuelo X-Plane desde ChatGPT o Codex mediante solicitudes en lenguaje natural.

X-Plane Control es un complemento multiplataforma que contiene un servidor local integrado de Model Context Protocol (MCP). El servidor MCP permite al modelo buscar los catálogos DataRefs.txt y Commands.txt propios de X-Plane, leer datos en vivo del simulador, cambiar valores escribibles, ejecutar comandos del simulador y reubicar la aeronave mediante el protocolo UDP nativo de X-Plane.

Ejemplos de solicitudes:

• "Mueve mi avión a una ubicación aleatoria en Arizona."

• "Muestra mi posición actual, velocidad indicada, altitud y rumbo."

• "Encuentra el comando correcto para bajar el tren de aterrizaje y luego ejecútalo."

• "Activa el freno de estacionamiento y verifica su estado."

• "Encuentra DataRefs escribibles relacionados con las luces de instrumentos."

El modelo no necesita una lista codificada de todos los controles de X-Plane. Busca en el catálogo que pertenece a tu versión de X-Plane, selecciona un comando o DataRef escribible adecuado y llama a la herramienta MCP correspondiente.

[!ADVERTENCIA] Este proyecto es solo para uso en simuladores de vuelo. No está destinado a la operación, navegación o decisiones de entrenamiento de aeronaves reales. Los comandos y escrituras pueden cambiar inmediatamente la aeronave simulada. Mantén la interfaz UDP no autenticada de X-Plane en una computadora de confianza o en una red privada.

Contenido

• Cómo funciona

• Características

• Requisitos

• Instalar una versión precompilada

• Instalar desde el código fuente

• Preparar X-Plane

• Configurar el complemento

• Usar X-Plane en otra computadora

• Empezar a usar el complemento

• Herramientas disponibles

• Referencia de configuración

• Comportamiento y limitaciones

• Solución de problemas

• Actualizar o desinstalar

• Desarrollo

• Notas de distribución

• Referencias técnicas

Related MCP server: ChatGPT Codex Bridge

Cómo funciona

ChatGPT desktop or Codex CLI
          |
          | MCP over local stdio
          v
X-Plane Control MCP server
          |
          | Native X-Plane UDP packets
          | RREF / DREF / CMND / RPOS / PREL
          v
      X-Plane 11 or 12

El complemento tiene dos entradas independientes:

1. Un catálogo — DataRefs.txt y Commands.txt le indican al modelo qué controles existen, qué significan y qué DataRefs son escribibles.

2. Un destino de red — una dirección IP y un puerto UDP identifican el simulador X-Plane en ejecución.

El catálogo y el simulador no tienen que estar en la misma computadora. Por ejemplo, ChatGPT puede ejecutar el complemento en una laptop usando archivos de catálogo copiados mientras X-Plane se ejecuta en una PC de juegos separada en la misma LAN.

El servidor se ejecuta localmente como un proceso de Node.js. No instala un complemento binario de X-Plane, no modifica el simulador, no requiere Python, no requiere PyYAML ni envía tráfico del simulador a través de un servicio alojado.

Características

• Se ejecuta en macOS, Linux y Windows con Node.js 20 o superior.

• Incluye el runtime completo de MCP en un solo archivo dist/server.mjs.

• Busca en los catálogos de DataRef y comandos de X-Plane del usuario.

• Usa una raíz de instalación de X-Plane o dos archivos de catálogo seleccionados explícitamente.

• Detecta automáticamente varias ubicaciones comunes de instalación de X-Plane 11 y 12.

• Descubre automáticamente X-Plane desde su baliza de multidifusión cuando es posible.

• Admite un host y puerto explícitos para computadoras remotas, VPN y redes donde la multidifusión no está disponible.

• Lee valores escalares con RREF.

• Escribe valores escalares numéricos con DREF.

• Ejecuta comandos exactos con CMND.

• Lee posición geográfica, actitud, velocidad y rotación mediante RPOS.

• Reubica una aeronave mediante PREL en lugar de intentar escribir DataRefs geográficos de solo lectura.

• Incluye una herramienta de alto nivel que selecciona un punto interior aleatorio en Arizona.

• Rechaza los DataRefs del catálogo marcados como de solo lectura.

• Rechaza DataRefs y comandos desconocidos por defecto.

• Requiere una anulación explícita para nombres de comandos asociados con salir, restablecer, reproducir, fallos, incendios o bloqueos.

Requisitos

Para todos

• X-Plane 11 o X-Plane 12.

• Node.js 20 o superior en la computadora que ejecuta ChatGPT o Codex.

• Un host de complemento local compatible:

  • ChatGPT de escritorio con soporte de complementos, o

  • Codex CLI.

• Los archivos DataRefs.txt y Commands.txt de la versión de X-Plane que deseas controlar.

Comprueba Node.js antes de instalar:

node --version

El resultado debe comenzar con v20, v21, v22 o una versión posterior. Una versión empaquetada no requiere npm, TypeScript, Python ni una instalación de dependencias por separado.

El ejecutable node debe estar disponible para el host del complemento a través de PATH. El instalador estándar de Node.js suele ser la opción más fácil en macOS y Windows. Si Node se instaló solo mediante un administrador de versiones específico de shell como nvm, consulta El complemento está instalado pero su servidor MCP no se inicia.

Requisitos adicionales al compilar desde el código fuente

• npm, incluido con Node.js.

• Git, si se clona en lugar de descargar el repositorio como archivo ZIP.

Superficies compatibles de ChatGPT y Codex

Este repositorio distribuye un complemento de marketplace local con un servidor MCP stdio integrado.

• ChatGPT de escritorio: compatible donde haya complementos locales disponibles.

• Codex CLI: compatible. Escribe /plugins para usar el navegador de complementos después de agregar el marketplace.

• Extensión de Codex IDE: no compatible porque la extensión IDE actualmente no admite complementos.

• ChatGPT web y móvil: no pueden iniciar directamente el servidor stdio integrado de esta computadora. Se necesitaría una edición alojada y publicada por separado para esas superficies.

Esta instalación local de marketplace normalmente no requiere el Modo Desarrollador de ChatGPT ni un endpoint HTTPS público. El Modo Desarrollador se usa al registrar y probar conexiones remotas de servidores MCP; este paquete, en cambio, lanza su propio servidor MCP localmente desde .mcp.json. Las políticas de cuenta o espacio de trabajo aún pueden restringir la disponibilidad de complementos.

Consulta la documentación oficial de OpenAI para conocer la disponibilidad e instalación de complementos actual y el empaquetado de complementos.

Instalar una versión precompilada

Este es el método de instalación recomendado para la mayoría de los usuarios.

1. Descargar y extraer el paquete

Descarga el archivo de la última versión desde la página de Releases de este repositorio y extráelo. Abre el directorio x-plane-control-marketplace extraído.

Si descargaste el repositorio completo en lugar de un archivo de versión, el marketplace precompilado se encuentra en:

release/x-plane-control-marketplace

El directorio de marketplace correcto contiene ambas rutas:

.agents/plugins/marketplace.json
plugins/x-plane-control/.codex-plugin/plugin.json

Los directorios con prefijo de punto, como .agents, pueden estar ocultos en Finder o Explorador de archivos. No es necesario hacerlos visibles para que funcionen los comandos de terminal.

2. Agregar el marketplace descargado

Abre Terminal en macOS o Linux, o PowerShell en Windows. Cambia al directorio de marketplace extraído y luego ejecuta:

codex plugin marketplace add .

También puedes darle al comando una ruta absoluta sin cambiar de directorio:

codex plugin marketplace add "/absolute/path/to/x-plane-control-marketplace"

Ejemplo de PowerShell:

codex plugin marketplace add "C:\Users\YourName\Downloads\x-plane-control-marketplace"

3. Instalar el complemento

codex plugin add x-plane-control@x-plane-control-local

Confirma que Codex puede ver el marketplace y el complemento:

codex plugin marketplace list
codex plugin list

4. Reiniciar el host

Cierra y vuelve a abrir por completo la aplicación de escritorio de ChatGPT, luego abre el Directorio de complementos y confirma que X Plane Control está instalado y habilitado. Inicia un nuevo chat para que se carguen la nueva habilidad y las herramientas MCP.

En Codex CLI, inicia una nueva sesión después de la instalación. También puedes escribir /plugins para revisar los complementos instalados.

Instalar desde el código fuente

Usa este método para desarrollar el complemento, inspeccionar el código fuente o compilar una versión tú mismo.

1. Descargar el repositorio

Usa la acción Code → Download ZIP de GitHub y extrae el archivo, o clona el repositorio:

git clone https://github.com/josvisser66/x-plane-control.git
cd x-plane-control

Si el repositorio contiene x-plane-control como subdirectorio, cambia a ese directorio antes de continuar. Es el directorio que contiene package.json.

2. Instalar dependencias y validar el proyecto

npm ci
npm run validate

La validación realiza una comprobación de TypeScript, ejecuta las pruebas automatizadas y crea dist/server.mjs.

3. Crear el marketplace distribuible

npm run package:plugin

Esto crea:

release/x-plane-control-marketplace

Solo el complemento de runtime, sus metadatos de marketplace, licencia, habilidad y documentación se copian en este directorio. Los archivos fuente, las pruebas y las dependencias de desarrollo no son necesarios para el complemento instalado.

4. Agregar e instalar el marketplace local

codex plugin marketplace add "./release/x-plane-control-marketplace"
codex plugin add x-plane-control@x-plane-control-local

Reinicia ChatGPT de escritorio o inicia una nueva sesión de Codex CLI.

Preparar X-Plane

1. Localizar los catálogos

Para una instalación normal de X-Plane, los archivos están aquí:

<X-Plane installation>/Resources/plugins/DataRefs.txt
<X-Plane installation>/Resources/plugins/Commands.txt

El nombre del directorio es Resources/plugins, con plugins en minúsculas en las instalaciones actuales de X-Plane. El complemento también verifica algunas variantes de mayúsculas para compatibilidad.

No configures Resources/plugins como la ruta de instalación. Configura la raíz de instalación de X-Plane que contiene Resources, como:

• macOS: /Applications/X-Plane 12 o /Users/alice/X-Plane 12

• Windows: C:\X-Plane 12

• Windows Steam: C:\Program Files (x86)\Steam\steamapps\common\X-Plane 12

• Linux: /home/alice/X-Plane 12

• Linux Steam: /home/alice/.steam/steam/steamapps/common/X-Plane 12

DataRefs.txt y Commands.txt no están incrustados intencionalmente en este repositorio. Cargar los archivos suministrados con el simulador mantiene el descubrimiento alineado con la versión de X-Plane instalada por el usuario. Si no hay una instalación local de X-Plane, copia ambos archivos a cualquier directorio legible y configura sus rutas exactas por separado.

2. Habilitar la red UDP

Abre la pantalla Settings → Network de X-Plane. Asegúrate de que X-Plane acepte conexiones entrantes de red/UDP y anota su puerto UDP entrante. El puerto estándar de X-Plane suele ser 49000, pero usa el valor que muestre tu simulador.

Permite que X-Plane pase a través del firewall del sistema operativo cuando se te solicite. Cuando X-Plane esté en otra computadora, su firewall debe permitir el tráfico UDP entrante en el puerto de X-Plane configurado desde la computadora que ejecuta el complemento.

3. Cargar un vuelo

El servidor MCP puede iniciarse antes que X-Plane, y X-Plane inicializa la red durante el arranque. Para obtener valores de DataRef, comandos y reubicación confiables, espera hasta que una aeronave y el escenario hayan terminado de cargarse en un vuelo.

Durante la pantalla de presentación, el menú principal o la carga del vuelo:

• la sonda de estado podría no recibir una respuesta;

• algunos DataRefs pueden no estar disponibles o contener valores de marcador de posición;

• los comandos pueden ignorarse; y

• las escrituras de posición o DataRef pueden sobrescribirse durante el proceso de carga.

Configurar el complemento

La configuración se puede guardar de forma conversacional, que es el método más simple, o proporcionarse mediante variables de entorno.

Opción A: configurar una raíz de instalación de X-Plane

Inicia un nuevo chat con el complemento instalado y di:

Usa X Plane Control. Configura mi directorio de instalación de X-Plane como /Applications/X-Plane 12 y luego muestra el estado sin cambiar el simulador.

Ejemplo de Windows:

Usa X Plane Control. Configura mi directorio de instalación de X-Plane como C:\X-Plane 12 y luego verifica el catálogo.

El complemento busca debajo de la raíz los archivos Resources/plugins/DataRefs.txt y Commands.txt. Valida ambos archivos antes de guardar la ruta.

Opción B: configurar dos archivos de catálogo

Usa este modo si X-Plane está instalado en otra computadora o los archivos de catálogo se almacenan en otro lugar:

Usa X Plane Control. Configura DataRefs.txt como /Users/alice/XPlaneCatalog/DataRefs.txt y Commands.txt como /Users/alice/XPlaneCatalog/Commands.txt, y luego muestra el estado.

Ambas rutas deben proporcionarse juntas. Los archivos pueden estar en directorios diferentes. Establecer rutas de catálogo explícitas reemplaza una raíz de instalación guardada previamente; establecer una raíz de instalación reemplaza rutas explícitas guardadas previamente.

Configurar el destino UDP

Para X-Plane en la misma computadora, el descubrimiento automático suele ser suficiente. Si el descubrimiento no está disponible, el complemento recurre a 127.0.0.1:49000.

Para establecer un destino explícito:

Configura X-Plane en el host 192.168.1.50 en el puerto UDP 49000 y, a continuación, haz una prueba.

El host puede ser una dirección IPv4 o un nombre de host que el equipo del plugin pueda resolver. Se recomienda especificar un host explícito cuando X-Plane se ejecuta en otro equipo.

Verificar la configuración

Pregunta:

Usa X Plane Control para mostrar el estado completo y probar el simulador.

El estado incluye:

• la ubicación del archivo de configuración guardado;

• la configuración efectiva de catálogo y de red;

• las rutas resueltas de DataRefs.txt y Commands.txt;

• el número de DataRefs y comandos analizados;

• si el destino se configuró, se descubrió mediante una baliza o se tomó del valor predeterminado de localhost; y

• el resultado de leer el DataRef de versión de X-Plane.

Usar X-Plane en otro equipo

El servidor MCP incluido siempre se ejecuta en el equipo de ChatGPT/Codex. X-Plane puede ejecutarse en ese equipo o en otro equipo accesible por UDP.

Configuración recomendada para equipos remotos

1. Conecta ambos equipos a la misma red de área local (LAN) de confianza o a una VPN privada.

2. Busca la dirección IP privada del equipo con X-Plane, por ejemplo 192.168.1.50.

3. En X-Plane, habilita las conexiones de red entrantes y anota el puerto UDP de entrada.

4. Permite el tráfico UDP entrante a ese puerto a través del cortafuegos del equipo con X-Plane.

5. Copia DataRefs.txt y Commands.txt al equipo de ChatGPT/Codex si no tiene X-Plane instalado.

6. Configura las rutas de catálogo copiadas.

7. Configura la dirección IP y el puerto UDP del equipo con X-Plane.

8. Carga un vuelo y ejecuta la prueba de estado.

Ejemplo de conversación:

Usa X Plane Control. Mi simulador está en 192.168.1.50:49000. Mis catálogos locales son /Users/alice/XPlaneCatalog/DataRefs.txt y /Users/alice/XPlaneCatalog/Commands.txt. Guarda esa configuración y prueba X-Plane.

El descubrimiento por multidifusión normalmente solo funciona en el mismo segmento de red local y puede estar bloqueado por el aislamiento de Wi-Fi, los enrutadores, los contenedores o el software de VPN. En esos casos, configura el host explícitamente.

No reenvíes el puerto UDP de X-Plane directamente desde un enrutador de internet. El protocolo nativo no está cifrado ni autenticado. Para equipos en ubicaciones diferentes, usa una VPN privada que haga que las máquinas sean accesibles por IP privada y restringe el acceso del cortafuegos al equipo del plugin.

Empezar a usar el plugin

Después de la instalación o una actualización, inicia siempre un nuevo chat o una sesión de Codex. Una instrucción directa para usar el plugin facilita las pruebas de la primera ejecución:

Usa X Plane Control para comprobar si mi simulador y mis catálogos están listos. No cambies nada todavía.

Una vez que el estado sea correcto, se pueden usar solicitudes normales en lenguaje natural.

Leer el estado del simulador

• «Muestra mi posición geográfica y mi actitud».

• «Lee mi velocidad aerodinámica indicada, mi velocidad aerodinámica real, mi rumbo y mi altitud de presión».

• «Busca los DataRefs de la cantidad de combustible y muestra sus valores actuales».

• «Comprueba si el freno de estacionamiento está accionado».

Para una solicitud que no mencione DataRefs exactos, el modelo debe buscar primero en el catálogo y usar las descripciones y los tipos para seleccionar candidatos.

Ejecutar comandos del simulador

• «Busca y ejecuta el comando para alternar el tren de aterrizaje».

• «Enciende las luces de aterrizaje con un comando de X-Plane».

• «Pausa el simulador».

• «Ejecuta el comando de arranque dos veces».

Los comandos representan acciones discretas. El servidor actual envía paquetes CMND de comando único; no implementa el mantenimiento de inicio/fin de comando.

Establecer valores

• «Busca un DataRef escribible para el freno de estacionamiento, establécelo en totalmente accionado y vuelve a leerlo».

• «Establece la relación de acelerador del primer motor en 0,5».

• «Busca DataRefs escribibles de brillo de las luces de instrumentos para esta solicitud y muéstrame los candidatos antes de cambiar nada».

Las descripciones de DataRefs.txt definen las unidades y los significados válidos. Si una unidad, un elemento de matriz o un valor deseado no está claro, pide al modelo que muestre los candidatos antes de escribir.

Mover la aeronave

• «Mueve mi avión a una ubicación aleatoria en Arizona».

• «Teletransporta la aeronave del usuario a la latitud 34.8697, longitud -111.7609, a 5000 metros sobre el nivel medio del mar, con rumbo este a 60 metros por segundo».

• «Muestra mi posición, muéveme a estas coordenadas y muestra la posición resultante».

Los DataRefs de posición geográfica son de solo lectura. El plugin usa el paquete PREL nativo de X-Plane para la reubicación y, a continuación, solicita una muestra RPOS independiente cuando es posible.

Pregunta antes de cambiar nada

Si quieres inspeccionar primero la elección del modelo, indícalo explícitamente:

Busca el mejor comando o DataRef escribible para bajar el tren de aterrizaje. Explica lo que hayas encontrado, pero no ejecutes ni escribas nada hasta que confirme.

Las herramientas de escritura, comando y reubicación están marcadas como operaciones de mutación, por lo que el cliente también puede mostrar un aviso de confirmación o aprobación según su configuración de seguridad.

Herramientas disponibles

La herramienta actual de región aleatoria de alto nivel es compatible con arizona. Otras ubicaciones geográficas se pueden usar mediante latitud y longitud explícitas con teleport_xplane_aircraft.

Referencia de configuración

Configuración guardada

La configuración conversacional se almacena en el directorio de configuración normal por usuario del sistema operativo:

• macOS: ~/Library/Application Support/XPlaneControl/config.json

• Linux: $XDG_CONFIG_HOME/x-plane-control/config.json, o ~/.config/x-plane-control/config.json cuando XDG_CONFIG_HOME no está definido

• Windows: %APPDATA%\XPlaneControl\config.json

Ejemplo:

{
  "installationPath": "/Applications/X-Plane 12",
  "host": "192.168.1.50",
  "port": 49000,
  "discoveryTimeoutMs": 1200
}

Ejemplo de archivo de catálogo explícito:

{
  "datarefsPath": "/Users/alice/XPlaneCatalog/DataRefs.txt",
  "commandsPath": "/Users/alice/XPlaneCatalog/Commands.txt",
  "host": "192.168.1.50",
  "port": 49000
}

Usa installationPath o el par datarefsPath/commandsPath, no ambos.

Variables de entorno

Las variables de entorno anulan los valores guardados:

La prioridad del catálogo es:

1. el par explícito XPLANE_DATAREFS_PATH y XPLANE_COMMANDS_PATH;

2. XPLANE_HOME; y

3. la configuración de catálogo guardada o la detección automática de instalación.

XPLANE_HOST, XPLANE_PORT y XPLANE_DISCOVERY_TIMEOUT_MS anulan individualmente sus equivalentes guardados.

Las variables de entorno son más fáciles de usar con Codex CLI porque la CLI hereda el entorno del shell:

export XPLANE_HOME="/home/alice/X-Plane 12"
export XPLANE_HOST="192.168.1.50"
export XPLANE_PORT="49000"
codex

PowerShell:

$env:XPLANE_HOME = "C:\X-Plane 12"
$env:XPLANE_HOST = "192.168.1.50"
$env:XPLANE_PORT = "49000"
codex

Es posible que una aplicación de escritorio iniciada desde Finder, el Dock o el menú Inicio no herede las variables establecidas en un terminal. Usa configure_xplane y la configuración guardada para la aplicación de escritorio a menos que la inicies intencionadamente con un entorno controlado.

Borrar la configuración guardada

Pide al plugin que borre campos individuales:

Borra el host y el puerto de X-Plane guardados y, a continuación, muestra el destino efectivo sin probar.

Para volver de archivos explícitos a la detección automática de instalación:

Borra las rutas guardadas de DataRefs.txt y Commands.txt y, a continuación, muestra el estado del catálogo.

Las dos rutas de catálogo explícitas siempre deben configurarse o borrarse juntas.

Comportamiento y limitaciones

Las escrituras UDP no se confirman

Los datagramas DREF, CMND y PREL nativos de X-Plane no devuelven confirmaciones de éxito. Un resultado correcto de la herramienta significa que el datagrama se envió, no que X-Plane aceptó el cambio.

Cuando la verificación sea importante, pide al modelo que lea el DataRef o la posición después. Una lectura de retorno es una observación independiente y la pérdida de UDP o el comportamiento del simulador aún pueden afectarla.

UDP no está ordenado ni es fiable

Los paquetes pueden perderse, duplicarse, retrasarse o llegar desordenados. El plugin usa tiempos de espera para las lecturas e informa de los valores que faltan. No proporciona semántica transaccional entre varias escrituras.

Solo se admiten escrituras escalares numéricas

La herramienta DREF actual escribe valores numéricos finitos. Las matrices y cadenas nativas deben tratarse de un elemento numérico indexado a la vez, por ejemplo:

sim/example/array_dataref[0]

No se han implementado las lecturas y escrituras de matrices completas ni de cadenas.

Los valores RREF son float32

X-Plane devuelve los valores de suscripción RREF como números de coma flotante de 32 bits, incluso cuando el catálogo describe un DataRef como entero o doble. Se esperan pequeñas diferencias de precisión.

Los catálogos no garantizan la disponibilidad en tiempo de ejecución

DataRefs.txt describe el catálogo base de X-Plane. Las aeronaves y los plugins de terceros pueden crear DataRefs o comandos adicionales en tiempo de ejecución. Es posible que esas entradas personalizadas no aparezcan en los archivos base.

Las herramientas tienen una vía de escape allowUnlisted, pero el modelo solo debe usarla cuando se haya identificado una ruta personalizada exacta de una fuente de confianza de aeronaves o plugins. Nunca se debe adivinar un nombre no incluido en la lista.

Que sea escribible no significa que todas las aeronaves respeten un valor

Un DataRef marcado como escribible puede seguir estando controlado o sobrescrito por la aeronave activa, el piloto automático, el modelo de vuelo u otro plugin. Algunos DataRefs solo tienen sentido para aeronaves o estados del simulador concretos.

Las unidades proceden del catálogo

Los nombres por sí solos no siempre revelan si un valor está en grados, radianes, nudos, metros por segundo, pies, metros, una proporción o una enumeración. El modelo debe inspeccionar la descripción del catálogo y pedir una aclaración cuando la unidad prevista no esté clara.

Varias instancias de X-Plane

El descubrimiento por baliza devuelve la primera instancia válida que escuche. Configura un host y un puerto explícitos cuando haya más de un simulador.

Solución de problemas

codex: command not found

Instala o actualiza Codex CLI, abre un nuevo terminal y confirma:

codex --version
codex plugin --help

La CLI actual debe proporcionar los comandos codex plugin. Consulta la documentación oficial de plugins de OpenAI para conocer las superficies de instalación compatibles.

El marketplace o el plugin no es visible

Ejecuta:

codex plugin marketplace list
codex plugin list

Confirma que:

• x-plane-control-local aparece como marketplace;

• x-plane-control aparece en la lista de plugins;

• añadiste el directorio que contiene .agents/plugins/marketplace.json, no el directorio interno del plugin;

• la aplicación de escritorio de ChatGPT se reinició por completo; y

• iniciaste un nuevo chat después de la instalación.

Los administradores del espacio de trabajo pueden restringir los plugins locales. Si el marketplace es reconocido por la CLI pero no está disponible en la aplicación, comprueba la política de la cuenta o del espacio de trabajo.

El plugin está instalado pero su servidor MCP no se inicia

Comprueba Node.js en una terminal:

node --version

En macOS o Linux, ejecuta también:

command -v node

En Windows:

Get-Command node

El .mcp.json incluido lanza node, por lo que debe ser visible en el PATH del host. Si Node solo está disponible después de que se cargue un perfil de shell, instala Node a nivel de sistema con el instalador estándar o haz que la aplicación de escritorio herede el PATH correcto y, a continuación, reinicia la aplicación por completo.

Para comprobar el servidor empaquetado manualmente, ejecuta esto desde el directorio del marketplace:

node plugins/x-plane-control/dist/server.mjs --transport=stdio

Un servidor stdio en buen estado espera en silencio los mensajes MCP; pulsa Ctrl+C para detenerlo. Los desarrolladores pueden ejecutar la prueba de protocolo de enlace automatizada con npm run smoke:stdio desde el directorio de origen.

No se puede encontrar el catálogo

Solicita el estado sin sondear X-Plane:

Muestra el estado de X Plane Control con el sondeo deshabilitado, incluidas las rutas de catálogo resueltas.

Comprueba que:

• una ruta de instalación apunta a la raíz de X-Plane, no a Resources/plugins;

• ambos archivos existen debajo de <root>/Resources/plugins;

• las rutas de archivo explícitas nombran los propios archivos;

• ambas rutas explícitas se configuraron juntas;

• el host del plugin tiene permiso para leer ambos archivos; y

• las variables de entorno no están sobrescribiendo la configuración guardada.

Si X-Plane está en otro equipo, copia ambos archivos al equipo del plugin y configura esas copias.

El sondeo UDP agota el tiempo de espera

Comprueba lo siguiente en orden:

1. X-Plane se está ejecutando y una aeronave ha terminado de cargarse.

2. X-Plane acepta conexiones de red entrantes.

3. El puerto UDP configurado coincide con los ajustes de red de X-Plane.

4. El host configurado es la dirección IP actual del equipo con X-Plane.

5. El cortafuegos del sistema operativo permite el tráfico.

6. Ambos equipos pueden alcanzarse entre sí en la misma LAN o VPN privada.

7. El aislamiento de clientes está deshabilitado en la red Wi-Fi.

8. Se configura un host explícito si el descubrimiento por multidifusión no puede cruzar el límite de la red.

El envío de un datagrama UDP puede parecer exitoso incluso cuando ningún simulador está escuchando. Usa el sondeo de versión o una lectura de DataRef para establecer la accesibilidad.

Un comando o escritura dice «enviado» pero nada cambia

Las posibles causas incluyen:

• el vuelo todavía se está cargando;

• pérdida de paquetes UDP;

• el valor de DataRef usa unidades diferentes o un enum;

• se seleccionó el índice de matriz incorrecto;

• la aeronave activa u otro plugin sobrescribió el valor inmediatamente;

• el comando no es aplicable a la aeronave activa; o

• el catálogo configurado no coincide con la versión de X-Plane en ejecución.

Pide al modelo que lea el valor de nuevo y que muestre la entrada del catálogo que seleccionó. Para una acción de cabina discreta, pídele que busque un comando exacto en lugar de forzar una escritura de DataRef.

Falta un comando o DataRef de una aeronave complementaria

Los archivos de catálogo estándar no contienen necesariamente los controles complementarios registrados dinámicamente. Consulta la documentación de la aeronave o del plugin para conocer la ruta exacta. A continuación, pide al modelo que use ese nombre exacto no listado y explica por qué la anulación es apropiada.

Los valores parecen redondeados o ligeramente diferentes

RREF devuelve valores float32. La precisión puede ser menor que el tipo de DataRef subyacente, y X-Plane puede actualizar los valores entre lecturas separadas.

Actualizar o desinstalar

Actualizar un paquete local descargado

1. Descarga y extrae la nueva versión.

2. Elimina la copia instalada anterior:

   codex plugin remove x-plane-control@x-plane-control-local

3. Si el nuevo paquete está en un directorio diferente, reemplaza el registro del marketplace:

   codex plugin marketplace remove x-plane-control-local
   codex plugin marketplace add "/path/to/new/x-plane-control-marketplace"

4. Instala el plugin de nuevo:

   codex plugin add x-plane-control@x-plane-control-local

5. Reinicia ChatGPT de escritorio e inicia un nuevo chat.

Los ajustes guardados de X-Plane Control se almacenan fuera de la caché del plugin, por lo que reinstalar el plugin normalmente no elimina la configuración guardada del simulador/catálogo.

Desinstalar

codex plugin remove x-plane-control@x-plane-control-local
codex plugin marketplace remove x-plane-control-local

Los comandos eliminan el plugin instalado y el registro del marketplace. No eliminan el config.json de X-Plane Control guardado por separado. Elimina ese archivo manualmente solo si también quieres borrar las rutas guardadas y el destino de red.

Desarrollo

Comandos comunes

npm run check
npm test
npm run build
npm run smoke:stdio
npm run package:plugin

• npm run check comprueba los tipos del código fuente TypeScript.

• npm test ejecuta las pruebas de paquetes, catálogo, configuración y X-Plane falso.

• npm run build empaqueta el servidor en dist/server.mjs.

• npm run smoke:stdio lanza el servidor empaquetado y realiza una prueba de protocolo de enlace/lista de herramientas de MCP.

• npm run package:plugin valida, empaqueta y prueba el plugin distribuible.

Estructura del proyecto

.codex-plugin/plugin.json     Plugin manifest
.mcp.json                     Bundled stdio MCP launch configuration
dist/server.mjs               Bundled runtime
skills/x-plane-control/       Model workflow instructions
src/catalog.ts                Catalog parsing and search
src/config.ts                 Saved and environment configuration
src/protocol.ts               X-Plane packet encoding and decoding
src/server.ts                 MCP tools and transports
src/xplane.ts                 UDP discovery and client
tests/                        Automated tests
scripts/package-plugin.mjs    Release marketplace builder
scripts/smoke-stdio.mjs       MCP stdio smoke test

Transporte HTTP de diagnóstico opcional

El plugin normal usa stdio. Se conserva un transporte HTTP de bucle local para diagnósticos de protocolo locales:

node dist/server.mjs --transport=http --host=127.0.0.1 --port=8765

Puntos de conexión:

• MCP: http://127.0.0.1:8765/mcp

• Comprobación de estado: http://127.0.0.1:8765/health

Este listener no está autenticado y debe permanecer vinculado al bucle local. No lo expongas públicamente.

Notas de distribución

Hacer público este repositorio en GitHub permite a los usuarios descargar e instalar el paquete de marketplace local. No lista automáticamente el plugin en el Directorio público universal de plugins de OpenAI.

La edición de GitHub/marketplace local es deliberadamente un plugin stdio empaquetado porque debe acceder a archivos de catálogo locales y a un simulador en la red del usuario. La ruta de envío de plugins públicos de OpenAI generalmente espera un servicio MCP de producción en un punto de conexión HTTPS estable, con autenticación y revisión adecuadas. Esa sería una arquitectura y un canal de publicación separados.

Antes de crear una versión en GitHub:

1. Actualiza la versión y los metadatos públicos de autor/repositorio en .codex-plugin/plugin.json y package.json.

2. Ejecuta npm ci.

3. Ejecuta npm run package:plugin.

4. Prueba el directorio release/x-plane-control-marketplace generado en una cuenta o máquina limpia.

5. Archiva ese directorio como el recurso de la versión, conservando .agents/plugins/marketplace.json.

6. Publica el código fuente y el archivo de versión bajo la licencia MIT incluida.

Privacidad y seguridad

• El servidor MCP y el cliente UDP de X-Plane se ejecutan localmente.

• Este servidor no requiere ninguna clave de API de OpenAI.

• No se usan credenciales de X-Plane.

• La configuración guardada contiene rutas del sistema de archivos y, opcionalmente, un nombre de host/IP y puerto del simulador.

• El tráfico UDP de X-Plane no está cifrado ni autenticado.

• Los archivos de catálogo se leen localmente y se usan para la búsqueda y los metadatos de seguridad.

• El plugin puede cambiar el estado del simulador, por lo que debes revisar las aprobaciones de herramientas y usarlo solo con un simulador que estés autorizado a controlar.

Referencias técnicas

• Referencia de DataRefs de X-Plane

• Documentación de acceso a datos del SDK de X-Plane

• Resumen del protocolo de salida de datos UDP de X-Plane

• Notas del protocolo de XPlaneConnector

• Documentación UDP de XPPython3

• Documentación de plugins de OpenAI

• Guía de empaquetado de plugins de OpenAI

• Especificación del Model Context Protocol

Licencia

MIT. Consulta LICENSE.