health_check
Run this read-only diagnostic first when something looks wrong: it reports TopicForge's runtime mode, ROS 2/DDS backend status, tool availability, domain ID, and discovery tracker health.
Instructions
Report TopicForge environment state as a HealthReport: effective runtime mode (live or mock), ros_backend and dds_backend, ros_tools_available, ros2_available, ros2_distro (fed by the ROS_DISTRO env var), dds_domain_id and observed_domain_note (only the DDS domain joined at startup is observed; programs on other domains are invisible), the server version and the server-side sample cap. Reading mode: live with ros_backend none means the DDS tools are live and the ROS 2 tools are not available (a DDS-only setup: use list_endpoints for topics and wiring). With dds_backend none, dds_inactive_reason says why: backend not selected, binding not installed, or adapter failed to start. payload_decoding is disabled: DDS user-topic payloads are not decoded. dds_security is not_supported: on a secured domain participants show up but protected endpoints and data do not. For a live DDS backend it also reports dds_domain_id, observer_started_ns and now_ns (how long TopicForge has been watching: nothing before observer_started_ns was observed) and the discovery tracker status tracker_running / tracker_passes / tracker_errors / tracker_last_pass_ns / tracker_cache_evictions (errors or evictions above 0, or a stale last pass, mean the discovery data has gaps). Always succeeds: call it first when something looks wrong. Read-only; no side effects.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | Runtime mode of the adapter actually serving requests: `mock` or `live`. `live` with `ros_backend` `none` means the DDS tools are live and the ROS 2 tools are not available. Can differ from `requested_mode` when a live backend could not start (e.g. `live` requested without `ros2` installed falls back to `mock`). | |
| now_ns | No | Server wall-clock time (ns since epoch) when this report was built. | |
| dds_backend | No | DDS backend of the adapter actually serving requests. `none` when the DDS module is not active (default for ROS2-only installs). `mock` for synthetic fixtures. `cyclone` requires `pip install "topicforge[dds-cyclone]"` (Eclipse CycloneDDS); `fast` requires a Fast DDS Python binding built from eProsima sources (not on PyPI); `opendds` and `dust` are permanent stub adapters that never serve. | none |
| ros2_distro | No | Value of `ROS_DISTRO` if set in the environment. **Env disclosure, by design**: under the local-trust threat model (see README 'Security model'), the MCP client is a trusted agent on a machine the user controls, and exposing the ROS2 distro lets it adapt to e.g. `humble`/`jazzy` differences. For a hosted multi-tenant TopicForge endpoint this field would be scrubbed . | |
| ros_backend | No | Active ROS2 backend. `ros2_cli` when the `ros2` CLI is on PATH and live mode resolves to a Ros2CliAdapter (alone or as the ROS half of a composite). `mock` when MockAdapter serves the ROS surface. `none` when no ROS2 backend is active (e.g. DDS-only live install with no `ros2` CLI). Together with `dds_backend` it tells the ROS2 and DDS halves of the runtime apart. | none |
| dds_security | No | DDS Security is not handled. On a secured domain TopicForge can show participants but not protected endpoints or data. | not_supported |
| dds_domain_id | No | DDS domain id observed when the DDS module is active. | |
| requested_mode | Yes | Mode requested via configuration (may be `auto`). | |
| ros2_available | Yes | Whether a `ros2` CLI is on PATH. | |
| server_version | Yes | TopicForge server version (matches the PyPI release of the `topicforge` package). | |
| tracker_errors | No | Discovery tracker passes that raised (swallowed and logged). Non-zero means gaps. | |
| tracker_passes | No | Completed discovery tracker passes since start. | |
| tracker_running | No | Whether the continuous discovery tracker thread is alive (Cyclone). `None` when the backend has no tracker. | |
| max_sample_count | Yes | Server-side cap on the number of samples returned per `sample_messages` call. Requests above this limit are silently clamped; the value is exposed here so a client can size its requests proactively. Constant within a given server version. | |
| payload_decoding | No | Whether DDS user-topic payloads are decoded. `disabled` today: `peek_dds_samples` and `topic_metrics` do not return message content for user topics. | disabled |
| dds_inactive_reason | No | Why `dds_backend` is `none` while the ROS 2 CLI serves: the backend was not selected (`TOPICFORGE_DDS_BACKEND` unset or `mock`), its Python binding is not installed, or the binding is installed but the adapter failed to start. `null` when a DDS backend is serving or the cause is not known. | |
| observer_started_ns | No | Wall-clock time (ns since epoch) when the DDS observer joined the bus. Nothing earlier than this was watched: `now_ns` minus this is how long TopicForge has been observing. `None` without a live DDS observer. | |
| ros_tools_available | No | True when the ROS 2 tools (`list_topics`, `get_topic_info`, `sample_messages`, `analyze_bag`, `peek_bag_samples`) can run, i.e. `ros_backend` is not `none`. False on a DDS-only setup: use `list_endpoints` for topics and wiring there. | |
| middleware_available | No | True when a DDS backend is serving (`dds_backend` is not `none`). When the DDS module is inactive (`dds_backend == 'none'`), whether the *configured* backend's Python bindings are importable, so a missing binding is visible. | |
| observed_domain_note | No | Plain statement of which DDS domain is observed, set when a DDS module is active: only the domain joined at startup is visible, a program on another domain is invisible. | |
| tracker_last_pass_ns | No | Wall-clock time (ns since epoch) of the last completed tracker pass. A value far older than `now_ns` means lifecycle is stale. | |
| payload_decoding_reason | No | One-line reason for `payload_decoding`. | user-topic payload decoding is switched off until it is validated on a real bus; builtin discovery topics are still readable |
| tracker_cache_evictions | No | Discovery entries dropped because a tracker cache was full (4096 per cache). Non-zero means the bus is bigger than what is listed. |