# X-Plane Control

Control and inspect an X-Plane flight simulator from ChatGPT or Codex using natural-language requests.

X-Plane Control is a cross-platform plugin containing a bundled, local [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server. The MCP server lets the model search X-Plane's own `DataRefs.txt` and `Commands.txt` catalogs, read live simulator data, change writable values, execute simulator commands, and relocate the aircraft through X-Plane's native UDP protocol.

Example requests:

- “Move my plane to a random location in Arizona.”
- “Show my current position, indicated airspeed, altitude, and heading.”
- “Find the correct command to lower the landing gear, then execute it.”
- “Set the parking brake and verify its state.”
- “Find writable DataRefs related to the instrument lights.”

The model does not need a hard-coded list of every X-Plane control. It searches the catalog that belongs to your X-Plane version, selects an appropriate command or writable DataRef, and calls the corresponding MCP tool.

> [!WARNING]
> This project is for flight-simulator use only. It is not intended for real-aircraft operation, navigation, or training decisions. Commands and writes can immediately change the simulated aircraft. Keep X-Plane's unauthenticated UDP interface on a trusted computer or private network.

## Contents

- [How it works](#how-it-works)
- [Features](#features)
- [Requirements](#requirements)
- [Install a prebuilt release](#install-a-prebuilt-release)
- [Install from source](#install-from-source)
- [Prepare X-Plane](#prepare-x-plane)
- [Configure the plugin](#configure-the-plugin)
- [Use X-Plane on another computer](#use-x-plane-on-another-computer)
- [Start using the plugin](#start-using-the-plugin)
- [Available tools](#available-tools)
- [Configuration reference](#configuration-reference)
- [Behavior and limitations](#behavior-and-limitations)
- [Troubleshooting](#troubleshooting)
- [Update or uninstall](#update-or-uninstall)
- [Development](#development)
- [Distribution notes](#distribution-notes)
- [Technical references](#technical-references)

## How it works

```text
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
```

The plugin has two independent inputs:

1. **A catalog** — `DataRefs.txt` and `Commands.txt` tell the model which controls exist, what they mean, and which DataRefs are writable.
2. **A network target** — an IP address and UDP port identify the running X-Plane simulator.

The catalog and simulator do not have to be on the same computer. For example, ChatGPT can run the plugin on a laptop using copied catalog files while X-Plane runs on a separate gaming PC on the same LAN.

The server runs locally as a Node.js process. It does not install an X-Plane binary plugin, modify the simulator, require Python, require PyYAML, or send simulator traffic through a hosted service.

## Features

- Runs on macOS, Linux, and Windows with Node.js 20 or newer.
- Bundles the complete MCP runtime into a single `dist/server.mjs` file.
- Searches the user's own X-Plane DataRef and command catalogs.
- Uses an X-Plane installation root or two explicitly selected catalog files.
- Auto-detects several common X-Plane 11 and 12 installation locations.
- Auto-discovers X-Plane from its multicast beacon when possible.
- Supports an explicit host and port for remote computers, VPNs, and networks where multicast is unavailable.
- Reads scalar values with `RREF`.
- Writes numeric scalar values with `DREF`.
- Executes exact commands with `CMND`.
- Reads geographic position, attitude, velocity, and rotation through `RPOS`.
- Relocates an aircraft through `PREL` rather than attempting to write read-only geographic DataRefs.
- Includes a high-level tool that selects a random interior point in Arizona.
- Rejects catalog DataRefs marked read-only.
- Rejects unknown DataRefs and commands by default.
- Requires an explicit override for command names associated with quitting, resetting, replay, failures, fire, or crashes.

## Requirements

### For everyone

- X-Plane 11 or X-Plane 12.
- [Node.js](https://nodejs.org/) 20 or newer on the computer running ChatGPT or Codex.
- A supported local plugin host:
  - ChatGPT desktop with plugin support, or
  - Codex CLI.
- The `DataRefs.txt` and `Commands.txt` files from the X-Plane version you want to control.

Check Node.js before installing:

```sh
node --version
```

The result must begin with `v20`, `v21`, `v22`, or a later version. A packaged release does not require `npm`, TypeScript, Python, or a separate dependency installation.

The `node` executable must be available to the plugin host through `PATH`. The standard Node.js installer is generally the easiest choice on macOS and Windows. If Node was installed only through a shell-specific version manager such as `nvm`, see [The plugin is installed but its MCP server will not start](#the-plugin-is-installed-but-its-mcp-server-will-not-start).

### Additional requirements when building from source

- `npm`, supplied with Node.js.
- Git, if cloning rather than downloading the repository as a ZIP archive.

## Supported ChatGPT and Codex surfaces

This repository distributes a **local marketplace plugin with a bundled stdio MCP server**.

- **ChatGPT desktop:** supported where local plugins are available.
- **Codex CLI:** supported. Enter `/plugins` to use the plugin browser after adding the marketplace.
- **Codex IDE extension:** not supported because the IDE extension does not currently support plugins.
- **ChatGPT web and mobile:** they cannot directly launch this computer's bundled stdio server. A separately hosted and published edition would be needed for those surfaces.

This local marketplace installation normally does **not** require ChatGPT Developer Mode or a public HTTPS endpoint. Developer Mode is used when registering and testing remote MCP server connections; this package instead launches its own MCP server locally from `.mcp.json`. Account or workspace policies can still restrict plugin availability.

See the official OpenAI documentation for current [plugin availability and installation](https://learn.chatgpt.com/docs/plugins) and [plugin packaging](https://developers.openai.com/plugins/build/plugins).

## Install a prebuilt release

This is the recommended installation method for most users.

### 1. Download and extract the bundle

Download the latest release archive from this repository's **Releases** page and extract it. Open the extracted `x-plane-control-marketplace` directory.

If you downloaded the entire repository instead of a release archive, the prebuilt marketplace is located at:

```text
release/x-plane-control-marketplace
```

The correct marketplace directory contains both of these paths:

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

Dot-prefixed directories such as `.agents` may be hidden in Finder or File Explorer. They do not need to be made visible for the terminal commands to work.

### 2. Add the downloaded marketplace

Open Terminal on macOS or Linux, or PowerShell on Windows. Change to the extracted marketplace directory, then run:

```sh
codex plugin marketplace add .
```

You can also give the command an absolute path without changing directories:

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

PowerShell example:

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

### 3. Install the plugin

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

Confirm that Codex can see the marketplace and plugin:

```sh
codex plugin marketplace list
codex plugin list
```

### 4. Restart the host

Fully quit and reopen the ChatGPT desktop app, then open the Plugins Directory and confirm that **X Plane Control** is installed and enabled. Start a new chat so the new skill and MCP tools are loaded.

In Codex CLI, start a new session after installation. You can also enter `/plugins` to review installed plugins.

## Install from source

Use this method to develop the plugin, inspect the source, or build a release yourself.

### 1. Download the repository

Use GitHub's **Code → Download ZIP** action and extract the archive, or clone the repository:

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

If the repository contains `x-plane-control` as a subdirectory, change into that directory before continuing. It is the directory containing `package.json`.

### 2. Install dependencies and validate the project

```sh
npm ci
npm run validate
```

Validation performs a TypeScript check, runs the automated tests, and creates `dist/server.mjs`.

### 3. Create the distributable marketplace

```sh
npm run package:plugin
```

This creates:

```text
release/x-plane-control-marketplace
```

Only the runtime plugin, its marketplace metadata, license, skill, and documentation are copied into this directory. Source files, tests, and development dependencies are not required by the installed plugin.

### 4. Add and install the local marketplace

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

Restart ChatGPT desktop or start a new Codex CLI session.

## Prepare X-Plane

### 1. Locate the catalogs

For a normal X-Plane installation, the files are here:

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

The directory name is `Resources/plugins`, with a lowercase `plugins` in current X-Plane installations. The plugin also checks a few capitalization variants for compatibility.

Do not configure `Resources/plugins` as the installation path. Configure the **X-Plane installation root** that contains `Resources`, such as:

- macOS: `/Applications/X-Plane 12` or `/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` and `Commands.txt` are intentionally not embedded in this repository. Loading the files supplied with the simulator keeps discovery aligned with the user's installed X-Plane version. If there is no local X-Plane installation, copy both files to any readable directory and configure their exact paths separately.

### 2. Enable UDP networking

Open X-Plane's **Settings → Network** screen. Ensure that X-Plane accepts incoming network/UDP connections and note its inbound UDP port. The standard X-Plane port is commonly `49000`, but use the value shown by your simulator.

Allow X-Plane through the operating-system firewall when prompted. When X-Plane is on another computer, its firewall must permit inbound UDP traffic on the configured X-Plane port from the computer running the plugin.

### 3. Load a flight

The MCP server can start before X-Plane, and X-Plane initializes networking during startup. For reliable DataRef values, commands, and relocation, wait until an aircraft and scenery have finished loading into a flight.

During the splash screen, main menu, or flight loading:

- the status probe might not receive a response;
- some DataRefs may be unavailable or contain placeholder values;
- commands may be ignored; and
- position or DataRef writes may be overwritten by the loading process.

## Configure the plugin

Configuration can be saved conversationally, which is the simplest method, or supplied through environment variables.

### Option A: configure an X-Plane installation root

Start a new chat with the plugin installed and say:

> Use X Plane Control. Configure my X-Plane installation directory as `/Applications/X-Plane 12`, then show the status without changing the simulator.

Windows example:

> Use X Plane Control. Configure my X-Plane installation directory as `C:\X-Plane 12`, then check the catalog.

The plugin looks beneath the root for `Resources/plugins/DataRefs.txt` and `Commands.txt`. It validates both files before saving the path.

### Option B: configure two catalog files

Use this mode if X-Plane is installed on another computer or the catalog files are stored elsewhere:

> Use X Plane Control. Configure DataRefs.txt as `/Users/alice/XPlaneCatalog/DataRefs.txt` and Commands.txt as `/Users/alice/XPlaneCatalog/Commands.txt`, then show the status.

Both paths must be supplied together. The files may be in different directories. Setting explicit catalog paths replaces a previously saved installation root; setting an installation root replaces previously saved explicit paths.

### Configure the UDP target

For X-Plane on the same computer, automatic discovery is usually sufficient. If discovery is unavailable, the plugin falls back to `127.0.0.1:49000`.

To set an explicit target:

> Configure X-Plane at host `192.168.1.50` on UDP port `49000`, then probe it.

The host may be an IPv4 address or a hostname resolvable by the plugin computer. An explicit host is recommended when X-Plane runs on another computer.

### Verify the configuration

Ask:

> Use X Plane Control to show the complete status and probe the simulator.

The status includes:

- the saved configuration-file location;
- the effective catalog and network settings;
- the resolved `DataRefs.txt` and `Commands.txt` paths;
- the number of parsed DataRefs and commands;
- whether the target was configured, discovered from a beacon, or taken from the localhost default; and
- the result of reading X-Plane's version DataRef.

## Use X-Plane on another computer

The bundled MCP server always runs on the ChatGPT/Codex computer. X-Plane may run on that computer or another computer reachable over UDP.

### Recommended remote-computer setup

1. Connect both computers to the same trusted LAN or private VPN.
2. Find the X-Plane computer's private IP address, for example `192.168.1.50`.
3. In X-Plane, enable incoming network connections and note the inbound UDP port.
4. Allow inbound UDP traffic to that port through the X-Plane computer's firewall.
5. Copy `DataRefs.txt` and `Commands.txt` to the ChatGPT/Codex computer if it does not also have X-Plane installed.
6. Configure the copied catalog paths.
7. Configure the X-Plane computer's IP address and UDP port.
8. Load a flight and run the status probe.

Example conversation:

> Use X Plane Control. My simulator is at `192.168.1.50:49000`. My local catalogs are `/Users/alice/XPlaneCatalog/DataRefs.txt` and `/Users/alice/XPlaneCatalog/Commands.txt`. Save that configuration and probe X-Plane.

Multicast discovery normally works only on the same local network segment and may be blocked by Wi-Fi isolation, routers, containers, or VPN software. Configure the host explicitly in those cases.

Do not forward X-Plane's UDP port directly from an internet router. The native protocol is not encrypted or authenticated. For computers in different locations, use a private VPN that makes the machines reachable by private IP, and restrict firewall access to the plugin computer.

## Start using the plugin

After installation or an update, always start a new chat or Codex session. A direct instruction to use the plugin makes first-run testing easier:

> Use X Plane Control to check whether my simulator and catalogs are ready. Do not change anything yet.

Once the status is healthy, ordinary natural-language requests can be used.

### Read simulator state

- “Show my geographic position and attitude.”
- “Read my indicated airspeed, true airspeed, heading, and pressure altitude.”
- “Find the DataRefs for fuel quantity and show their current values.”
- “Check whether the parking brake is set.”

For a request that does not name exact DataRefs, the model should search the catalog first and use the descriptions and types to select candidates.

### Execute simulator commands

- “Find and execute the command to toggle the landing gear.”
- “Turn on the landing lights using an X-Plane command.”
- “Pause the simulator.”
- “Execute the starter command twice.”

Commands represent discrete actions. The current server sends `CMND` command-once packets; it does not implement command-begin/command-end holding.

### Set values

- “Find a writable DataRef for the parking brake, set it to fully engaged, and read it back.”
- “Set the first engine throttle ratio to 0.5.”
- “Find writable instrument-light brightness DataRefs for this request and show me the candidates before changing anything.”

Descriptions in `DataRefs.txt` define units and valid meanings. If a unit, array element, or desired value is ambiguous, ask the model to show the candidates before writing.

### Move the aircraft

- “Move my plane to a random location in Arizona.”
- “Teleport the user aircraft to latitude `34.8697`, longitude `-111.7609`, at 5,000 meters MSL, heading east at 60 meters per second.”
- “Show my position, move me to these coordinates, and show the resulting position.”

Geographic position DataRefs are read-only. The plugin uses X-Plane's native `PREL` packet for relocation and then requests a separate `RPOS` sample when possible.

### Ask before changing anything

If you want to inspect the model's choice first, say so explicitly:

> Find the best command or writable DataRef for lowering the landing gear. Explain what you found, but do not execute or write anything until I confirm.

The write, command, and relocation tools are marked as mutating operations, so the client may also display a confirmation or approval prompt depending on its security settings.

## Available tools

| Tool | Purpose | Changes X-Plane? |
| --- | --- | --- |
| `get_xplane_status` | Show effective configuration, catalog status, target selection, and optionally probe the simulator. | No |
| `configure_xplane` | Save catalog paths, installation root, host, port, or discovery timeout. | Saves local configuration only |
| `search_xplane_catalog` | Search DataRefs and commands by path or description; optionally return only writable DataRefs. | No |
| `read_xplane_datarefs` | Read as many as 32 scalar or indexed values with `RREF`. | No |
| `write_xplane_datarefs` | Send as many as 32 numeric updates with `DREF`. | Yes |
| `execute_xplane_command` | Execute an exact command with `CMND`, optionally multiple times. | Yes |
| `get_xplane_position` | Read position, attitude, velocity, and rotation with `RPOS`. | No |
| `teleport_xplane_aircraft` | Relocate an aircraft to explicit geographic coordinates with `PREL`. | Yes |
| `move_xplane_aircraft_random` | Choose a random point in a supported region and relocate the user aircraft. | Yes |

The current high-level random-region tool supports `arizona`. Other geographic locations can still be used through explicit latitude and longitude with `teleport_xplane_aircraft`.

## Configuration reference

### Saved configuration

Conversational configuration is stored in the operating system's normal per-user configuration directory:

- macOS: `~/Library/Application Support/XPlaneControl/config.json`
- Linux: `$XDG_CONFIG_HOME/x-plane-control/config.json`, or `~/.config/x-plane-control/config.json` when `XDG_CONFIG_HOME` is unset
- Windows: `%APPDATA%\XPlaneControl\config.json`

Example:

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

Explicit catalog-file example:

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

Use either `installationPath` or the `datarefsPath`/`commandsPath` pair, not both.

### Environment variables

Environment variables override saved values:

| Variable | Meaning |
| --- | --- |
| `XPLANE_HOME` | X-Plane installation root containing `Resources/plugins` |
| `XPLANE_DATAREFS_PATH` | Exact path to `DataRefs.txt`; requires `XPLANE_COMMANDS_PATH` |
| `XPLANE_COMMANDS_PATH` | Exact path to `Commands.txt`; requires `XPLANE_DATAREFS_PATH` |
| `XPLANE_HOST` | Simulator hostname or IP address |
| `XPLANE_PORT` | Simulator's inbound UDP port, from 1 through 65535 |
| `XPLANE_DISCOVERY_TIMEOUT_MS` | Multicast discovery timeout, from 100 through 30000 milliseconds |
| `XPLANE_CONTROL_CONFIG_PATH` | Alternate saved configuration-file path |

Catalog precedence is:

1. the explicit `XPLANE_DATAREFS_PATH` and `XPLANE_COMMANDS_PATH` pair;
2. `XPLANE_HOME`; and
3. the saved catalog configuration or automatic installation detection.

`XPLANE_HOST`, `XPLANE_PORT`, and `XPLANE_DISCOVERY_TIMEOUT_MS` override their saved equivalents individually.

Environment variables are easiest with Codex CLI because the CLI inherits the shell environment:

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

PowerShell:

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

A desktop app launched from Finder, the Dock, or the Start menu may not inherit variables set in a terminal. Use `configure_xplane` and the saved configuration for the desktop app unless you intentionally launch it with a controlled environment.

### Clear saved settings

Ask the plugin to clear individual fields:

> Clear the saved X-Plane host and port, then show the effective target without probing.

To switch back from explicit files to automatic installation detection:

> Clear both saved DataRefs.txt and Commands.txt paths, then show the catalog status.

The two explicit catalog paths must always be configured or cleared together.

## Behavior and limitations

### UDP writes are not acknowledged

X-Plane's native `DREF`, `CMND`, and `PREL` datagrams do not return success acknowledgements. A successful tool result means that the datagram was sent, not that X-Plane accepted the change.

When verification matters, ask the model to read the DataRef or position afterward. A readback is a separate observation and can still be affected by UDP loss or simulator behavior.

### UDP is unordered and unreliable

Packets can be lost, duplicated, delayed, or arrive out of order. The plugin uses timeouts for reads and reports missing values. It does not provide transaction semantics across multiple writes.

### Only numeric scalar writes are supported

The current `DREF` tool writes finite numeric values. Native arrays and strings must be addressed one indexed numeric element at a time, for example:

```text
sim/example/array_dataref[0]
```

Whole-array and string reads/writes are not implemented.

### `RREF` values are float32

X-Plane returns `RREF` subscription values as 32-bit floating-point numbers, even when the catalog describes a DataRef as an integer or double. Small precision differences are expected.

### Catalogs do not guarantee runtime availability

`DataRefs.txt` describes X-Plane's base catalog. Aircraft and third-party plugins can create additional DataRefs or commands at runtime. Those custom entries may not appear in the base files.

The tools have an `allowUnlisted` escape hatch, but the model should use it only when an exact custom path has been identified from a trusted aircraft/plugin source. An unlisted name should never be guessed.

### Writable does not mean every aircraft will honor a value

A DataRef marked writable can still be controlled or overwritten by the active aircraft, autopilot, flight model, or another plugin. Some DataRefs are meaningful only for particular aircraft or simulator states.

### Units come from the catalog

Names alone do not always reveal whether a value is degrees, radians, knots, meters per second, feet, meters, a ratio, or an enum. The model should inspect the catalog description and ask for clarification when the intended unit is not clear.

### Multiple X-Plane instances

Beacon discovery returns the first valid instance it hears. Configure an explicit host and port when more than one simulator is present.

## Troubleshooting

### `codex: command not found`

Install or update Codex CLI, open a new terminal, and confirm:

```sh
codex --version
codex plugin --help
```

The current CLI must provide the `codex plugin` commands. See the official [OpenAI plugin documentation](https://learn.chatgpt.com/docs/plugins) for supported installation surfaces.

### The marketplace or plugin is not visible

Run:

```sh
codex plugin marketplace list
codex plugin list
```

Confirm that:

- `x-plane-control-local` appears as a marketplace;
- `x-plane-control` appears in the plugin list;
- you added the directory containing `.agents/plugins/marketplace.json`, not the inner plugin directory;
- the ChatGPT desktop app was fully restarted; and
- you started a new chat after installation.

Workspace administrators can restrict local plugins. If the marketplace is recognized by the CLI but unavailable in the app, check the account or workspace policy.

### The plugin is installed but its MCP server will not start

Check Node.js in a terminal:

```sh
node --version
```

On macOS or Linux, also run:

```sh
command -v node
```

On Windows:

```powershell
Get-Command node
```

The bundled `.mcp.json` launches `node`, so it must be visible on the host's `PATH`. If Node is available only after a shell profile loads, install Node system-wide with the standard installer or arrange for the desktop application to inherit the correct `PATH`, then fully restart the app.

To check the packaged server manually, run this from the marketplace directory:

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

A healthy stdio server waits silently for MCP messages; press `Ctrl+C` to stop it. Developers can run the automated handshake test with `npm run smoke:stdio` from the source directory.

### The catalog cannot be found

Ask for status without probing X-Plane:

> Show the X Plane Control status with probing disabled, including the resolved catalog paths.

Check that:

- an installation path points at the X-Plane root, not at `Resources/plugins`;
- both files exist beneath `<root>/Resources/plugins`;
- explicit file paths name the files themselves;
- both explicit paths were configured together;
- the plugin host has permission to read both files; and
- environment variables are not overriding the saved configuration.

If X-Plane is on another computer, copy both files to the plugin computer and configure those copies.

### The UDP probe times out

Check the following in order:

1. X-Plane is running and an aircraft has finished loading.
2. X-Plane accepts incoming network connections.
3. The configured UDP port matches X-Plane's Network settings.
4. The configured host is the X-Plane computer's current IP address.
5. The operating-system firewall allows the traffic.
6. Both computers can reach each other on the same LAN or private VPN.
7. Client isolation is disabled on the Wi-Fi network.
8. An explicit host is configured if multicast discovery cannot cross the network boundary.

Sending a UDP datagram can appear successful even when no simulator is listening. Use the version probe or a DataRef read to establish reachability.

### A command or write says “sent” but nothing changes

Possible causes include:

- the flight is still loading;
- UDP packet loss;
- the DataRef value uses different units or an enum;
- the wrong array index was selected;
- the active aircraft or another plugin immediately overwrote the value;
- the command is not applicable to the active aircraft; or
- the configured catalog does not match the running X-Plane version.

Ask the model to read the value back and to show the catalog entry it selected. For a discrete cockpit action, ask it to search for an exact command instead of forcing a DataRef write.

### An add-on aircraft command or DataRef is missing

The standard catalog files do not necessarily contain dynamically registered add-on controls. Consult the aircraft or plugin documentation for the exact path. Then ask the model to use that exact unlisted name and explain why the override is appropriate.

### Values look rounded or slightly different

`RREF` returns float32 values. Precision can be lower than the underlying DataRef type, and X-Plane can update values between separate reads.

## Update or uninstall

### Update a downloaded local bundle

1. Download and extract the new release.
2. Remove the old installed copy:

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

3. If the new bundle is in a different directory, replace the marketplace registration:

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

4. Install the plugin again:

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

5. Restart ChatGPT desktop and start a new chat.

Saved X-Plane Control settings live outside the plugin cache, so reinstalling the plugin does not normally remove the saved simulator/catalog configuration.

### Uninstall

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

The commands remove the installed plugin and marketplace registration. They do not delete the separately saved X-Plane Control `config.json`. Delete that file manually only if you also want to erase the saved paths and network target.

## Development

### Common commands

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

- `npm run check` type-checks the TypeScript source.
- `npm test` runs the packet, catalog, configuration, and fake-X-Plane tests.
- `npm run build` bundles the server into `dist/server.mjs`.
- `npm run smoke:stdio` launches the bundled server and performs an MCP handshake/tool-list test.
- `npm run package:plugin` validates, packages, and smoke-tests the distributable plugin.

### Project layout

```text
.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
```

### Optional diagnostic HTTP transport

The normal plugin uses stdio. A loopback HTTP transport is retained for local protocol diagnostics:

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

Endpoints:

- MCP: `http://127.0.0.1:8765/mcp`
- Health check: `http://127.0.0.1:8765/health`

This listener is unauthenticated and should remain bound to loopback. Do not expose it publicly.

## Distribution notes

Making this repository public on GitHub lets users download and install the local marketplace bundle. It does **not** automatically list the plugin in OpenAI's universal public Plugins Directory.

The GitHub/local-marketplace edition is deliberately a bundled stdio plugin because it must access local catalog files and a simulator on the user's network. OpenAI's public plugin submission path generally expects a production MCP service at a stable HTTPS endpoint, with appropriate authentication and review. That would be a separate architecture and release channel.

Before creating a GitHub release:

1. Update the version and public author/repository metadata in `.codex-plugin/plugin.json` and `package.json`.
2. Run `npm ci`.
3. Run `npm run package:plugin`.
4. Test the generated `release/x-plane-control-marketplace` directory on a clean account or machine.
5. Archive that directory as the release asset, preserving `.agents/plugins/marketplace.json`.
6. Publish the source and release archive under the included MIT license.

## Privacy and security

- The MCP server and X-Plane UDP client run locally.
- No OpenAI API key is required by this server.
- No X-Plane credentials are used.
- Saved configuration contains filesystem paths and, optionally, a simulator hostname/IP and port.
- X-Plane UDP traffic is unencrypted and unauthenticated.
- Catalog files are read locally and used for search and safety metadata.
- The plugin can change simulator state, so review tool approvals and use it only with a simulator you are authorized to control.

## Technical references

- [X-Plane DataRefs reference](https://developer.x-plane.com/datarefs/)
- [X-Plane SDK data access documentation](https://developer.x-plane.com/sdk/XPLMDataAccess/)
- [X-Plane UDP data output protocol overview](https://flyawaysimulation.com/ask/answers/x-plane-udp-data-output-protocol/)
- [XPlaneConnector protocol notes](https://github.com/MaxFerretti/XPlaneConnector/blob/master/XPlaneConnector/XPlaneConnectorCore/README.md)
- [XPPython3 UDP documentation](https://xppython3.readthedocs.io/en/latest/development/udp/index.html)
- [OpenAI plugin documentation](https://learn.chatgpt.com/docs/plugins)
- [OpenAI plugin packaging guide](https://developers.openai.com/plugins/build/plugins)
- [Model Context Protocol specification](https://modelcontextprotocol.io/specification/latest)

## License

MIT. See [LICENSE](LICENSE).