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은 같은 LAN의 별도 게임 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를 통해 지리적 위치, 자세, 속도, 회전을 읽습니다.

• 읽기 전용 지리적 DataRef를 쓰려고 시도하는 대신 PREL을 통해 항공기를 이동시킵니다.

• 애리조나의 임의 내부 지점을 선택하는 고수준 도구를 포함합니다.

• 읽기 전용으로 표시된 카탈로그 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가 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의 설정 → 네트워크 화면을 엽니다. 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 경로;

• 파싱된 DataRefs 및 명령 수;

• 대상이 구성되었는지, 비콘에서 발견되었는지, 또는 localhost 기본값에서 가져왔는지 여부; 그리고

• X-Plane 버전 DataRef 읽기 결과.

다른 컴퓨터에서 X-Plane 사용

번들로 제공되는 MCP 서버는 항상 ChatGPT/Codex 컴퓨터에서 실행됩니다. X-Plane은 해당 컴퓨터 또는 UDP를 통해 연결 가능한 다른 컴퓨터에서 실행될 수 있습니다.

권장 원격 컴퓨터 설정

1. 두 컴퓨터를 동일한 신뢰할 수 있는 LAN 또는 개인 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 포트를 직접 전달하지 마십시오. 기본 프로토콜은 암호화되거나 인증되지 않습니다. 서로 다른 위치의 컴퓨터의 경우, 개인 IP로 컴퓨터에 연결할 수 있는 개인 VPN을 사용하고 방화벽 접근을 플러그인 컴퓨터로 제한하십시오.

플러그인 사용 시작

설치 또는 업데이트 후에는 항상 새 채팅 또는 Codex 세션을 시작하십시오. 플러그인을 사용하라는 직접 지시는 첫 실행 테스트를 더 쉽게 만듭니다:

X Plane Control을 사용하여 제 시뮬레이터와 카탈로그가 준비되었는지 확인하십시오. 아직 아무것도 변경하지 마십시오.

상태가 정상이면 일반 자연어 요청을 사용할 수 있습니다.

시뮬레이터 상태 읽기

• "제 지리적 위치와 자세를 표시하십시오."

• "제 지시 속도, 실제 속도, 방향 및 압력 고도를 읽으십시오."

• "연료량에 대한 DataRefs를 찾고 현재 값을 표시하십시오."

• "주차 브레이크가 설정되었는지 확인하십시오."

정확한 DataRefs를 지정하지 않는 요청의 경우, 모델은 먼저 카탈로그를 검색하고 설명과 유형을 사용하여 후보를 선택해야 합니다.

시뮬레이터 명령 실행

• “랜딩 기어를 토글하는 명령을 찾아 실행하십시오.”

• “X-Plane 명령을 사용하여 착륙등을 켜십시오.”

• “시뮬레이터를 일시 중지하십시오.”

• “시동 명령을 두 번 실행하십시오.”

명령은 개별 동작을 나타냅니다. 현재 서버는 CMND 명령-일회 패킷을 전송합니다. 명령-시작/명령-종료 유지 기능은 구현하지 않습니다.

값 설정

• “주차 브레이크에 대한 쓰기 가능한 DataRef를 찾아 완전히 설정하고 다시 읽으십시오.”

• “첫 번째 엔진 스로틀 비율을 0.5로 설정하십시오.”

• “이 요청에 대한 쓰기 가능한 계기등 밝기 DataRefs를 찾고 변경 전에 후보를 표시하십시오.”

DataRefs.txt의 설명은 단위와 유효한 의미를 정의합니다. 단위, 배열 요소 또는 원하는 값이 모호한 경우, 쓰기 전에 모델에게 후보를 표시하도록 요청하십시오.

항공기 이동

• “제 비행기를 애리조나의 임의 위치로 이동하십시오.”

• “사용자 항공기를 위도 34.8697, 경도 -111.7609, 해발 5,000미터, 동쪽 방향 60미터/초로 순간 이동하십시오.”

• “내 위치를 표시하고, 이 좌표로 이동하고, 결과 위치를 표시하십시오.”

지리 위치 DataRefs는 읽기 전용입니다. 플러그인은 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는 셸 환경을 상속하기 때문입니다:

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은 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 데스크톱 앱을 완전히 다시 시작했는지; 그리고

• 설치 후 새 채팅을 시작했는지.

작업공간 관리자는 로컬 플러그인을 제한할 수 있습니다. 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. 구성된 호스트가 X-Plane 컴퓨터의 현재 IP 주소인지.

5. 운영 체제 방화벽이 트래픽을 허용하는지.

6. 두 컴퓨터가 동일한 LAN 또는 개인 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 데스크톱을 다시 시작하고 새 채팅을 시작합니다.

저장된 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 릴리스를 만들기 전에:

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 서버와 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 플러그인 패키징 가이드

• Model Context Protocol 사양

라이선스

MIT. LICENSE를 참조하세요.