Check whether the CARLA server is reachable and return version info.

Always call this first before running scenarios.

Returns: dict: carla_available/ready flags plus version info or an error hint describing how to start the simulator.

List the CARLA maps supported by CarlaMCP.

Returns: dict: A maps mapping of map name to a short description of its characteristics.

Generate and execute a CARLA scenario from natural language.

Builds a validated :class:ScenarioManifest from flat parameters and runs it. At least one of the cut_in_*, pedestrian_*, or weather_* groups must be provided. Optionally persists the validated spec for replay.

Args: nl_prompt (str): The natural-language description of the scenario. cut_in_speed_kmh (Optional[float]): See :func:_build_manifest. cut_in_ttc_s (Optional[float]): See :func:_build_manifest. cut_in_side (Optional[str]): See :func:_build_manifest. cut_in_ego_speed_kmh (float): See :func:_build_manifest. cut_in_map (str): See :func:_build_manifest. pedestrian_gap_s (Optional[float]): See :func:_build_manifest. pedestrian_distance_m (Optional[float]): See :func:_build_manifest. pedestrian_occluded (bool): See :func:_build_manifest. weather_condition (Optional[str]): See :func:_build_manifest. weather_intensity (Optional[float]): See :func:_build_manifest. save_as (Optional[str]): If given, save the validated spec under this name for later replay.

Returns: dict: The execution result, or an error/hint payload if validation failed.

Examples: Aggressive cut-in from the right at 120 km/h::

    run_scenario("...", cut_in_speed_kmh=120, cut_in_ttc_s=1.2,
                 cut_in_side="right")

Occluded pedestrian crossing 30 m ahead::

    run_scenario("...", pedestrian_gap_s=1.5, pedestrian_distance_m=30,
                 pedestrian_occluded=True)

Apply a weather condition to the world without spawning agents.

Args: condition (str): One of clear, rain, fog, night, rain_night. intensity (float): Severity from 0.0 (minimal) to 1.0 (maximum).

Returns: dict: The execution result.

Validate a scenario manifest JSON without executing it.

Args: manifest_json (str): JSON string of a :class:ScenarioManifest.

Returns: dict: {"valid": True, "manifest": ..., "primitives": [...]} on success, or {"valid": False, "error": ...} on failure.

Validate and persist a scenario manifest for later replay.

Args: manifest_json (str): JSON string of a :class:ScenarioManifest. name (str): Short name to save under (stored as scenarios/<name>.json).

Returns: dict: {"saved": True, "path": ...} on success, or {"saved": False, "error": ...} if validation failed.

Load a previously saved scenario spec and execute it.

Args: path (str): Saved scenario name or path (e.g. "demo" or "scenarios/demo.json").

Returns: dict: The execution result, or {"error": ...} if the spec could not be loaded.