Skip to content
harshit51290Public

About

No description, website, or topics provided.

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

gaea-mcp

Model Context Protocol server for QuadSpinner Gaea 2 terrain automation. Drive Gaea.Swarm.exe headlessly from any MCP client or AI agent: read recipes, reshape them, run builds, verify results — and see the outputs.

Verified against Gaea 2.3.1.0, including real headless builds.

Requirements

  • Windows, Python 3.10+
  • QuadSpinner Gaea 2 (any edition; mesh export needs a higher edition — the verifier tells you exactly that instead of failing mysteriously)

Install

git clone https://github.com/harshit51290/gaea-mcp.git
cd gaea-mcp
python -m pip install -e ".[dev]"

Connect (opencode / Claude Desktop / Inspector)

{
  "mcpServers": {
    "gaea": {
      "command": "python",
      "args": ["-m", "gaea_mcp.server"],
      "env": { "GAEA_EXE": "C:\\Program Files\\QuadSpinner\\Gaea 2\\Gaea.Swarm.exe" }
    }
  }
}

Engine lookup order: per-tool exe arg → GAEA_EXE env → HKLM\SOFTWARE\QuadSpinner\Gaea\<ver> registry → default Program Files paths.

Tools (19)

Tool Purpose
locate_gaea_install Find engine, version, builds root (+ MCP server version)
list_terrains Scan a dir for .terrain recipes with parsed summaries
find_projects Find recipes by plain words, typo-tolerant, no path needed
remember_project Name a recipe once, resolve it by name forever
describe_terrain Recipe readout: resolution, nodes, exports, variables, profiles
create_variation Clone a recipe + scalar node tweaks (topology never touched)
add_plain_level Append Constant + Combine(Max): flat plains below peaks + export
add_height_export Attach PNG16 height export to any node (enables measurement)
rewire_port Point one input port at another node's output (e.g. File → Erosion)
set_output_destination Set build Type/Destination (fixes silent no-output builds)
preview_build_command Exact Swarm argv without executing (Copy Command Line)
run_build Headless build → exit code + build-dir analysis
batch_build Sequential multi-recipe builds
list_builds Build output dirs (<project>/<NNN>), newest first
get_build_report report.json + report.txt + crash issues for one build
verify_build pass/fail verdict with severity (benign / warning / error)
list_outputs Files in an output directory
inspect_heightfield File stats, image metadata, raw sample stats
see_output SEE the render (image) + relief stats — agent eyes

Resources: gaea://install, gaea://cli-reference, gaea://recipe-format, gaea://formats, gaea://verification. Prompts: plan_automation_recipe, bridge_workflow.

Agent loop

describe_terrain → preview_build_command → run_build → verify_build → see_output

The skills/gaea-terrain skill file teaches agents this loop, the plain-language routing ("my island map" → find_projects), the art-director iteration pattern, and the real-Earth DEM workflow. Copy it into your agent's skills directory.

CLI contract (Gaea.Swarm --help, 2.3.1.0)

Gaea.Swarm --Filename "<recipe.terrain>" [--profile Name] [--region Name]
  [--seed N] [--resolution R] [--buildpath DIR] [--node ID]
  [--silent] [--ignorecache] [--verbose] [--safemode] [--interactive]
  [--vars vars.json] [--va a,b,c] [-v name=value ...]

Two hard-won facts encoded in the runner: --silent is always passed (Swarm waits for a keypress otherwise and crashes headless), and Swarm stdout cannot be captured (console-handle crash on pipes and files) — so the server runs it in a hidden console and verifies via exit code + build directory.

Recipes you should know

  • .terrain files are lenient JSON (BOM/trailing commas tolerated).
  • A node exports iff it has SaveDefinition.Filename.
  • A null BuildDefinition.Type makes Swarm exit 0 having built nothing.
  • Gaea heightmaps are relative (peaks ~0.3 normalized is normal) — "big" comes from relief contrast + importer Z-scale, not raw numbers.

Dev

python -m pytest -q   # 23 tests, no Gaea install needed

See CONTRIBUTING.md. MIT licensed — LICENSE. Gaea is a trademark of QuadSpinner; this project is unaffiliated.

About

No description, website, or topics provided.

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages