# Gaea MCP

MCP server for QuadSpinner Gaea terrain workflows.

The server edits Gaea `.terrain` graph files, discovers Gaea CLI executables,
and can run silent builds through `Gaea.Swarm.exe`.

This is intentionally small. It automates the repetitive bridge work while
leaving artistic terrain tuning inside Gaea.

## Install

From this repo:

```powershell
cd C:\Users\marti\Games\Ascent\tools\gaea-mcp
npm install
npm run build
```

From a standalone checkout:

```powershell
git clone https://github.com/JulianIrigoyen/gaea-mcp.git
cd gaea-mcp
npm install
npm run build
```

## Codex / Claude MCP Config

Add a server entry like this:

```json
{
  "mcpServers": {
    "gaea": {
      "command": "node",
      "args": [
        "C:/path/to/gaea-mcp/dist/index.js"
      ],
      "env": {
        "GAEA_ROOT": "C:/path/to/your/terrain/project",
        "GAEA_EXE_DIR": "C:/Program Files/QuadSpinner/Gaea 2"
      }
    }
  }
}
```

## Tools

- `gaea_clone_graph` - clones a `.terrain` graph and optionally repoints input/output paths.
- `gaea_find_install` - finds `Gaea.Swarm.exe`, `Gaea.exe`, and related executables.
- `gaea_list_graphs` - lists `.terrain` files.
- `gaea_inspect_graph` - reports File nodes, output destination, profiles, and exposed variables.
- `gaea_set_input_heightmap` - rewrites File node input paths.
- `gaea_set_build_output` - rewrites the build output destination.
- `gaea_set_variable` - updates or creates a variable entry when the graph exposes a matching structure.
- `gaea_run_build` - runs `Gaea.Swarm.exe` with optional profile, resolution, seed, vars, and output path.
- `gaea_open_graph` - opens a graph in the Gaea desktop app.
- `gaea_list_outputs` - lists files in an output folder.

Write/build/open tools default to `dryRun: true`. Pass `dryRun: false` to
actually save, launch, or build. Graph edits create timestamped `.bak-*`
backups before overwriting existing files.

## Example

```json
{
  "graph": "TerrainExports/LaninTrue_Gaea.terrain"
}
```

Then:

```json
{
  "graph": "TerrainExports/LaninTrue_Gaea.terrain",
  "nodeId": "522",
  "heightmap": "TerrainExports/LaninTrue_Gaea/LaninTrue_Height.png",
  "dryRun": false
}
```

Clone Aconcagua into a Lanin graph:

```json
{
  "sourceGraph": "TerrainExports/Aconcagua_v01.terrain",
  "targetGraph": "TerrainExports/LaninTrue_Gaea.terrain",
  "heightmap": "TerrainExports/LaninTrue_Gaea/LaninTrue_Height.png",
  "outputDir": "TerrainExports/LaninTrue_Gaea",
  "dryRun": false
}
```

Preview the exact build command without launching Gaea:

```json
{
  "graph": "TerrainExports/LaninTrue_Gaea.terrain",
  "outputDir": "TerrainExports/LaninTrue_Gaea",
  "resolution": "2048",
  "dryRun": true
}
```

Open a graph in the Gaea UI:

```json
{
  "graph": "TerrainExports/LaninTrue_Gaea.terrain",
  "dryRun": false
}
```

## Safety

- All file paths are constrained to `GAEA_ROOT`.
- Writes default to dry-run.
- Existing graph edits write `.bak-*` backups.
- Real Gaea builds require `dryRun: false`.
- Build execution has a timeout, defaulting to one hour.

## Scope

This is not an official QuadSpinner product. It works through documented CLI
entry points and the `.terrain` graph format as observed on disk.

## Known Limitations

- The `.terrain` graph format is not treated as a public stable API by this
  project; inspect and dry-run before writing.
- `gaea_set_variable` only works when the graph contains discoverable variable
  objects with `Value`/`value` fields. CLI `-v name:value` is more reliable for
  exposed build variables.
- On Windows, `Gaea.Swarm.exe` may crash with `System.IO.IOException: The handle
  is invalid` when launched from a host without a real console. If that happens,
  run the printed dry-run command in a normal terminal or a PTY-backed shell.
- The server does not generate terrain artistically. It automates graph
  plumbing, builds, and handoff files.