Skip to main content
Glama
X-Plane Control

X-Plane Control

by josvisser66

X-Plane Control

通过自然语言请求,从 ChatGPT 或 Codex 控制和检查 X-Plane 飞行模拟器。

X-Plane Control 是一个跨平台插件,包含一个捆绑的本地 Model Context Protocol (MCP) 服务器。MCP 服务器让模型能够搜索 X-Plane 自带的 DataRefs.txt 和 Commands.txt 目录,读取实时模拟器数据,更改可写值,执行模拟器命令,并通过 X-Plane 的原生 UDP 协议重新定位飞机。

示例请求:

  • “把我的飞机移动到亚利桑那州的随机位置。”

  • “显示我当前的位置、指示空速、高度和航向。”

  • “找到放下起落架的正确命令,然后执行它。”

  • “设置驻车制动并验证其状态。”

  • “查找与仪表灯相关的可写 DataRef。”

模型不需要硬编码的 X-Plane 控制列表。它会搜索属于你的 X-Plane 版本的目录,选择适当的命令或可写 DataRef,并调用相应的 MCP 工具。

[!WARNING] 本项目仅用于飞行模拟器。不适用于真实飞机操作、导航或训练决策。命令和写入操作可以立即改变模拟飞机。请将 X-Plane 的未认证 UDP 接口保留在受信任的计算机或专用网络上。

目录

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 在同一个局域网内的另一台游戏 PC 上运行。

服务器作为 Node.js 进程在本地运行。它不会安装 X-Plane 二进制插件、修改模拟器、需要 Python、需要 PyYAML,也不会通过托管服务发送模拟器流量。

功能特性

  • 在 macOS、Linux 和 Windows 上运行,需要 Node.js 20 或更高版本。

  • 将完整的 MCP 运行时捆绑到单个 dist/server.mjs 文件中。

  • 搜索用户自己的 X-Plane DataRef 和命令目录。

  • 使用 X-Plane 安装根目录或两个显式选择的目录文件。

  • 自动检测几种常见的 X-Plane 11 和 12 安装位置。

  • 在可能的情况下,通过多播信标自动发现 X-Plane。

  • 支持显式的主机和端口,用于远程计算机、VPN 以及多播不可用的网络。

  • 使用 RREF 读取标量值。

  • 使用 DREF 写入数值标量值。

  • 使用 CMND 执行精确命令。

  • 通过 RPOS 读取地理位置、姿态、速度和旋转。

  • 通过 PREL 重新定位飞机,而不是尝试写入只读的地理 DataRef。

  • 包含一个高级工具,用于在亚利桑那州选择随机内部点。

  • 拒绝目录中标记为只读的 DataRef。

  • 默认拒绝未知的 DataRef 和命令。

  • 对于与退出、重置、回放、故障、火灾或坠毁相关的命令名称,需要显式覆盖。

系统要求

适用于所有人

  • X-Plane 11 或 X-Plane 12。

  • 运行 ChatGPT 或 Codex 的计算机上需要 Node.js 20 或更高版本。

  • 受支持的本地插件宿主:

    • 支持插件的 ChatGPT 桌面版,或

    • Codex CLI。

  • 来自你要控制的 X-Plane 版本的 DataRefs.txt 和 Commands.txt 文件。

安装前检查 Node.js:

node --version

结果必须以 v20、v21、v22 或更高版本开头。打包版本不需要 npm、TypeScript、Python 或单独的依赖安装。

node 可执行文件必须通过 PATH 对插件宿主可用。标准的 Node.js 安装程序通常是 macOS 和 Windows 上最简单的选择。如果 Node 仅通过特定 shell 的版本管理器(如 nvm)安装,请参阅插件已安装但其 MCP 服务器无法启动。

从源码构建时的额外要求

  • npm,随 Node.js 提供。

  • Git,如果克隆而不是以 ZIP 存档形式下载仓库。

受支持的 ChatGPT 和 Codex 界面

本仓库分发一个带有捆绑 stdio MCP 服务器的本地市场插件。

  • ChatGPT 桌面版: 在本地插件可用的地方受支持。

  • Codex CLI: 受支持。添加市场后,输入 /plugins 使用插件浏览器。

  • Codex IDE 扩展: 不受支持,因为 IDE 扩展目前不支持插件。

  • ChatGPT 网页版和移动版: 它们无法直接启动这台计算机的捆绑 stdio 服务器。这些界面需要单独托管和发布的版本。

这种本地市场安装通常不需要 ChatGPT 开发者模式或公共 HTTPS 端点。开发者模式用于注册和测试远程 MCP 服务器连接;此包改为从 .mcp.json 在本地启动自己的 MCP 服务器。账户或工作区策略仍可能限制插件的可用性。

有关当前的插件可用性和安装以及插件打包,请参阅官方 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 上打开终端,或在 Windows 上打开 PowerShell。切换到解压后的市场目录,然后运行:

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 桌面应用,然后打开插件目录并确认 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 桌面版或开始新的 Codex CLI 会话。

准备 X-Plane

1. 定位目录

对于正常的 X-Plane 安装,文件位于:

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

目录名是 Resources/plugins,当前 X-Plane 安装中使用小写的 plugins。插件也会检查几种大小写变体以保持兼容性。

不要将 Resources/plugins 配置为安装路径。请配置包含 Resources 的 X-Plane 安装根目录,例如:

  • 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 网络

打开 X-Plane 的 Settings → Network 屏幕。确保 X-Plane 接受传入的网络/UDP 连接,并记下其入站 UDP 端口。标准 X-Plane 端口通常是 49000,但请使用模拟器显示的值。

在提示时允许 X-Plane 通过操作系统防火墙。当 X-Plane 在另一台计算机上时,其防火墙必须允许从运行插件的计算机向配置的 X-Plane 端口传入 UDP 流量。

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。

要设置显式目标:

在主机 192.168.1.50 的 UDP 端口 49000 上配置 X-Plane,然后探测它。

主机可以是 IPv4 地址,也可以是插件计算机可解析的主机名。当 X-Plane 运行在另一台计算机上时,建议使用显式主机。

验证配置

询问:

使用 X Plane Control 显示完整状态并探测模拟器。

状态包括:

  • 已保存配置文件的位置;

  • 生效的目录和网络设置;

  • 解析后的 DataRefs.txt 和 Commands.txt 路径;

  • 解析出的 DataRef 和命令数量;

  • 目标是手动配置的、通过信标发现的,还是取自 localhost 默认值;以及

  • 读取 X-Plane 版本 DataRef 的结果。

在另一台计算机上使用 X-Plane

捆绑的 MCP 服务器始终运行在 ChatGPT/Codex 计算机上。X-Plane 可以运行在该计算机上,也可以运行在可通过 UDP 访问的另一台计算机上。

推荐的远程计算机设置

  1. 将两台计算机连接到同一个受信任的局域网或私有 VPN。

  2. 找到 X-Plane 计算机的私有 IP 地址,例如 192.168.1.50。

  3. 在 X-Plane 中启用传入网络连接,并记下入站 UDP 端口。

  4. 在 X-Plane 计算机的防火墙中允许到该端口的入站 UDP 流量。

  5. 如果 ChatGPT/Codex 计算机未安装 X-Plane,请将 DataRefs.txt 和 Commands.txt 复制到该计算机。

  6. 配置复制过来的目录路径。

  7. 配置 X-Plane 计算机的 IP 地址和 UDP 端口。

  8. 加载一个飞行并运行状态探测。

示例对话:

使用 X Plane Control。我的模拟器位于 192.168.1.50:49000。我的本地目录是 /Users/alice/XPlaneCatalog/DataRefs.txt 和 /Users/alice/XPlaneCatalog/Commands.txt。保存该配置并探测 X-Plane。

多播发现通常只在同一本地网段内有效,并且可能被 Wi-Fi 隔离、路由器、容器或 VPN 软件阻止。在这些情况下,请显式配置主机。

不要直接从互联网路由器转发 X-Plane 的 UDP 端口。原生协议未加密、未认证。对于位于不同地点的计算机,请使用私有 VPN 使各机器可通过私有 IP 访问,并将防火墙访问限制为仅允许插件计算机。

开始使用插件

安装或更新后,始终启动新的聊天或 Codex 会话。直接指示使用插件可让首次运行测试更简单:

使用 X Plane Control 检查我的模拟器和目录是否就绪。暂时不要更改任何内容。

状态正常后,即可使用普通的自然语言请求。

读取模拟器状态

  • “显示我的地理位置和姿态。”

  • “读取我的指示空速、真空速、航向和气压高度。”

  • “查找燃油量的 DataRef,并显示它们的当前值。”

  • “检查停车刹车是否已设置。”

对于未指定确切 DataRef 的请求,模型应首先搜索目录,并利用描述和类型来选择候选。

执行模拟器命令

  • “查找并执行切换起落架的命令。”

  • “使用 X-Plane 命令打开着陆灯。”

  • “暂停模拟器。”

  • “执行启动器命令两次。”

命令表示离散操作。当前服务器发送 CMND 单次命令数据包;它不实现命令开始/命令结束的持续按住。

设置值

  • “查找一个可写的停车刹车 DataRef,将其设置为完全接合,然后读回。”

  • “将第一台发动机的油门比率设置为 0.5。”

  • “为此请求查找可写的仪表灯亮度 DataRef,并在更改任何内容之前向我显示候选。”

DataRefs.txt 中的描述定义了单位和有效含义。如果单位、数组元素或期望值不明确,请在写入前让模型显示候选。

移动飞机

  • “把我的飞机移动到亚利桑那州的随机位置。”

  • “将用户飞机传送到纬度 34.8697、经度 -111.7609,海拔 5,000 米 MSL,以每秒 60 米的速度向东飞行。”

  • “显示我的位置,将我移动到这些坐标,并显示结果位置。”

地理位置 DataRef 是只读的。插件使用 X-Plane 的原生 PREL 数据包进行重定位,然后在可能时请求单独的 RPOS 采样。

更改任何内容前先询问

如果你想先检查模型的选择,请明确说明:

找到放下起落架的最佳命令或可写 DataRef。解释你找到的内容,但在确认之前不要执行或写入任何内容。

写入、命令和重定位工具被标记为变更操作,因此客户端也可能根据其安全设置显示确认或批准提示。

可用工具

工具

用途

是否更改 X-Plane?

get_xplane_status

显示生效配置、目录状态、目标选择,并可选择探测模拟器。

否

configure_xplane

保存目录路径、安装根目录、主机、端口或发现超时。

仅保存本地配置

search_xplane_catalog

按路径或描述搜索 DataRef 和命令;可选择仅返回可写的 DataRef。

否

read_xplane_datarefs

使用 RREF 读取最多 32 个标量或索引值。

否

write_xplane_datarefs

使用 DREF 发送最多 32 个数值更新。

是

execute_xplane_command

使用 CMND 执行精确命令,可选择多次执行。

是

get_xplane_position

使用 RPOS 读取位置、姿态、速度和旋转。

否

teleport_xplane_aircraft

使用 PREL 将飞机重定位到明确的经纬度坐标。

是

move_xplane_aircraft_random

在受支持的区域中选择一个随机点,并重定位用户飞机。

是

当前的高级随机区域工具支持 arizona。其他地理位置仍可通过 teleport_xplane_aircraft 使用明确的纬度和经度。

配置参考

已保存的配置

对话配置存储在操作系统常规的每用户配置目录中:

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

  • Linux:$XDG_CONFIG_HOME/x-plane-control/config.json,或当 XDG_CONFIG_HOME 未设置时为 ~/.config/x-plane-control/config.json

  • 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 对,不要同时使用两者。

环境变量

环境变量覆盖已保存的值:

变量

含义

XPLANE_HOME

包含 Resources/plugins 的 X-Plane 安装根目录

XPLANE_DATAREFS_PATH

DataRefs.txt 的精确路径;需要 XPLANE_COMMANDS_PATH

XPLANE_COMMANDS_PATH

Commands.txt 的精确路径;需要 XPLANE_DATAREFS_PATH

XPLANE_HOST

模拟器主机名或 IP 地址

XPLANE_PORT

模拟器的入站 UDP 端口,范围 1 到 65535

XPLANE_DISCOVERY_TIMEOUT_MS

多播发现超时,范围 100 到 30000 毫秒

XPLANE_CONTROL_CONFIG_PATH

备用的已保存配置文件路径

目录优先级为:

  1. 显式的 XPLANE_DATAREFS_PATH 和 XPLANE_COMMANDS_PATH 对;

  2. XPLANE_HOME;以及

  3. 已保存的目录配置或自动安装检测。

XPLANE_HOST、XPLANE_PORT 和 XPLANE_DISCOVERY_TIMEOUT_MS 分别覆盖对应的已保存值。

环境变量在 Codex CLI 中最容易使用,因为 CLI 会继承 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

从 Finder、Dock 或开始菜单启动的桌面应用可能不会继承在终端中设置的变量。对于桌面应用,请使用 configure_xplane 和已保存的配置,除非你特意在受控环境中启动它。

清除已保存的设置

让插件清除单个字段:

清除已保存的 X-Plane 主机和端口,然后在不探测的情况下显示生效目标。

要从显式文件切换回自动安装检测:

清除已保存的 DataRefs.txt 和 Commands.txt 路径,然后显示目录状态。

两个显式目录路径必须始终一起配置或一起清除。

行为和限制

UDP 写入不返回确认

X-Plane 的原生 DREF、CMND 和 PREL 数据报不会返回成功确认。工具结果成功仅表示数据报已发送,并不表示 X-Plane 接受了更改。

当验证很重要时,请让模型随后读取 DataRef 或位置。读回是独立的观测,仍可能受到 UDP 丢失或模拟器行为的影响。

UDP 无序且不可靠

数据包可能丢失、重复、延迟或乱序到达。插件对读取使用超时,并报告缺失值。它不提供跨多次写入的事务语义。

仅支持数值标量写入

当前的 DREF 工具写入有限的数值。原生数组和字符串必须一次处理一个带索引的数值元素,例如:

sim/example/array_dataref[0]

未实现整个数组和字符串的读取/写入。

RREF 值是 float32

X-Plane 以 32 位浮点数返回 RREF 订阅值,即使目录将 DataRef 描述为整数或双精度浮点数。出现较小的精度差异是正常的。

目录不保证运行时可用性

DataRefs.txt 描述 X-Plane 的基础目录。飞机和第三方插件可以在运行时创建额外的 DataRef 或命令。这些自定义条目可能不会出现在基础文件中。

工具提供了 allowUnlisted 逃生通道,但模型只有在从可信的飞机/插件来源识别出精确的自定义路径时才应使用它。绝不应猜测未列出的名称。

可写并不意味着每架飞机都会遵循该值

标记为可写的 DataRef 仍可能被当前飞机、自动驾驶仪、飞行模型或其他插件控制或覆盖。某些 DataRef 仅对特定飞机或模拟器状态有意义。

单位来自目录

仅凭名称并不总能揭示值是度、弧度、节、米每秒、英尺、米、比率还是枚举。模型应检查目录描述,并在预期单位不明确时请求澄清。

多个 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 桌面应用已完全重启;且

  • 安装后你开启了新的对话。

工作区管理员可以限制本地插件。如果 CLI 能识别市场但应用内不可用,请检查账户或工作区策略。

插件已安装但其 MCP 服务器无法启动

在终端中检查 Node.js:

node --version

在 macOS 或 Linux 上,还需运行:

command -v node

在 Windows 上:

Get-Command node

捆绑的 .mcp.json 会启动 node,因此它必须对主机的 PATH 可见。如果 Node 仅在 shell 配置文件加载后才可用,请使用标准安装程序在系统范围内安装 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. 配置的主机是 X-Plane 计算机当前的 IP 地址。

  5. 操作系统防火墙允许该流量通过。

  6. 两台计算机在同一个局域网或私有 VPN 上可以互相访问。

  7. 无线网络上已禁用客户端隔离。

  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 桌面应用并开启新对话。

已保存的 X-Plane Control 设置位于插件缓存之外,因此重新安装插件通常不会删除已保存的模拟器/目录配置。

卸载

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

这些命令会删除已安装的插件和市场注册。它们不会删除单独保存的 X-Plane Control config.json。只有当你也想擦除已保存的路径和网络目标时,才手动删除该文件。

开发

常用命令

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 验证、打包并对可分发的插件进行冒烟测试。

项目结构

.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 的公共插件提交路径通常期望一个在稳定的 HTTPS 端点上运行、带有适当身份验证并通过审核的生产级 MCP 服务。那将是一个独立的架构和发布渠道。

在创建 GitHub release 之前:

  1. 更新 .codex-plugin/plugin.json 和 package.json 中的版本及公开作者/仓库元数据。

  2. 运行 npm ci。

  3. 运行 npm run package:plugin。

  4. 在干净的账户或机器上测试生成的 release/x-plane-control-marketplace 目录。

  5. 将该目录打包为 release 资产,并保留 .agents/plugins/marketplace.json。

  6. 在随附的 MIT 许可证下发布源码和 release 归档。

隐私与安全

  • MCP 服务器和 X-Plane UDP 客户端在本地运行。

  • 此服务器不需要 OpenAI API 密钥。

  • 不使用任何 X-Plane 凭据。

  • 已保存的配置包含文件系统路径,以及可选的模拟器主机名/IP 和端口。

  • X-Plane UDP 流量未加密且未经身份验证。

  • 目录文件在本地读取,用于搜索和安全元数据。

  • 插件可以更改模拟器状态,因此请审查工具批准,并且只对你有权控制的模拟器使用它。

技术参考

许可证

MIT。参见 LICENSE。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers