X-Plane Control

Управляйте и наблюдайте за авиасимулятором X-Plane из ChatGPT или Codex с помощью запросов на естественном языке.

X-Plane Control — это кроссплатформенный плагин, содержащий встроенный локальный сервер Model Context Protocol (MCP). MCP-сервер позволяет модели искать по собственным каталогам X-Plane DataRefs.txt и Commands.txt, считывать данные симулятора в реальном времени, изменять значения записываемых переменных, выполнять команды симулятора и перемещать воздушное судно через собственный протокол UDP от X-Plane.

Примеры запросов:

• «Перемести мой самолёт в случайное место в Аризоне.»

• «Покажи мои текущие координаты, приборную скорость, высоту и курс.»

• «Найди правильную команду для выпуска шасси, затем выполни её.»

• «Включи стояночный тормоз и проверь его состояние.»

• «Найди записываемые DataRef'ы, связанные с освещением приборной панели.»

Модели не нужен жёстко заданный список всех элементов управления X-Plane. Она ищет по каталогу, соответствующему вашей версии X-Plane, выбирает подходящую команду или записываемый DataRef и вызывает соответствующий MCP-инструмент.

[!WARNING] Этот проект предназначен только для использования с авиасимулятором. Он не предназначен для управления реальным воздушным судном, навигации или принятия решений при обучении. Команды и записи могут немедленно изменить состояние моделируемого воздушного судна. Держите неаутентифицированный UDP-интерфейс X-Plane на доверенном компьютере или в частной сети.

Содержание

• Как это работает

• Возможности

• Требования

• Установка из готового релиза

• Установка из исходного кода

• Подготовка X-Plane

• Настройка плагина

• Использование X-Plane на другом компьютере

• Начало работы с плагином

• Доступные инструменты

• Справочник по настройке

• Поведение и ограничения

• Устранение неполадок

• Обновление или удаление

• Разработка

• Примечания по распространению

• Технические ссылки

Related MCP server: ChatGPT Codex Bridge

Как это работает

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

Плагин имеет два независимых входа:

1. Каталог — DataRefs.txt и Commands.txt сообщают модели, какие элементы управления существуют, что они означают и какие DataRef'ы доступны для записи.

2. Сетевой адрес — IP-адрес и UDP-порт идентифицируют запущенный симулятор X-Plane.

Каталог и симулятор не обязательно должны находиться на одном компьютере. Например, ChatGPT может запускать плагин на ноутбуке, используя скопированные файлы каталога, в то время как X-Plane работает на отдельном игровом ПК в той же локальной сети.

Сервер работает локально как процесс Node.js. Он не устанавливает бинарный плагин X-Plane, не изменяет симулятор, не требует Python или PyYAML и не отправляет трафик симулятора через сторонний сервис.

Возможности

• Работает на macOS, Linux и Windows с Node.js 20 или новее.

• Объединяет всю среду выполнения MCP в один файл dist/server.mjs.

• Выполняет поиск по собственным каталогам DataRef и команд X-Plane пользователя.

• Использует корневой каталог установки X-Plane или два явно выбранных файла каталога.

• Автоматически обнаруживает несколько распространённых мест установки X-Plane 11 и 12.

• Автоматически обнаруживает X-Plane по его многоадресному маячку, когда это возможно.

• Поддерживает явный хост и порт для удалённых компьютеров, VPN и сетей, где многоадресная рассылка недоступна.

• Считывает скалярные значения с помощью RREF.

• Записывает числовые скалярные значения с помощью DREF.

• Выполняет точные команды с помощью CMND.

• Считывает географическое положение, ориентацию, скорость и вращение через RPOS.

• Перемещает воздушное судно через PREL, а не пытается записывать доступные только для чтения географические DataRef'ы.

• Включает высокоуровневый инструмент, который выбирает случайную внутреннюю точку в Аризоне.

• Отклоняет DataRef'ы каталога, помеченные как доступные только для чтения.

• По умолчанию отклоняет неизвестные DataRef'ы и команды.

• Требует явного подтверждения для имён команд, связанных с выходом, сбросом, повтором, сбоями, пожаром или крушением.

Требования

Для всех

• X-Plane 11 или X-Plane 12.

• Node.js 20 или новее на компьютере, где запущены ChatGPT или Codex.

• Поддерживаемый локальный хост плагинов:

  • ChatGPT desktop с поддержкой плагинов, или

  • Codex CLI.

• Файлы DataRefs.txt и Commands.txt из версии X-Plane, которой вы хотите управлять.

Проверьте Node.js перед установкой:

node --version

Результат должен начинаться с v20, v21, v22 или более поздней версии. Готовый пакет не требует npm, TypeScript, Python или отдельной установки зависимостей.

Исполняемый файл node должен быть доступен хосту плагина через PATH. Стандартный установщик Node.js обычно является самым простым выбором в macOS и Windows. Если Node был установлен только через менеджер версий, специфичный для оболочки, например nvm, см. Плагин установлен, но его MCP-сервер не запускается.

Дополнительные требования при сборке из исходного кода

• npm, входящий в состав Node.js.

• Git, если вы клонируете репозиторий, а не загружаете его в виде ZIP-архива.

Поддерживаемые поверхности ChatGPT и Codex

Этот репозиторий распространяет локальный плагин маркетплейса со встроенным stdio MCP-сервером.

• ChatGPT desktop: поддерживается там, где доступны локальные плагины.

• Codex CLI: поддерживается. Введите /plugins, чтобы использовать браузер плагинов после добавления маркетплейса.

• Расширение Codex IDE: не поддерживается, поскольку расширение IDE в настоящее время не поддерживает плагины.

• ChatGPT в Интернете и на мобильных устройствах: они не могут напрямую запускать встроенный stdio-сервер этого компьютера. Для этих поверхностей потребуется отдельно размещённая и опубликованная версия.

Эта локальная установка маркетплейса обычно не требует режима разработчика ChatGPT или публичной HTTPS-конечной точки. Режим разработчика используется при регистрации и тестировании удалённых подключений к MCP-серверу; этот пакет вместо этого запускает свой собственный MCP-сервер локально из .mcp.json. Политики учётной записи или рабочей области по-прежнему могут ограничивать доступность плагинов.

Официальную документацию по доступности и установке плагинов и упаковке плагинов см. в официальной документации OpenAI.

Установка из готового релиза

Это рекомендуемый способ установки для большинства пользователей.

1. Загрузите и распакуйте пакет

Загрузите последний архив релиза со страницы Releases этого репозитория и распакуйте его. Откройте извлечённый каталог x-plane-control-marketplace.

Если вы загрузили весь репозиторий, а не архив релиза, готовый маркетплейс находится по адресу:

release/x-plane-control-marketplace

Правильный каталог маркетплейса содержит оба этих пути:

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

Каталоги с префиксом точки, такие как .agents, могут быть скрыты в Finder или Проводнике. Для работы терминальных команд их не нужно делать видимыми.

2. Добавьте загруженный маркетплейс

Откройте Терминал на macOS или Linux или PowerShell в Windows. Перейдите в извлечённый каталог маркетплейса, затем выполните:

codex plugin marketplace add .

Вы также можете указать команде абсолютный путь, не меняя каталог:

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

Пример для PowerShell:

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

3. Установите плагин

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

Убедитесь, что Codex видит маркетплейс и плагин:

codex plugin marketplace list
codex plugin list

4. Перезапустите хост

Полностью закройте и снова откройте приложение ChatGPT desktop, затем откройте Каталог плагинов и убедитесь, что X Plane Control установлен и включён. Начните новый чат, чтобы загрузились новый навык и MCP-инструменты.

В Codex CLI начните новый сеанс после установки. Вы также можете ввести /plugins, чтобы просмотреть установленные плагины.

Установка из исходного кода

Используйте этот метод для разработки плагина, изучения исходного кода или самостоятельной сборки релиза.

1. Загрузите репозиторий

Используйте действие GitHub Code → Download ZIP и распакуйте архив или клонируйте репозиторий:

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

Если репозиторий содержит x-plane-control как подкаталог, перейдите в этот каталог перед продолжением. Это каталог, содержащий package.json.

2. Установите зависимости и проверьте проект

npm ci
npm run validate

Проверка выполняет проверку TypeScript, запускает автоматические тесты и создаёт dist/server.mjs.

3. Создайте распространяемый маркетплейс

npm run package:plugin

Это создаст:

release/x-plane-control-marketplace

В этот каталог копируются только среда выполнения плагина, его метаданные маркетплейса, лицензия, навык и документация. Исходные файлы, тесты и зависимости для разработки не требуются установленному плагину.

4. Добавьте и установите локальный маркетплейс

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

Перезапустите ChatGPT desktop или начните новый сеанс Codex CLI.

Подготовка X-Plane

1. Найдите каталоги

Для обычной установки X-Plane файлы находятся здесь:

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

Имя каталога — Resources/plugins, со строчной plugins в текущих установках X-Plane. Плагин также проверяет несколько вариантов написания с заглавной буквы для совместимости.

Не указывайте Resources/plugins в качестве пути установки. Укажите корневой каталог установки X-Plane, который содержит Resources, например:

• macOS: /Applications/X-Plane 12 или /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 и Commands.txt намеренно не включены в этот репозиторий. Загрузка файлов, поставляемых с симулятором, обеспечивает соответствие обнаружения установленной версии X-Plane пользователя. Если локальной установки X-Plane нет, скопируйте оба файла в любой доступный для чтения каталог и укажите их точные пути отдельно.

2. Включите сеть UDP

Откройте экран Settings → Network в X-Plane. Убедитесь, что X-Plane принимает входящие сетевые/UDP-подключения, и запишите его входящий UDP-порт. Стандартный порт X-Plane обычно 49000, но используйте значение, отображаемое вашим симулятором.

Разрешите X-Plane через брандмауэр операционной системы при появлении запроса. Если X-Plane находится на другом компьютере, его брандмауэр должен разрешать входящий UDP-трафик на настроенном порту X-Plane с компьютера, на котором запущен плагин.

3. Загрузите полёт

MCP-сервер может запускаться до X-Plane, а X-Plane инициализирует сеть во время запуска. Для получения надёжных значений DataRef, команд и перемещения подождите, пока воздушное судно и сцена завершат загрузку в полёт.

Во время заставки, главного меню или загрузки полёта:

• зонд состояния может не получить ответа;

• некоторые DataRef'ы могут быть недоступны или содержать значения-заглушки;

• команды могут игнорироваться; и

• запись позиции или DataRef может быть перезаписана процессом загрузки.

Настройка плагина

Конфигурацию можно сохранить в диалоговом режиме, что является самым простым способом, или передать через переменные окружения.

Вариант A: укажите корневой каталог установки X-Plane

Начните новый чат с установленным плагином и скажите:

Используй X Plane Control. Укажи мой каталог установки X-Plane как /Applications/X-Plane 12, затем покажи статус, не изменяя симулятор.

Пример для Windows:

Используй X Plane Control. Укажи мой каталог установки X-Plane как C:\X-Plane 12, затем проверь каталог.

Плагин ищет в корневом каталоге Resources/plugins/DataRefs.txt и Commands.txt. Он проверяет оба файла перед сохранением пути.

Вариант B: укажите два файла каталога

Используйте этот режим, если X-Plane установлен на другом компьютере или файлы каталога хранятся в другом месте:

Используй X Plane Control. Укажи DataRefs.txt как /Users/alice/XPlaneCatalog/DataRefs.txt и Commands.txt как /Users/alice/XPlaneCatalog/Commands.txt, затем покажи статус.

Оба пути должны быть указаны вместе. Файлы могут находиться в разных каталогах. Установка явных путей к каталогам заменяет ранее сохранённый корневой каталог установки; установка корневого каталога установки заменяет ранее сохранённые явные пути.

Настройка UDP-адресата

Для X-Plane на том же компьютере обычно достаточно автоматического обнаружения. Если обнаружение недоступно, плагин возвращается к 127.0.0.1:49000.

Чтобы указать явный адресат:

Настройте X-Plane на хосте 192.168.1.50 через UDP-порт 49000, затем выполните проверку.

Хостом может быть IPv4-адрес или имя хоста, разрешаемое компьютером с плагином. Явное указание хоста рекомендуется, когда X-Plane работает на другом компьютере.

Проверка конфигурации

Спросите:

Используй X Plane Control, чтобы показать полный статус и выполнить проверку симулятора.

Статус включает:

• расположение сохранённого файла конфигурации;

• действующие настройки каталога и сети;

• разрешённые пути к DataRefs.txt и Commands.txt;

• количество распознанных DataRefs и команд;

• был ли целевой симулятор настроен явно, обнаружен по маяку или взят из локального значения по умолчанию; и

• результат чтения DataRef версии X-Plane.

Использование X-Plane на другом компьютере

Встроенный MCP-сервер всегда работает на компьютере с ChatGPT/Codex. X-Plane может работать на этом же компьютере или на другом, доступном по UDP.

Рекомендуемая настройка удалённого компьютера

1. Подключите оба компьютера к одной доверенной локальной сети или частной VPN.

2. Узнайте частный IP-адрес компьютера с X-Plane, например 192.168.1.50.

3. В X-Plane включите входящие сетевые подключения и запишите входящий UDP-порт.

4. Разрешите входящий UDP-трафик на этот порт через брандмауэр компьютера с X-Plane.

5. Скопируйте DataRefs.txt и Commands.txt на компьютер с ChatGPT/Codex, если на нём не установлен X-Plane.

6. Настройте пути к скопированным каталогам.

7. Настройте IP-адрес и UDP-порт компьютера с X-Plane.

8. Загрузите полёт и выполните проверку статуса.

Пример диалога:

Используй X Plane Control. Мой симулятор находится по адресу 192.168.1.50:49000. Мои локальные каталоги: /Users/alice/XPlaneCatalog/DataRefs.txt и /Users/alice/XPlaneCatalog/Commands.txt. Сохрани эту конфигурацию и выполни проверку X-Plane.

Многоадресное обнаружение обычно работает только в пределах одного сегмента локальной сети и может блокироваться изоляцией Wi-Fi, маршрутизаторами, контейнерами или VPN-программным обеспечением. В таких случаях настраивайте хост явно.

Не перенаправляйте UDP-порт X-Plane напрямую с интернет-маршрутизатора. Нативный протокол не шифруется и не аутентифицируется. Для компьютеров в разных местах используйте частную VPN, которая делает машины доступными по частному IP, и ограничьте доступ через брандмауэр только компьютером с плагином.

Начало работы с плагином

После установки или обновления всегда начинайте новый чат или сессию Codex. Прямая инструкция использовать плагин упрощает тестирование при первом запуске:

Используй X Plane Control, чтобы проверить, готовы ли мой симулятор и каталоги. Пока ничего не меняй.

Когда статус станет нормальным, можно использовать обычные запросы на естественном языке.

Чтение состояния симулятора

• «Покажи мои географические координаты и ориентацию.»

• «Прочитай мою индикаторную воздушную скорость, истинную воздушную скорость, курс и барометрическую высоту.»

• «Найди DataRefs для количества топлива и покажи их текущие значения.»

• «Проверь, установлен ли стояночный тормоз.»

Для запроса, в котором не указаны точные DataRefs, модель должна сначала выполнить поиск по каталогу и использовать описания и типы для выбора кандидатов.

Выполнение команд симулятора

• «Найди и выполни команду переключения шасси.»

• «Включи посадочные фары с помощью команды X-Plane.»

• «Поставь симулятор на паузу.»

• «Выполни команду запуска двигателя дважды.»

Команды представляют собой дискретные действия. Текущий сервер отправляет пакеты CMND «команда один раз»; он не реализует удержание команды «начало/конец».

Установка значений

• «Найди доступный для записи DataRef стояночного тормоза, установи его в полностью затянутое положение и прочитай обратно.»

• «Установи коэффициент тяги первого двигателя на 0.5.»

• «Найди доступные для записи DataRefs яркости подсветки приборов для этого запроса и покажи мне кандидатов перед любыми изменениями.»

Описания в DataRefs.txt определяют единицы измерения и допустимые значения. Если единица, элемент массива или желаемое значение неоднозначны, попросите модель показать кандидатов перед записью.

Перемещение воздушного судна

• «Перемести мой самолёт в случайное место в Аризоне.»

• «Телепортируй пользовательское воздушное судно на широту 34.8697, долготу -111.7609, на высоту 5 000 метров над уровнем моря, курс на восток, скорость 60 метров в секунду.»

• «Покажи мою позицию, перемести меня на эти координаты и покажи получившуюся позицию.»

DataRefs географического положения доступны только для чтения. Плагин использует нативный пакет PREL X-Plane для перемещения, а затем запрашивает отдельный образец RPOS, когда это возможно.

Спрашивайте перед любыми изменениями

Если вы хотите сначала проверить выбор модели, скажите об этом явно:

Найди лучшую команду или доступный для записи DataRef для выпуска шасси. Объясни, что ты нашёл, но ничего не выполняй и не записывай, пока я не подтвержу.

Инструменты записи, команд и перемещения помечены как изменяющие операции, поэтому клиент также может отображать запрос на подтверждение или одобрение в зависимости от настроек безопасности.

Доступные инструменты

Текущий высокоуровневый инструмент случайного региона поддерживает arizona. Другие географические местоположения по-прежнему можно использовать через явные широту и долготу с помощью teleport_xplane_aircraft.

Справочник по конфигурации

Сохранённая конфигурация

Диалоговая конфигурация хранится в стандартном каталоге конфигурации пользователя операционной системы:

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

• Linux: $XDG_CONFIG_HOME/x-plane-control/config.json или ~/.config/x-plane-control/config.json, если XDG_CONFIG_HOME не задан

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

Пример:

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

Пример с явными файлами каталога:

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

Используйте либо installationPath, либо пару datarefsPath/commandsPath, но не оба варианта одновременно.

Переменные окружения

Переменные окружения переопределяют сохранённые значения:

Приоритет каталогов:

1. явная пара XPLANE_DATAREFS_PATH и XPLANE_COMMANDS_PATH;

2. XPLANE_HOME; и

3. сохранённая конфигурация каталога или автоматическое обнаружение установки.

XPLANE_HOST, XPLANE_PORT и XPLANE_DISCOVERY_TIMEOUT_MS переопределяют свои сохранённые эквиваленты по отдельности.

Переменные окружения проще всего использовать с Codex CLI, поскольку CLI наследует окружение оболочки:

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

Настольное приложение, запущенное из Finder, Dock или меню «Пуск», может не наследовать переменные, заданные в терминале. Используйте configure_xplane и сохранённую конфигурацию для настольного приложения, если вы не запускаете его намеренно с контролируемым окружением.

Очистка сохранённых настроек

Попросите плагин очистить отдельные поля:

Очисти сохранённые хост и порт X-Plane, затем покажи действующую цель без проверки.

Чтобы вернуться от явных файлов к автоматическому обнаружению установки:

Очисти оба сохранённых пути к DataRefs.txt и Commands.txt, затем покажи статус каталога.

Два явных пути к каталогам всегда должны настраиваться или очищаться вместе.

Поведение и ограничения

UDP-записи не подтверждаются

Нативные дейтаграммы DREF, CMND и PREL X-Plane не возвращают подтверждений об успехе. Успешный результат инструмента означает, что дейтаграмма была отправлена, а не то, что X-Plane принял изменение.

Когда проверка важна, попросите модель прочитать DataRef или позицию после этого. Обратное чтение — это отдельное наблюдение, и на него всё ещё могут влиять потери UDP или поведение симулятора.

UDP неупорядочен и ненадёжен

Пакеты могут теряться, дублироваться, задерживаться или приходить не по порядку. Плагин использует таймауты для чтения и сообщает об отсутствующих значениях. Он не обеспечивает транзакционную семантику для множественных записей.

Поддерживается только запись числовых скаляров

Текущий инструмент DREF записывает конечные числовые значения. Нативные массивы и строки должны обрабатываться по одному индексированному числовому элементу за раз, например:

sim/example/array_dataref[0]

Чтение и запись целых массивов и строк не реализованы.

Значения RREF — float32

X-Plane возвращает значения подписки RREF как 32-битные числа с плавающей запятой, даже если каталог описывает DataRef как целое число или double. Небольшие различия в точности ожидаемы.

Каталоги не гарантируют доступность во время выполнения

DataRefs.txt описывает базовый каталог X-Plane. Воздушные суда и сторонние плагины могут создавать дополнительные DataRefs или команды во время выполнения. Эти пользовательские записи могут отсутствовать в базовых файлах.

Инструменты имеют запасной вариант allowUnlisted, но модель должна использовать его только тогда, когда точный пользовательский путь был определён из доверенного источника воздушного судна/плагина. Не следует угадывать незарегистрированное имя.

Доступность для записи не означает, что каждое воздушное судно учтёт значение

DataRef, помеченный как доступный для записи, всё равно может контролироваться или перезаписываться активным воздушным судном, автопилотом, моделью полёта или другим плагином. Некоторые DataRefs имеют смысл только для конкретных воздушных судов или состояний симулятора.

Единицы измерения берутся из каталога

Одни только имена не всегда показывают, является ли значение градусами, радианами, узлами, метрами в секунду, футами, метрами, коэффициентом или перечислением. Модель должна изучить описание в каталоге и запросить уточнение, когда предполагаемая единица измерения неясна.

Несколько экземпляров X-Plane

Обнаружение по маяку возвращает первый допустимый экземпляр, который оно услышит. Настройте явные хост и порт, когда присутствует более одного симулятора.

Устранение неполадок

codex: command not found

Установите или обновите Codex CLI, откройте новый терминал и подтвердите:

codex --version
codex plugin --help

Текущий CLI должен предоставлять команды codex plugin. Официальную документацию по плагинам OpenAI см. для поддерживаемых способов установки.

Маркетплейс или плагин не отображается

Выполните:

codex plugin marketplace list
codex plugin list

Убедитесь, что:

• x-plane-control-local отображается как маркетплейс;

• x-plane-control присутствует в списке плагинов;

• вы добавили каталог, содержащий .agents/plugins/marketplace.json, а не внутренний каталог плагина;

• приложение ChatGPT desktop было полностью перезапущено; и

• после установки вы начали новый чат.

Администраторы рабочей области могут ограничивать локальные плагины. Если маркетплейс распознаётся CLI, но недоступен в приложении, проверьте политику учётной записи или рабочей области.

Плагин установлен, но его MCP-сервер не запускается

Проверьте Node.js в терминале:

node --version

На macOS или Linux также выполните:

command -v node

На Windows:

Get-Command node

Встроенный .mcp.json запускает node, поэтому он должен быть виден в PATH хоста. Если Node доступен только после загрузки профиля оболочки, установите Node системно с помощью стандартного установщика или настройте наследование правильного PATH настольным приложением, затем полностью перезапустите приложение.

Чтобы проверить упакованный сервер вручную, выполните следующее из каталога маркетплейса:

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

Исправный stdio-сервер молча ожидает MCP-сообщения; нажмите Ctrl+C, чтобы остановить его. Разработчики могут запустить автоматический тест рукопожатия с помощью npm run smoke:stdio из исходного каталога.

Каталог не найден

Запросите статус без зондирования X-Plane:

Покажи статус X Plane Control с отключённым зондированием, включая разрешённые пути к каталогам.

Проверьте, что:

• путь установки указывает на корень X-Plane, а не на Resources/plugins;

• оба файла существуют внутри <root>/Resources/plugins;

• явные пути к файлам указывают на сами файлы;

• оба явных пути были настроены вместе;

• хост плагина имеет разрешение на чтение обоих файлов; и

• переменные окружения не переопределяют сохранённую конфигурацию.

Если X-Plane находится на другом компьютере, скопируйте оба файла на компьютер с плагином и настройте эти копии.

Тайм-аут UDP-зондирования

Проверьте следующее по порядку:

1. X-Plane запущен, и загрузка воздушного судна завершена.

2. X-Plane принимает входящие сетевые подключения.

3. Настроенный UDP-порт соответствует сетевым настройкам X-Plane.

4. Настроенный хост — это текущий IP-адрес компьютера с X-Plane.

5. Брандмауэр операционной системы разрешает трафик.

6. Оба компьютера могут связаться друг с другом в одной локальной сети или частной VPN.

7. Изоляция клиентов отключена в Wi-Fi сети.

8. Если многоадресное обнаружение не может пересечь границу сети, настроен явный хост.

Отправка UDP-датаграммы может выглядеть успешной, даже если симулятор не слушает порт. Используйте зонд версии или чтение DataRef для установления доступности.

Команда или запись показывает «отправлено», но ничего не меняется

Возможные причины:

• полёт всё ещё загружается;

• потеря UDP-пакетов;

• значение DataRef использует другие единицы или перечисление;

• выбран неверный индекс массива;

• активное воздушное судно или другой плагин немедленно перезаписали значение;

• команда неприменима к активному воздушному судну; или

• настроенный каталог не соответствует запущенной версии X-Plane.

Попросите модель прочитать значение обратно и показать выбранную запись каталога. Для дискретного действия в кабине попросите её найти точную команду вместо принудительной записи DataRef.

Команда или DataRef аддона отсутствует

Стандартные файлы каталога не обязательно содержат динамически регистрируемые элементы управления аддонов. Обратитесь к документации воздушного судна или плагина за точным путём. Затем попросите модель использовать это точное не указанное в списке имя и объяснить, почему переопределение уместно.

Значения выглядят округлёнными или слегка отличаются

RREF возвращает значения float32. Точность может быть ниже базового типа DataRef, и X-Plane может обновлять значения между отдельными чтениями.

Обновление или удаление

Обновление загруженного локального пакета

1. Скачайте и распакуйте новый релиз.

2. Удалите старую установленную копию:

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

3. Если новый пакет находится в другом каталоге, замените регистрацию маркетплейса:

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

4. Установите плагин снова:

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

5. Перезапустите ChatGPT desktop и начните новый чат.

Сохранённые настройки X-Plane Control находятся вне кэша плагинов, поэтому переустановка плагина обычно не удаляет сохранённую конфигурацию симулятора/каталога.

Удаление

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

Эти команды удаляют установленный плагин и регистрацию маркетплейса. Они не удаляют отдельно сохранённый config.json X-Plane Control. Удалите этот файл вручную только в том случае, если вы также хотите стереть сохранённые пути и сетевой целевой адрес.

Разработка

Часто используемые команды

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

• npm run check — проверка типов исходного кода TypeScript.

• npm test — запуск тестов пакетов, каталога, конфигурации и фейкового X-Plane.

• npm run build — сборка сервера в dist/server.mjs.

• npm run smoke:stdio — запуск собранного сервера и выполнение теста рукопожатия/списка инструментов MCP.

• npm run package:plugin — проверка, упаковка и smoke-тестирование распространяемого плагина.

Структура проекта

.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

Необязательный диагностический HTTP-транспорт

Обычный плагин использует stdio. Петлевой HTTP-транспорт сохранён для локальной диагностики протокола:

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

Конечные точки:

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

• Проверка работоспособности: http://127.0.0.1:8765/health

Этот слушатель не требует аутентификации и должен оставаться привязанным к петлевому интерфейсу. Не открывайте его публично.

Примечания по распространению

Публикация этого репозитория на GitHub позволяет пользователям скачивать и устанавливать локальный пакет маркетплейса. Это не автоматически добавляет плагин в универсальный публичный каталог плагинов OpenAI.

Издание для GitHub/локального маркетплейса намеренно является пакетным stdio-плагином, поскольку ему требуется доступ к локальным файлам каталога и симулятору в сети пользователя. Публичный путь подачи плагинов OpenAI обычно предполагает продакшн-сервис MCP на стабильной HTTPS-конечной точке с соответствующей аутентификацией и проверкой. Это была бы отдельная архитектура и канал выпуска.

Перед созданием релиза на GitHub:

1. Обновите версию и публичные метаданные автора/репозитория в .codex-plugin/plugin.json и package.json.

2. Выполните npm ci.

3. Выполните npm run package:plugin.

4. Протестируйте сгенерированный каталог release/x-plane-control-marketplace на чистой учётной записи или машине.

5. Заархивируйте этот каталог как ресурс релиза, сохранив .agents/plugins/marketplace.json.

6. Опубликуйте исходный код и архив релиза под включённой лицензией MIT.

Конфиденциальность и безопасность

• MCP-сервер и UDP-клиент X-Plane работают локально.

• Этому серверу не требуется ключ API OpenAI.

• Учётные данные X-Plane не используются.

• Сохранённая конфигурация содержит пути файловой системы и, опционально, имя хоста/IP и порт симулятора.

• UDP-трафик X-Plane не шифруется и не аутентифицируется.

• Файлы каталога читаются локально и используются для поиска и метаданных безопасности.

• Плагин может изменять состояние симулятора, поэтому проверяйте одобрения инструментов и используйте его только с симулятором, которым вам разрешено управлять.

Технические ссылки

• Справочник DataRefs X-Plane

• Документация доступа к данным SDK X-Plane

• Обзор протокола вывода данных UDP X-Plane

• Заметки о протоколе XPlaneConnector

• Документация UDP XPPython3

• Документация по плагинам OpenAI

• Руководство по упаковке плагинов OpenAI

• Спецификация Model Context Protocol

Лицензия

MIT. См. LICENSE.