X4CodeSense MCP server

X4CodeSense

Language support for X4: Foundations scripts (AI scripts and Mission Director scripts), built as a Language Server Protocol server with a thin Visual Studio Code client and a command-line checker.

Status: 0.x. The npm packages are on npm; the extension is on the Visual Studio Marketplace, and its .vsix is also attached to the GitHub releases. The Marketplace-facing description lives in client/README.md.

Layout

• packages/catalog - x4-catalog, reads the game's catalogs (.cat/.dat) in place, without extracting them, and writes new ones. No dependencies.
• packages/core - x4-script-core, the editor-independent analysis library: script detection, XML structure, expression language, types, scopes, symbols, diagnostics, and the ReadText calls of Lua files. No vscode imports. Its API is made for the server, the client and the checker, and changes with them.
• packages/server - x4-script-language-server, the LSP server on top of the core.
• packages/cli - x4-script-check, a command-line checker for CI and tools, on top of the core.
• packages/mcp - x4-script-mcp, an MCP server for AI agents that write scripts: checks, the schemas' elements, expression types, scripts, cues and texts, on top of the core.
• client - the X4CodeSense VS Code extension (publisher X4DevTools). It bundles the server, the checker, the MCP server and the core into client/dist, and offers the MCP server to VS Code's agents.

Development

Requires Node.js 22.

npm install
npm run build        # tsc -b for all packages, then esbuild bundle of the client
npm test             # vitest across the packages and the client
npm run typecheck:tests   # tsc over the tests, which vitest runs without checking their types
npm run lint
npm run package -w client   # produces client/x4codesense-<version>.vsix

Press F5 in VS Code (configuration Launch Client, or Client + Server to attach to the server as well).

Optional corpus check against the extracted vanilla game files, an installed game read from its catalogs, and a folder of extensions:

$env:X4_EXTRACTED = 'C:\path\to\extracted\9.00'
$env:X4_GAME = 'C:\path\to\X4 Foundations'
$env:X4_MODS = 'C:\path\to\extensions'
npm test

With both X4EXTRACTED and X4GAME, the files read from the catalogs are compared with the extracted ones of the same build.

The corpus check times the analysis of the largest game file, and of a change typed into it as the editor analyses it, against a ceiling of 200 ms, and of patch documents against twice that. On a slower or busy machine, X4FILECEILING_MS sets a higher ceiling; with all corpus files running at once, each shares the machine with the others.

Releases

release-please keeps one release pull request open on main: the next versions and the changelogs of the six packages, from the conventional commits since their last release. They share one pull request because they depend on each other at exact versions, and it updates package-lock.json with them. Merging it tags each package that changed (x4-script-core@v0.1.0, x4codesense@v0.1.0) and creates its GitHub release, which starts the Build and Publish workflow:

Shortened. The full README is on GitHub.