Spartan Engine MCP

The MCP server manages a curated markdown file named AGENT_MEMORY.md to provide durable context for future agent runs. Use agent_memory_append to add information to this file.

Use cases for memory:

• Engine facts learned from previous runs.
• Successful strategies and known gotchas.
• Advice for future agents or maintainers (e.g., reporting missing tools or architecture problems).
• Problem reports for recurring friction.

Best Practices:

• Do not use it as a chat transcript.
• Keep notes short and replace stale entries.
• Avoid duplicate bullets.

To use Spartan Engine tools within Cursor, add the spartan_engine server to your Cursor MCP settings. You must ensure the MCP bridge is enabled in Spartan or the Spartan AI widget is open before starting the server. You can override default connection settings using --host, --port, or --timeout-ms flags.

{
  "mcpServers": {
    "spartan_engine": {
      "type": "stdio",
      "command": "node",
      "args": [
        "C:/Users/panos/Desktop/spartan_engine/tools/mcp/spartan_engine/server.mjs"
      ],
      "cwd": "C:/Users/panos/Desktop/spartan_engine/tools/mcp/spartan_engine"
    }
  }
}

To ensure every camera sees a car arrive, pass the center of the shot, and leave before the next cut, use this pattern:

1. Set the follower speed on the spline follower.
2. Run spline_query to retrieve the pass_time_seconds for each camera.
3. Place each sequencer cut at the midpoint between consecutive pass_time_seconds values.

To validate a car preset, define a <validation> section in the .car file containing public evidence envelopes (e.g., zero_to_100_min, braking_distance_max, skidpad_g_min).

Steps to run validation:

1. Open a flat vehicle test world.
2. Use the Run validation command in the telemetry window.
3. Review the results in the generated car_validation_report.csv file.

A preset is considered acceptable when it loads without validation errors and passes the following scenarios: settle acceleration, braking, coastdown, skidpad, step steer, and slalom.

To create a surface that appears emissive white, follow these steps using the material and component APIs:

1. Create a material using material_create (this defaults to white albedo).
2. Set the emissive_from_albedo property to 1 using material_set_property.
3. Assign the material to the render component of an entity using the material property via component_set.

The albedo color of the material will drive the color of the emission.

To test or inspect a vehicle, follow this workflow:

1. Set engine mode to play: engine_set_mode(mode='play').
2. Enter the vehicle: vehicle_enter (requires MCP pedal ownership).
3. Provide input: Hold vehicle_set_input for a duration.
4. Inspect telemetry: Use vehicle_telemetry to view data (output is car_telemetry.csv in the working directory, not an Excel file).

Available Vehicle Tools:

• vehicle_list / vehicle_get
• vehicle_set_input / vehicle_shift
• vehicle_set_view / vehicle_reset / vehicle_exit

Follow these strategies when interacting with the Spartan Engine via MCP:

• Initialization: Start tasks with spartan_status or context_snapshot to understand the current state.
• Error Recovery: Use debug_log_read after a failure to inspect actual command inputs/outputs.
• Discovery: Use search_capabilities and get_capability_details before attempting to use a tool.
• Targeting: Always resolve targets with entity_resolve before mutating named or selected entities.
• Batching: Use component_set_batch for multiple property edits on one component, and entity_set_transform_batch for repositioning many entities.
• Visual Verification: Use screenshot_take when visual confirmation is required; it returns the saved PNG as image content.

Use read-only mode when an agent needs to inspect the engine or source code without the ability to mutate the scene. In this mode, mutating tools are not registered by server.mjs. You can enable this via CLI arguments or environment variables.

CLI Argument: Add --read-only to the args array in your MCP configuration.

Environment Variables:

• SPARTAN_MCP_READ_ONLY=1 (for server.mjs)
• SPARTAN_ASSISTANT_READ_ONLY=1 (for assistant.mjs)

{
  "mcpServers": {
    "spartan_engine": {
      "type": "stdio",
      "command": "node",
      "args": [
        "C:/Users/panos/Desktop/spartan_engine/tools/mcp/spartan_engine/server.mjs",
        "--read-only"
      ],
      "cwd": "C:/Users/panos/Desktop/spartan_engine/tools/mcp/spartan_engine"
    }
  }
}

Common error resolutions for the Spartan Engine MCP:

• engine_timeout: Retry the operation once. If it fails again, reduce the operation size or switch to a batch/Lua path.
• edit_mode_required: Switch the engine to edit mode before attempting mutations.
• Assistant fails to start: Ensure Node.js is in your PATH and run npm install in the tools/mcp/spartan_engine directory.
• Port binding failure: Check if another Spartan instance or a stale bridge process is already running.
• Stale source search: The index refreshes on search, but you can restart the MCP server for a full rebuild.