MCP Tools Reference

Rig management

`list_rigs`

List all registered rigs with connection status. Parameters: None Returns:

[
  {
    "name": "bench_01",
    "id": "uuid-...",
    "connected": true,
    "last_seen_at": 1748948400.0,
    "version": "0.15.0",
    "created_at": 1748000000.0,
    "extra_meta": { "platform": "orin_nx", "can_interfaces": ["can0", "can1"] }
  }
]

`get_rig_config`

Get connectivity status and hardware summary for one rig. Parameters:

string

required

Exact name of the rig as registered in the control plane.

Returns:

{
  "rig_name": "bench_01",
  "rig_id": "uuid-...",
  "connected": true,
  "last_seen_at": 1748948400.0,
  "version": "0.15.0",
  "created_at": 1748000000.0,
  "hardware_summary": {
    "platform": "orin_nx",
    "can_interfaces": ["can0", "can1"],
    "eth_interfaces": ["eth1"]
  }
}

`register_rig`

The API key is shown ONCE and cannot be retrieved again. Save it immediately.

Parameters:

string

required

Unique name for the rig. Letters, numbers, hyphens (e.g. orin-bench-01).

Returns:

{
  "rig_name": "orin-bench-01",
  "rig_id": "uuid-...",
  "role": "admin",
  "api_key": "chk_xxxxxxxxxxxxxxxx",
  "next_steps": [
    "Save the api_key — it will not be shown again.",
    "On the bench machine, generate the rig TOML:",
    "  crucihil discover --describe 'your hardware'",
    "Start the agent:",
    "  export CRUCIHIL_API_KEY=chk_xxxxxxxxxxxxxxxx",
    "  export CRUCIHIL_BASE_URL=<your server URL>",
    "  crucihil agent --rig rigs/orin-bench-01.toml"
  ]
}

Test runs

`list_runs`

List recent test runs, optionally filtered by rig. Parameters:

string

Filter to runs from this rig. Pass null for all rigs.

integer

default:"20"

Maximum number of runs to return. Max 500.

Returns:

[
  {
    "run_id": "uuid-...",
    "suite_name": "engine_validation",
    "status": "completed",
    "total": 5,
    "passed": 4,
    "failed": 1,
    "blocked": 0,
    "errored": 0,
    "skipped": 0,
    "started_at": 1748948400.0,
    "completed_at": 1748948421.3
  }
]

`get_run_summary`

Get a full summary of one run including pass rate and duration. Parameters:

string

required

UUID of the run.

Returns:

{
  "run_id": "uuid-...",
  "rig_id": "uuid-...",
  "suite_name": "engine_validation",
  "status": "completed",
  "started_at": 1748948400.0,
  "completed_at": 1748948421.3,
  "duration_s": 21.3,
  "total": 5,
  "passed": 4,
  "failed": 1,
  "blocked": 0,
  "errored": 0,
  "skipped": 0,
  "pass_rate": 0.8,
  "triggered_by": "CI"
}

`run_test_suite`

Create a queued run and push it to the connected agent. Parameters:

string

required

Name of the rig to run tests on.

string

required

Path to the YAML suite manifest as known to the agent (e.g. tests/suites/engine_validation.yaml).

list[string]

Optional tag filter — only tests matching at least one tag are run.

string

Optional suite type filter (e.g. smoke, regression).

Returns: Run record with run_id for polling.

`cancel_run`

Cancel a running test suite. Parameters:

string

required

UUID of the run to cancel. Only running runs can be cancelled.

Returns:

{
  "detail": "cancellation requested",
  "run_id": "uuid-..."
}

Result inspection

`get_results`

List test results for a run. Parameters:

string

required

UUID of the run.

string

Filter by status: pass, fail, blocked, error, or skip.

Returns:

[
  {
    "test_id": "engine_startup",
    "run_id": "uuid-...",
    "suite_name": "engine_validation",
    "status": "pass",
    "duration": 0.012,
    "started_at": 1748948400.1,
    "completed_at": 1748948400.112
  }
]

`get_signal_trace`

Extract signal samples for a specific signal across the most recent tests in a run. Searches up to 5 test results. Returns up to 100 samples per test. Parameters:

string

required

UUID of the run.

string

required

Signal name as stored in test results (e.g. EngineData.RPM).

Returns:

{
  "run_id": "uuid-...",
  "signal_name": "EngineData.RPM",
  "found": true,
  "tests": [
    {
      "test_id": "engine_startup",
      "samples": [
        {"t": 0.0, "value": 0.0},
        {"t": 0.1, "value": 450.0},
        {"t": 0.2, "value": 820.0}
      ],
      "total_samples": 3,
      "truncated": false
    }
  ],
  "note": null
}

`describe_failure`

Get complete failure context for one test in one run. This is the primary tool for AI failure analysis — it returns everything needed for root-cause analysis in a single call. Combines: run metadata, error messages, log lines, signal traces (up to 5 signals, 100 samples each). Parameters:

string

required

UUID of the run.

string

required

Test ID as declared in the YAML manifest.

Returns:

{
  "run_id": "uuid-...",
  "test_id": "brake_response",
  "suite_name": "engine_validation",
  "rig_id": "uuid-...",
  "triggered_by": "CI",
  "started_at": 1748948410.0,
  "completed_at": 1748948411.2,
  "duration_s": 1.2,
  "run_started_at": 1748948400.0,
  "status": "fail",
  "errors": ["Expected BrakeStatus.Pressure >= 75.0, got 0.0"],
  "error_count": 1,
  "logs": [],
  "log_count": 0,
  "captured_signals": ["BrakeStatus.Pressure", "EngineData.RPM"],
  "signal_traces": {
    "BrakeStatus.Pressure": [
      {"t": 0.0, "value": 0.0},
      {"t": 0.1, "value": 0.0},
      {"t": 1.2, "value": 0.0}
    ]
  },
  "signal_note": null,
  "pass_rate_in_run": 0.6,
  "run_status": "completed",
  "total_failures_in_run": 2
}

Signal and suite introspection

`list_signals`

Parse a DBC file and return metadata for every signal. Parameters:

string

required

Path to the .dbc file, relative to the working directory when the MCP server was started.

Returns:

{
  "dbc_path": "defs/vehicle_can.dbc",
  "message_count": 8,
  "signal_count": 24,
  "signals": [
    {
      "signal_name": "RPM",
      "message_name": "EngineData",
      "message_id": "0x100",
      "bit_length": 16,
      "factor": 0.25,
      "offset": 0.0,
      "min_val": 0.0,
      "max_val": 8000.0,
      "unit": "rpm",
      "interface": "CAN",
      "choices": null
    }
  ]
}

`list_tests`

Parse a YAML suite manifest and return metadata for every test. Parameters:

string

required

Path to the YAML manifest (e.g. tests/suites/engine_validation.yaml).

Returns:

{
  "suite_name": "engine_validation",
  "description": "Engine ECU validation suite",
  "version": "1.0.0",
  "suite_path": "tests/suites/engine_validation.yaml",
  "test_count": 5,
  "enabled_count": 4,
  "tests": [
    {
      "id": "engine_startup",
      "name": "ECU reaches idle RPM after ignition",
      "enabled": true,
      "skip_reason": null,
      "priority": "critical",
      "tags": ["engine", "startup"],
      "suite_types": ["smoke", "regression"],
      "hw_variants": ["Virtual_Sim"],
      "timeout": 5.0,
      "depends_on": [],
      "requirements": ["REQ-ENG-001"],
      "ticket": null
    }
  ]
}

AI-assisted tools

`generate_test_suite`

Scaffold a YAML manifest and Python stubs, optionally with AI-generated assertions. Parameters:

string

required

Snake-case suite name (e.g. brake_validation).

string

required

One-sentence description of what the suite validates.

string

default:"\"Virtual_Sim\""

Hardware variant to target.

string

default:"\"tests/suites\""

Directory to write both files.

list[string]

Manual context: signal names, fault scenarios, integration flows, sensor feeds.

string

Rig TOML — auto-extracts ECU names, power rails, GPIO presence.

string

DBC file — auto-extracts all MessageName.SignalName pairs.

string

Provider override: anthropic, openai, gemini.

Returns:

{
  "suite_name": "brake_validation",
  "yaml_path": "tests/suites/brake_validation.yaml",
  "py_path": "tests/suites/brake_validation.py",
  "module_path": "tests.suites.brake_validation",
  "auto_context_count": 26,
  "context_items_used": [...],
  "next_steps": [...]
}

`analyze_component`

Extract the signal interface contract of a C/C++ software component. Requires pip install 'crucihil[analyze]'. Parameters:

string

required

Path to a .c/.cpp/.h file or a directory of source files.

string

required

Label for this component in the output (e.g. BrakeController).

list[string]

One or more DBC file paths. Merged with TOML-discovered DBCs.

string

Rig TOML — auto-discovers DBCs from [rig.definitions], infers interface type from key name.

list[string]

Shim header directories or SWC paths to parse alongside the primary source.

string

Provider override: anthropic, openai, gemini.

Returns:

{
  "component": "BrakeController",
  "files_analyzed": 7,
  "identifiers_extracted": 87,
  "signal_corpus_size": 26,
  "inputs": [
    {
      "signal": "BrakeDemand.Value",
      "dbc": "/path/to/chassis.dbc",
      "interface": "ETH",
      "matched_identifier": "Rte_Read_BC_BrakeDemandVal",
      "confidence": 0.95,
      "review_required": false
    }
  ],
  "outputs": [...],
  "unmatched_identifiers": [...],
  "confidence_summary": { "high": 5, "medium": 0, "low": 0 },
  "review_required_count": 0
}

Authoring and verification

`author_component`

Author a self-verified test suite from component source code. Chains: analyze (signal contract with evidence chains) → generate → baseline gate (must run green on the rig, with AI repair rounds) → write. Broken AI output never reaches disk — a deterministic static generator is the guaranteed fallback. Runs entirely on the machine hosting the MCP server (source code and rig TOML are local paths). Writes the suite files into output_dir. Parameters:

string

required

Component source file or directory (local path).

string

required

Component label (e.g. BrakeController).

string

default:"\"rigs/virtual.toml\""

Rig the baseline gate runs against (virtual by default).

list[string]

DBC file paths for the signal corpus.

string

Firmware repo root — enables cross-component port-graph resolution (shared-memory indirection).

string

default:"\"tests/suites\""

Where the promoted suite is written.

string

Suite name (default: <component>_contract).

string

default:"\"crucihil\""

Output format: crucihil (native YAML+Python), pytest, or robot.

string

Provider override: anthropic, openai, gemini (auto-detected from env vars if omitted).

integer

default:"2"

AI repair rounds before the static fallback.

Returns:

{
  "suite_name": "brake_controller_contract",
  "framework": "crucihil",
  "yaml_path": "tests/suites/brake_controller_contract.yaml",
  "py_path": "tests/suites/brake_controller_contract.py",
  "contract_path": "contracts/BrakeController.json",
  "generator": "ai",
  "test_functions": ["test_brake_demand_response", "..."],
  "review_tests": [],
  "baseline": { "total": 5, "passed": 5 },
  "repair_attempts": 0
}

On failure, returns {"error": "...", "stage": "analyze" | "generate" | "baseline" | "write"}.

`verify_suite`

Mutation-verify a test suite and return its strength report. Runs the suite once as a baseline, then once per mutation. Outcome per test: caught (test failed — good), missed (test stayed green while the behavior was broken — vacuous), wrong_reason (test went blocked/error instead of failing). A suite score of 1.0 means every planned mutation was caught. Works on native CruciHiL suites and on existing pytest / Robot Framework suites with zero rewrites. Parameters:

string

required

Native YAML manifest, or a pytest/Robot test tree when framework is given. A YAML manifest with a framework: field routes automatically.

string

default:"\"rigs/virtual.toml\""

Rig the verification runs against.

string

pytest | robot to verify a foreign suite unchanged; omit for native (or manifest-declared).

string

Contract artifact (contracts/<component>.json) — sharpens the mutation plan with the component’s real outputs.

integer

default:"20"

Cap on mutation runs (priority-ordered).

string

Also save the full report JSON here (readable later via get_strength_report).

Returns:

{
  "suite_name": "brake_controller_contract",
  "rig": "Virtual_Sim",
  "generated_at": "2026-07-05T12:00:00+00:00",
  "suite_score": 1.0,
  "per_test": {
    "brake_demand_response": {
      "caught": 3, "missed": 0, "wrong_reason": 0,
      "planned": 3, "score": 1.0
    }
  },
  "results": [
    {
      "test_id": "brake_demand_response",
      "mutation": {
        "mutation_type": "dead_dut",
        "label": "DUT silent — all output messages stopped",
        "params": {}
      },
      "outcome": "caught",
      "evidence": "Expected BrakeStatus.Pressure >= 75.0, got timeout",
      "baseline_status": "pass",
      "mutated_status": "fail"
    }
  ],
  "unverifiable": {},
  "planned_mutations": [...],
  "report_path": "reports/strength.json"
}

report_path appears only when it was requested. On failure, returns {"error": "..."}.

`get_strength_report`

Read a previously saved mutation strength report JSON. Parameters:

string

required

Path passed to verify_suite’s report_path (or crucihil verify --report).

Returns: The saved strength report (same shape as verify_suite), or {"error": "..."} if the file is missing or not valid JSON.

`detect_coverage_gaps`

Find what a component’s tests never exercised (coverage gaps). Compares the component contract (which signals the component touches) against the signal traces recorded by a run’s tests. Reports signals never tested at all and value regions never reached (“never tested BrakePressure > 80% of range”), each with a proposed gap test whose description can be passed straight to generate_test_suite. Parameters:

string

required

The run whose recorded traces to analyze.

string

required

Contract artifact (contracts/<component>.json).

list[string]

DBCs for signal ranges (defaults to the DBCs the contract entries reference).

Returns:

{
  "component": "BrakeController",
  "contract_signals": 4,
  "traced_tests": ["brake_demand_response"],
  "signals": {
    "BrakeStatus.Pressure": {
      "dbc_min": 0.0,
      "dbc_max": 100.0,
      "observed_min": 0.0,
      "observed_max": 60.0,
      "tested_by": ["brake_demand_response"]
    }
  },
  "gaps": [
    {
      "signal": "BrakeStatus.Pressure",
      "kind": "upper_range",
      "detail": "never tested BrakeStatus.Pressure > 60.0 — the top 40% of its DBC range [0.0, 100.0] is unexercised",
      "threshold": 60.0
    }
  ],
  "proposed_tests": [
    {
      "signal": "BrakeStatus.Pressure",
      "value": 100.0,
      "description": "Set BrakeStatus.Pressure to 100.0 and verify the component's response — ...",
      "generate_test_suite_args": { "suite_name": "gap_brakestatus_pressure", "description": "..." }
    }
  ],
  "run_id": "uuid-..."
}

Gap kind is one of untested, upper_range, lower_range. On failure, returns {"error": "..."}.

​Rig management

​list_rigs

​get_rig_config

​register_rig

​Test runs

​list_runs

​get_run_summary

​run_test_suite

​cancel_run

​Result inspection

​get_results

​get_signal_trace

​describe_failure

​Signal and suite introspection

​list_signals

​list_tests

​AI-assisted tools

​generate_test_suite

​analyze_component

​Authoring and verification

​author_component

​verify_suite

​get_strength_report

​detect_coverage_gaps

​See also

Rig management

`list_rigs`

`get_rig_config`

`register_rig`

Test runs

`list_runs`

`get_run_summary`

`run_test_suite`

`cancel_run`

Result inspection

`get_results`

`get_signal_trace`

`describe_failure`

Signal and suite introspection

`list_signals`

`list_tests`

AI-assisted tools

`generate_test_suite`

`analyze_component`

Authoring and verification

`author_component`

`verify_suite`

`get_strength_report`

`detect_coverage_gaps`

See also