# X4CodeSense MCP server

> Provides AI agents with deep knowledge of X4: Foundations scripts, schemas, expression types, and game texts for automated script development.

- Repository: https://github.com/chemodun/X4CodeSense
- Page: https://hostedmcp.org/servers/chemodun/x4-script-mcp
- Transport: stdio
- Stars: 0
- License: Apache-2.0
- Latest version: 0.5.0

## Install

### Claude Code

```sh
claude mcp add x4-script-mcp -- npx -y x4-script-mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "x4-script-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "x4-script-mcp"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "x4-script-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "x4-script-mcp"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"x4-script-mcp","type":"stdio","command":"npx","args":["-y","x4-script-mcp"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "x4-script-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "x4-script-mcp"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add x4-script-mcp -- npx -y x4-script-mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.x4-script-mcp]
command = "npx"
args = ["-y", "x4-script-mcp"]
```

### Gemini CLI

```sh
gemini mcp add -s user x4-script-mcp npx -- -y x4-script-mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "x4-script-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "x4-script-mcp"
      ]
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `X4_GAME` | no | no | The installed game, the folder of X4.exe; its files are read from the catalogs. |
| `X4_UNPACKED` | no | no | The extracted game files, the folder holding libraries, md and aiscripts; used instead of X4_GAME. |

## Tools (9)

- `check`: Checks X4 scripts and patches as the X4CodeSense editor and x4-script-check do: well-formedness, the game schemas, expressions, variables, names, cues, scripts and texts referred to; and library files that name their schema in xsi:noNamespaceSchemaLocation against it. Returns the findings with their quick fixes (edits to apply), and counts. Run it after every change to an md or aiscripts script or a patch, and fix what it reports; with text, check a draft before writing it. (read-only)
- `describe_element`: An element of the Mission Director or AI script schema, from the game’s md.xsd or aiscripts.xsd, or of a library file’s schema (libraries.xsd for jobs.xml, unlocks.xsd, …): its documentation, its attributes (type, required, default, allowed values, whether the value is an expression) and the child elements it allows. Use it before writing an element or attribute you are not sure of, instead of searching md.xsd, aiscripts.xsd or common.xsd: it follows their types, groups and includes. (read-only)
- `expression_type`: What a keyword or a property chain of the expression language yields, step by step, from the game’s scriptproperties.xml: player.ship, player.ship.sector, event.param; and the properties of the result with their types. Or a datatype’s properties. A variable has no type here, its type comes from the script around it: the step after it is matched against the properties of every datatype. Use it before writing a property chain you are not sure of, instead of searching scriptproperties.xml. (read-only)
- `find`: Mission Director scripts, AI scripts, cues, libraries and interrupt library items (actions, handlers, conditions) of the game, its DLCs and the extensions, by name: whole names first, then those starting with the query, then those containing it; the extensions’ before the game’s among equals. A query with a dot matches qualified names: md.Setup.Start. When no name contains the query, a few that have its letters in order. Use it instead of searching the files for a cue or script name. (read-only)
- `definition`: Where what is named at a place of a script is defined, as the editor’s go to definition finds it: a cue, script, library, label, variable, order, text, element or attribute of the schema, property of scriptproperties.xml. Each place with its line of text. (read-only)
- `references`: Every place that names what is named at a place of a script, in the game, its DLCs and the extensions, as the editor finds them: who signals a cue, includes a library, runs a script. Each place with its line of text. Use it instead of searching the files for a name. (read-only)
- `hover`: What the editor’s hover shows for a place of a script or patch: an element or attribute with its documentation from the schema, a step of a property chain with its type and description from scriptproperties.xml, a variable with its type and where the type comes from, a cue or script with where it is defined, a {page, id} text as the game shows it. Use it to understand a line of an existing script, the game’s included, instead of looking each part up in the schemas, scriptproperties.xml or the t folders. (read-only)
- `text`: Texts of the game and the extensions, as the game shows them, references resolved: {page, id} in a language; the texts of a page; or the texts that contain some words. Use it instead of searching the t folders: for what a {page, id} says, or to find an existing text to reuse. (read-only)
- `status`: What the server read: the game folder, the extension folders, how many scripts and texts, and the problems met reading them. (read-only)

## FAQ

### Can the server write files?

No, the tools are read-only; the AI agent is responsible for writing the actual files.

### How do I add this to Claude Code?

You can add it using the command: `claude mcp add x4 -- npx -y x4-script-mcp --game "C:\Games\X4 Foundations" --extensions C:\mods`

### What are the requirements to run the server?

The server requires Node.js version 22 or later.

### Does it support DLCs and extensions?

Yes, it reads scripts, texts, and schemas from the game, its DLCs, and any specified extensions.
