X4CodeSense

x4-script-mcp

用于 X4: Foundations 脚本（AI 脚本和 Mission Director 脚本）的 MCP 服务，基于 x4-script-core 构建。它为编写脚本的 AI Agent 提供 X4CodeSense VS Code 扩展从游戏自身文件中获取的信息：检查及其快速修复、架构中的元素和属性、表达式的类型和属性，以及游戏、其 DLC 和扩展的脚本、线索和文本。它的工具只读取信息；文件由 Agent 写入。

X4CodeSense 扩展会附带此服务，并将其提供给 VS Code 的 Agent（Copilot 的 Agent 模式），用于其设置中指定的游戏文件和扩展，无需进行任何设置；其命令 X4CodeSense: Start MCP Server 会在 http://127.0.0.1:47400/mcp 上提供此服务，供其他 Agent 使用，其中包括 Copilot CLI 会话。其他 Agent 也可以通过 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"]
    }
  }
}

第二种是 Claude Desktop、Cursor 和其他需要此格式配置的客户端所用的配置。它需要 Node.js 22 或更高版本。它也收录在 MCP Registry 中，名称为 io.github.chemodun/x4-script-mcp；VS Code 的 MCP 服务库等会读取此目录。安装 X4CodeSense 扩展后，无需从该目录添加此服务，否则会运行第二个副本。

Agent 会使用告知它们的工具：例如，在 Agent 的指令（CLAUDE.md、.github/copilot-instructions.md、AGENTS.md）中说明，写入元素或表达式之前先调用 describe_element 和 expression_type，而不是搜索游戏的 .xsd 文件和 scriptproperties.xml；每次更改脚本后都运行 check。每次调用都会记录到标准错误输出中，客户端会将其显示为服务日志：包括工具、参数、时间和答案大小。

选项：

• --game <folder> - 已安装游戏所在的文件夹，即包含 X4.exe 的文件夹。游戏及其 DLC 的文件会直接从所在目录的目录清单中读取，不会解压。未指定 --unpacked 时使用此选项。即使同时指定了 --unpacked，也会从此处读取已安装且扩展依赖或要修补的模组，以供修补使用；已打包的模组则从其目录清单中读取。
• --installed-dependencies - 与 --game 搭配使用时，扩展所依赖的已安装模组会作为整体计入：其提示、脚本和文本都会被解析。
• --unpacked <folder> - 解压后的原版游戏文件所在的文件夹，包含 libraries、md、aiscripts 和 t。
• 未指定 --game 和 --unpacked 时，会使用 X4_UNPACKED 环境变量指定的解压文件；否则使用 X4_GAME 指定的已安装游戏。任一命令行选项优先于这两个环境变量。
• --extensions <folder> - 一个扩展，或包含多个扩展的文件夹：包括 Agent 编写的扩展及其引用的扩展。除了游戏文件，还会读取这些扩展的脚本和文本。可多次指定；未指定时使用当前文件夹。
• --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 的 Agent 提供 Streamable HTTP 服务，地址为 http://127.0.0.1:<port>/mcp，而不使用标准输入和输出；0 会选择一个空闲端口。此时会一次性读取游戏文件，所有客户端共享这些文件。仅服务于本机上的客户端：指定其他主机的请求，或来自其他站点网页的请求，都会被拒绝。端口已被占用时，程序会以退出代码 1 结束。
• -h、--help - 显示用法。

游戏文件会在首次调用时读取，耗时数秒。扩展文件会受到监视：Agent 新建、修改或删除脚本或文本文件后，会在下次调用前重新读取；调用中指定的文件则始终按磁盘上的当前内容读取。添加扩展或修改 content.xml 后，所有文件都会重新读取。

工具

行和列从 1 开始计数；列以 UTF-16 代码单元为单位，与编辑器的计数方式一致。位置以 file、line、column、endLine、endColumn 表示，并附带所在行的 text；对于游戏或 DLC 的文件，还会附带 game: true，这类文件可能只存在于目录中。答案为 JSON；工具无法回答时会以错误形式说明原因。

• check - paths：文件和文件夹；text：要检查的内容，用来替代 paths 中单个文件在磁盘上的内容；severity：要报告的问题的最低严重级别。检查文件夹的方式与 x4-script-check 相同：检查其中及下一层的 md、aiscripts 和 libraries 文件夹。返回检查器 JSON 格式的问题及其快速修复建议（互不重叠的编辑；preferred 表示编辑器会自行应用的建议），以及问题数量。
• describe_element - name；script（md 或 aiscripts）或 library（根据库文件名确定库的架构：jobs.xml 对应 libraries，unlocks）；对于在不同位置以不同方式声明的元素，使用 parent（param、actions）；对于完整查询某个属性，使用 attribute。返回元素文档、其属性及属性类型、是否必需、默认值、值是否为表达式，以及允许的值中的第一个（完整查询某个属性时返回全部允许值及其文档）；还会返回该元素允许的子元素。对于架构不认识的名称，会返回相似名称。
• 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。