List available ROS2 log runs with summary info.

Args: log_dir: Optional path to log directory. If not provided, resolves via MCP_ROS2_LOGS_DIR, ROS_LOG_DIR, or ~/.ros/log. limit: Maximum runs to return. Defaults to MCP_ROS2_LOGS_MAX_RESULTS (100). offset: Number of runs to skip (default 0).

Load and parse a ROS2 log run into a unified timeline.

Args: run_id: The run directory name or file path. log_dir: Optional path to log directory.

Search and filter the merged ROS2 log timeline. Use after load_run.

Flexible query tool for finding specific log entries across all nodes. Supports filtering by severity, node, time range, and text content. The context parameter enables cross-node cascade analysis by including surrounding messages from ALL nodes around each match.

Args: run_id: Run ID from list_runs or a direct path to a log file/directory. severity: Filter by severity level(s). Comma-separated: "ERROR", "WARN,ERROR,FATAL". Case-insensitive. nodes: Filter by node name(s). Comma-separated: "sensor_driver", "planner,controller". time_start: Start time filter. ISO format ("2024-04-14T14:02:31"), epoch ("1713103351.0"), or relative ("-30s" = 30s before run end, "+10s" = 10s after run start). time_end: End time filter. Same format as time_start. text: Search message content. Plain substring by default. Interpreted as regex if it contains special characters (*, +, ?, [, etc). limit: Maximum entries to return (default 50). Total match count is always reported even if truncated. offset: Number of entries to skip (default 0). context: Include N messages before and after each match across ALL nodes. Enables cascade analysis (e.g., context=5 shows what happened on other nodes around each error). Overlapping context windows are merged. log_dir: Optional path to log directory override.

Get detailed analysis of a specific node's log activity. Use after load_run.

Provides a comprehensive summary of one node including uptime, message counts per severity, top recurring message patterns, all unique errors with timestamps, any stack traces found, and average message rate.

Args: run_id: Run ID from list_runs or a direct path to a log file/directory. node: Node name to analyze (e.g., "sensor_driver", "motion_planner"). limit: Cap unique_errors and stack_traces lists. Defaults to MCP_ROS2_LOGS_MAX_RESULTS (100). offset: Number of items to skip in unique_errors and stack_traces (default 0). log_dir: Optional path to log directory override.

Get a condensed narrative summary of a ROS2 log run. Use after load_run.

Compresses the full log timeline into a readable narrative by grouping consecutive same-severity messages, highlighting severity transitions (e.g., INFO -> ERROR), and flagging gaps where a node went silent. Essential for quickly understanding what happened in a long run.

Args: run_id: Run ID from list_runs or a direct path to a log file/directory. time_start: Start time filter. ISO format, epoch, or relative ("-30s" = 30s before run end, "+10s" = 10s after run start). time_end: End time filter. Same format as time_start. nodes: Filter by node name(s). Comma-separated: "sensor_driver,planner". limit: Maximum events to return. Defaults to MCP_ROS2_LOGS_MAX_RESULTS (100). offset: Number of events to skip (default 0). log_dir: Optional path to log directory override.

Compare two ROS2 log runs to find what changed. Use after loading both runs.

Diffs a "good" run (run_id_1) against a "bad" run (run_id_2) to identify: new/missing nodes, severity distribution changes, novel error messages that only appear in run_2, the first divergence point, and timing differences for when errors first appeared.

Args: run_id_1: First run ID (typically the "good" or baseline run). run_id_2: Second run ID (typically the "bad" or failing run). log_dir: Optional path to log directory override.

Detect anomalous patterns in a ROS2 log run. Use after load_run.

Statistically analyzes the run using the first portion as a baseline for "normal" behavior, then flags deviations: rate spikes, new error patterns, severity escalations, silence gaps, and error bursts.

Args: run_id: Run ID from list_runs or a direct path to a log file/directory. baseline_ratio: Fraction of the run (by time) to use as baseline (default 0.3 = first 30%). min_severity_score: Only return anomalies with severity_score >= this value (0.0-1.0). Default 0.0 returns all. limit: Maximum anomalies to return. Defaults to MCP_ROS2_LOGS_MAX_RESULTS (100). offset: Number of anomalies to skip (default 0). log_dir: Optional path to log directory override.

List topics in a ROS2 bag file with message types and counts.

Args: run_id: Bag directory name or path. limit: Maximum topics to return. Defaults to MCP_ROS2_LOGS_MAX_RESULTS (100). offset: Number of topics to skip (default 0). log_dir: Optional path to log directory override.

Query bag messages filtered by topic and time range.

Args: run_id: Bag directory name or path. topic: Filter by topic name (e.g., "/scan", "/cmd_vel"). time_start: Start time filter (epoch or relative "-30s"). time_end: End time filter (epoch or relative). limit: Maximum messages to return (default 50). offset: Number of messages to skip (default 0). log_dir: Optional path to log directory override.

Correlate log entries with bag topic messages within a time window.

Shows what was happening on ROS2 topics around the time of log events (typically errors). Can correlate logs from one run with a bag from a different run if they share the same time window.

Args: run_id: Run ID containing the log files. bag_run_id: Run ID containing the bag file. Defaults to run_id if not provided (same run has both logs and bag). severity: Log severity filter (default "ERROR,FATAL"). window_ms: Time window in milliseconds (default 100ms, symmetric). topics: Comma-separated topic names to include (default: all topics). limit: Maximum correlations to return. Defaults to MCP_ROS2_LOGS_MAX_RESULTS (100). offset: Number of correlations to skip (default 0). log_dir: Optional path to log directory override.

Tail a ROS2 log run for new entries since last check.

First call loads the run and returns a summary. Subsequent calls return only new entries appended since the previous call. Useful for monitoring an active ROS2 system.

Args: run_id: Run ID from list_runs or a direct path to a log file/directory. limit: Maximum new entries to return. Defaults to MCP_ROS2_LOGS_MAX_RESULTS (100). offset: Number of new entries to skip (default 0). log_dir: Optional path to log directory override.