X4: Foundations scripts: checks, schema elements, expression types, scripts, cues and texts.
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.
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.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 X4_EXTRACTED and X4_GAME, 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, X4_FILE_CEILING_MS sets a higher ceiling; with all corpus files running at once, each shares the machine with the others.
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:
x4codesense: the .vsix is built, attached to the release and, with the VT_API_KEY secret, scanned by VirusTotal. With the repository variable PUBLISH_TO_MARKETPLACE set to true, the same .vsix is then published to the Visual Studio Marketplace as X4DevTools. That job runs in the marketplace environment and signs in to Microsoft Entra ID, whose app registration trusts that environment, so no Marketplace token is kept either.x4-catalog, x4-script-core, x4-script-language-server, x4-script-check, x4-script-mcp: built, tested and sent to npm by trusted publishing. No npm token is kept in the repository: npm accepts the upload because the package is bound to this repository and its build-and-publish.yml, and adds a provenance statement. The version is published directly. A package that is not on npm yet is skipped with a warning: its first version is published by hand, which creates the package the binding is set on.x4-script-mcp then goes to the MCP Registry as io.github.chemodun/x4-script-mcp, described by packages/mcp/server.json, whose versions release-please keeps with the package's. The workflow signs in with its GitHub identity, which owns the namespace, and the registry checks that the npm package names it in mcpName. The step waits until npm lists the new version, up to 10 minutes, and skips a version the registry has already, so a failed job can be run again.X4CodeSense is the successor of X4CodeComplete (MIT), started by Cgetty and continued by archenovalis. It is written anew around a language server, building on the ideas of X4CodeComplete and on the valuable experience gained during its development.
Apache License 2.0, see LICENSE.
Source-derived launch command. Check the maintainer’s required arguments and credentials before running:
npx -y x4-script-mcpMerge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.
{
"mcpServers": {
"io-github-chemodun-x4-script-mcp": {
"command": "npx",
"args": [
"-y",
"x4-script-mcp"
]
}
}
}Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.
Claude Desktop setup referenceX4CodeSense works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.
~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect.~/.cursor/mcp.jsonRestart Cursor for changes to take effect..vscode/mcp.jsonReload VS Code window for changes to take effect.~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect..mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.