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 接口保留在受信任的计算机或专用网络上。

目录

• 工作原理

• 功能特性

• 系统要求

• 安装预构建版本

• 从源码安装

• 准备 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 在同一个局域网内的另一台游戏 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。解释你找到的内容，但在确认之前不要执行或写入任何内容。

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

可用工具

当前的高级随机区域工具支持 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 对，不要同时使用两者。

环境变量

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

目录优先级为：

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 流量未加密且未经身份验证。

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

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

技术参考

• X-Plane DataRefs 参考

• X-Plane SDK 数据访问文档

• X-Plane UDP 数据输出协议概述

• XPlaneConnector 协议说明

• XPPython3 UDP 文档

• OpenAI 插件文档

• OpenAI 插件打包指南

• 模型上下文协议规范

许可证

MIT。参见 LICENSE。