X4CodeSense

x4-script-mcp

x4-script-core を基盤とする、X4: Foundations のスクリプト（AI スクリプトおよび Mission Director スクリプト）用 MCP サーバーです。スクリプトを作成する AI エージェントに、ゲーム本体のファイルから X4CodeSense VS Code 拡張機能が把握している情報を提供します。チェック項目とクイックフィックス、スキーマの要素と属性、式の型とプロパティ、ゲーム本体、DLC、拡張機能のスクリプト、キュー、テキストが含まれます。ツールは読み取り専用で、ファイルはエージェントが書き込みます。

X4CodeSense 拡張機能にはこの機能が組み込まれており、設定で指定したゲームファイルと拡張機能に対して、VS Code のエージェント（Copilot のエージェントモード）に提供します。セットアップは不要です。コマンド X4CodeSense: Start MCP Server を実行すると、http://127.0.0.1:47400/mcp で他のエージェントにも提供され、Copilot CLI セッションなどから利用できます。他のエージェントでは、npm から起動することもできます。

# Claude Code
claude mcp add x4 -- npx -y x4-script-mcp --game "C:\Games\X4 Foundations" --extensions C:\mods

{
  "mcpServers": {
    "x4": {
      "command": "npx",
      "args": ["-y", "x4-script-mcp", "--unpacked", "C:\\X4\\extracted", "--extensions", "C:\\mods"]
    }
  }
}

2 つ目は、Claude Desktop、Cursor など、同じ形式の設定を受け付けるアプリの設定です。Node.js 22 以降が必要です。また、VS Code の MCP サーバーギャラリーなどが参照するカタログである MCP Registry に io.github.chemodun/x4-script-mcp として登録されています。X4CodeSense 拡張機能がインストールされている場合、そこから追加する必要はありません。追加すると、2 つ目のコピーが起動してしまいます。

エージェントは、指示されたツールを使用します。たとえばエージェントへの指示（CLAUDE.md、.github/copilot-instructions.md、AGENTS.md）で、ゲームの .xsd ファイルや scriptproperties.xml を検索するのではなく、要素や式を記述する前に describe_element と expression_type を呼び出し、スクリプトを変更するたびに check を実行するよう指示してください。各呼び出しは標準エラーに記録され、クライアントではサーバーのログとして、ツール名、引数、時刻、回答のサイズが表示されます。

オプション：

• --game <folder> - インストール済みゲームのフォルダー（X4.exe があるフォルダー）です。ゲーム本体と DLC のファイルは、展開されることなく、それぞれのカタログから読み込まれます。--unpacked が指定されていない場合に使用されます。また、--unpacked と併用した場合、拡張機能が依存する、またはパッチを適用するために必要な、ここにインストールされている MOD もパッチ用に読み込まれます。パック済みの MOD はカタログから読み込まれます。
• --installed-dependencies - --game と併用すると、拡張機能が依存するインストール済み MOD 全体が対象になります。そのキュー、スクリプト、テキストが解決されます。
• --unpacked <folder> - 展開済みのバニラゲームファイルのフォルダーです。libraries、md、aiscripts、t が含まれるフォルダーを指定します。
• --game と --unpacked のどちらも指定されていない場合、展開済みファイルには環境変数 X4_UNPACKED が使用され、それがなければインストール済みゲームには X4_GAME が使用されます。いずれかのオプションを指定すると、両方の環境変数より優先されます。
• --extensions <folder> - 拡張機能、または拡張機能のフォルダーです。エージェントが作成するものと、エージェントが参照するものを指定します。スクリプトとテキストはゲーム本体のファイルに加えて読み込まれます。複数回指定できます。指定しない場合は、現在のフォルダーが使用されます。
• --language <number> - テキストの表示言語です。デフォルトは 44（英語）です。言語番号はゲームの libraries/languages.xml に記載されています。
• --no-structure - 不明な要素、属性、値、必須属性の欠落、および要素内のテキストのみを報告し、子要素の順序と完全性は報告しません。
• --no-type-guesses - スクリプトとスキーマに記載された内容のみで変数の型を判定し、アクション名やドキュメント（create_ship は船を作成する、など）から推測しません。
• --library-patch-unknown-elements <severity> - ライブラリファイルのパッチによって追加される要素が、そのファイルのスキーマで宣言されていない場合の重大度です。error、warning（デフォルト）、info を指定できます。ライブラリのスキーマはファイルに追いついていません。各 DLC でモジュールの <category> に <extension> が追加されますが、どのスキーマにも宣言されていません。
• --port <number> - URL を渡されるエージェント向けに、標準入力と標準出力の代わりに http://127.0.0.1:<port>/mcp で Streamable HTTP を提供します。0 を指定すると空きポートが選択されます。この場合、ゲームファイルは一度に読み込まれ、すべてのクライアントで共有されます。このマシン上のクライアントのみが利用できます。別のホストを指定するリクエストや、別のサイトのウェブページからのリクエストは拒否されます。使用中のポートが指定された場合、終了コード 1 で終了します。
• -h、--help - 使用方法を表示します。

ゲームファイルは最初の呼び出し時に読み込まれ、数秒かかります。拡張機能のファイルは監視されます。エージェントがスクリプトファイルまたはテキストファイルを作成、変更、削除すると、次の呼び出しの前に再度読み込まれます。また、呼び出しで指定されたファイルは、常にディスク上の状態で読み込まれます。拡張機能が追加された場合、または content.xml が変更された場合は、すべてのファイルが再度読み込まれます。

ツール

行と列は 1 から数えます。列は、エディターで数えるのと同じく UTF-16 コード単位です。場所は file、line、column、endLine、endColumn で指定し、text はその行にあるテキスト、game: true はゲームまたは DLC のファイルであることを示します。このファイルはカタログにしか存在しない場合があります。回答は JSON です。回答できないツールは、エラーとしてその理由を返します。

• check - paths：ファイルとフォルダー、text：ディスク上にある paths 内の単一ファイルの代わりにチェックする内容、severity：報告する指摘の最低深刻度。フォルダーは x4-script-check と同様にチェックされます。対象は、フォルダー内とその 1 階層下にある md、aiscripts、libraries フォルダーです。チェッカーの JSON 形式で、クイックフィックス（互いに重ならない編集。preferred はエディターが自動で適用するもの）と件数を含む指摘を返します。
• describe_element - name、script（md または aiscripts）、または library（ライブラリファイルのファイル名で指定するスキーマ。jobs.xml の場合は libraries、unlocks）、異なる場所で異なる形で宣言されている要素の場合は parent（param、actions）、属性を 1 つ詳しく調べる場合は attribute。要素のドキュメント、属性とその型、必須かどうか、デフォルト値、値が式かどうか、許可される値の最初のもの（属性を 1 つ詳しく調べる場合は、ドキュメント付きですべて）を返します。また、許可される子要素も返します。スキーマに認識されない名前の場合は、類似した名前を返します。
• expression_type - expression（player.ship.sector などのキーワードとそのプロパティ）、または datatype（ship など）、script、filter。各ステップについて、解決された内容、その型、説明を返します。結果のデータ型とその上位型、およびプロパティを name → type の形式で返し、その型から派生した型が追加するプロパティの数も示します。filter の場合は、名前にその文字列を含むプロパティと、派生型のプロパティも説明付きで返します。ここでは変数に型はありません。変数の後のステップは、すべてのデータ型のプロパティと照合されます。
• find - query、limit。Mission Director スクリプト、AI スクリプト、キュー、ライブラリ、割り込みライブラリ項目を名前で検索します。完全一致を最初に、その後、クエリで始まるもの、クエリを含むものの順に返します。ドットを含むクエリは、md.Setup.Start のような修飾名に一致します。
• definition、references - file、line、column。ゲーム、DLC、拡張コンテンツ内で、指定された名前が定義されている場所、またはその名前を参照するすべての場所を返します。対象はキュー、スクリプト、ライブラリ、ラベル、変数、命令、テキストです。定義の場合は、スキーマと scriptproperties.xml 内の定義も返します。
• hover - file、line、column。その場所にエディターのホバーで表示される内容を、対象範囲とともに Markdown で返します。対象は、ドキュメント付きの要素または属性、型付きのプロパティチェーンのステップ、型と設定場所を含む変数、定義場所を含むキューまたはスクリプト、ゲーム内で表示される {page, id} 形式のテキストです。パッチ内でも、そのパッチが追加する内容について返します。
• text - page と id、テキストを検索する場合は page のみ、またはすべての単語を含むテキストを検索する場合は search。language、limit。ゲーム内で表示されるテキスト、参照を解決した結果、ゲーム内表示と異なる場合は記述されているテキストを、それが含まれるファイルと存在する言語とともに返します。
• status - ゲームフォルダー、拡張コンテンツのフォルダー、読み込んだスクリプトとテキストの数、読み込み中に発生した問題を返します。

X4CodeSense の一部です。Apache License 2.0。