topicforge 0.7.1__tar.gz → 0.7.2__tar.gz

{topicforge-0.7.1 → topicforge-0.7.2}/CHANGELOG.md

@@ -7,6 +7,58 @@ and this project adheres to [Semantic Versioning 2.0.0](https://semver.org/spec/
 
 ## [Unreleased]
 
+## [0.7.2] - 2026-10-18
+
+TF tree inspection, ROS 2 node names on DDS participants, and a flag for the `ros2` CLI
+processes TopicForge itself spawns. Additive only: no field or input was renamed, removed or
+retyped (`docs/CONTRACT.md` section 9). Validated on the Docker ROS 2 bench (Humble and Jazzy,
+rmw_fastrtps and rmw_cyclonedds).
+
+### Added
+
+- `inspect_tf`, the 15th tool (additive, `docs/CONTRACT.md` section 9.8): rebuilds the TF tree
+  from `/tf_static` (latched, read once) and `/tf` (listened to for `window_s`, 1 to 20 s) and
+  returns `TfReport`: every frame with its parent, `kind` (static, dynamic, both), `age_s`,
+  `stale`, and two rates (`observed_frequency_hz` on wall time, `sim_frequency_hz` on header
+  stamps), the `roots`, and `findings` (`stale`, `two_parents`, `disconnected`,
+  `static_and_dynamic`, `cycle`, `no_path`). Ages are measured on the stamps against the newest
+  `/tf` stamp, so they hold on sim time; `real_time_factor` says when the robot runs on
+  `/clock`. `source_frame` and `target_frame` give the chain between two frames in `path`.
+  ROS lane, `ros2` CLI only (a DDS-only setup raises the usual error); the mock serves a fixed
+  tree with one stale frame. The mock `/tf` sample no longer carries `base_link -> laser`,
+  which moved to the new mock topic `/tf_static`.
+- `list_participants` fills `node_names` (and `node_names_source` `ros_discovery_info`) on
+  the Cyclone backend: a fourth reader on `ros_discovery_info` plus a hand-written XCDR1
+  decoder (`adapters/common/ros_discovery.py`) that accepts the 24-byte (Humble) and
+  16-byte (Jazzy and later) gid. Checked on the Docker ROS 2 bench (Humble and Jazzy, rmw_fastrtps
+  and rmw_cyclonedds). Mock participants get names from the mock node fixtures.
+- `ParticipantInfo.is_topicforge_cli`: the `ros2` CLI processes TopicForge itself spawns
+  (right after `get_node_info` they stay on the bus 0.3-2 s, so a 7-participant bus
+  listed 8) are flagged, never hidden, and the listing `note` explains them. Matched by
+  `_ros2cli_<pid>` node name, or (only when the participant's hostname is known and is this
+  machine's) Fast DDS GUID pid bits or Cyclone `__Pid`, against a 30 s ring of pids recorded
+  by the process runner; a participant announcing another host is never flagged. Limit: on
+  Windows `ros2.exe` spawns a child process, so the recorded pid rarely matches and the flag
+  mostly falls back to the time-correlation note (`may be its ghosts`).
+- `ParticipantListing.restarts_by_node`: `restarts_by_name` keyed by ROS 2 node name.
+
+### Changed
+
+- `MiddlewareAdapter` gains `capture_tf(window_s)` (needed by `inspect_tf`). Third-party
+  adapters implementing the protocol must add it; DDS-only ones can raise the DDS-only error
+  (`DDS_ONLY_ERROR_MSG`).
+
+### Fixed
+
+- Ground-truth comparator (`scripts/ground_truth`, tooling only: no change to the MCP tools or
+  the output contract). Two real OmniSim runs on 0.7.1 showed false FAILs that were the host's
+  or the harness's doing, not TopicForge's: wall-clock frequency rows are now WARN at most when
+  the kit's real-time factor is under 0.5 or the wall/sim ratios of the kit and TopicForge
+  differ by more than 25 percent (simulated-time rows still gate); `/parameter_events` and
+  `/rosout` writer/reader counts are no longer compared; `ros2` CLI participants started by
+  TopicForge itself (`is_topicforge_cli` or a `_ros2cli_` node name) are ignored and reported.
+  `drive.py` now runs the DDS calls before `get_node_info` and settles 3 s before them and at the end.
+
 ## [0.7.1] - 2026-10-14
 
 QoS fix suggestions and agent-friction fixes from the blind evaluation (`docs/EVAL.md`). Additive only: no field or
@@ -1661,7 +1713,8 @@ Initial MVP release of TopicForge: ROS Topic Inspector & Bag Analyzer MCP server
 - The write path (publishing, commanding robots) is intentionally out of scope for the MVP.
 - `analyze_bag` in live mode parses `ros2 bag info` text output; deeper anomaly detection remains mock-only for now.
 
-[Unreleased]: https://github.com/yaniswav/TopicForge/compare/v0.7.1...HEAD
+[Unreleased]: https://github.com/yaniswav/TopicForge/compare/v0.7.2...HEAD
+[0.7.2]: https://github.com/yaniswav/TopicForge/compare/v0.7.1...v0.7.2
 [0.7.1]: https://github.com/yaniswav/TopicForge/compare/v0.7.0...v0.7.1
 [0.7.0]: https://github.com/yaniswav/TopicForge/compare/v0.6.4...v0.7.0
 [0.6.4]: https://github.com/yaniswav/TopicForge/compare/v0.6.3...v0.6.4

{topicforge-0.7.1 → topicforge-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: topicforge
-Version: 0.7.1
+Version: 0.7.2
 Summary: ROS Topic Inspector & Bag Analyzer MCP server for AI agents
 Project-URL: Homepage, https://github.com/yaniswav/TopicForge
 Project-URL: Repository, https://github.com/yaniswav/TopicForge
@@ -73,7 +73,7 @@ A read-only MCP (Model Context Protocol) server that lets an AI agent inspect a
 
 Every tool also declares itself read-only in the MCP protocol (`readOnlyHint`, `destructiveHint=false`, `idempotentHint`, with an honest `openWorldHint`), and a test fails if any tool lacks it. See [`SECURITY.md`](SECURITY.md#read-only-guarantee-architecture-declaration-proof) for the guarantee and its limits.
 
-It gives the agent fourteen typed tools that return frozen Pydantic schemas (output contract 2: one object per tool, one `note`, units in the field names; see [`docs/CONTRACT.md`](docs/CONTRACT.md)), identical whether the server talks to a real robot or to its built-in mock fixtures. Ask why `nav_planner` gets no scan, and the agent reads the bus, finds the BEST_EFFORT writer facing a RELIABLE reader and names the incompatible policy (see [`examples/02-debug-qos-mismatch.md`](examples/02-debug-qos-mismatch.md)). It is meant for ROS2 developers, robotics ML/CV engineers and teams that cannot accept a write path into a production stack.
+It gives the agent fifteen typed tools that return frozen Pydantic schemas (output contract 2: one object per tool, one `note`, units in the field names; see [`docs/CONTRACT.md`](docs/CONTRACT.md)), identical whether the server talks to a real robot or to its built-in mock fixtures. Ask why `nav_planner` gets no scan, and the agent reads the bus, finds the BEST_EFFORT writer facing a RELIABLE reader and names the incompatible policy (see [`examples/02-debug-qos-mismatch.md`](examples/02-debug-qos-mismatch.md)). It is meant for ROS2 developers, robotics ML/CV engineers and teams that cannot accept a write path into a production stack.
 
 For DDS, TopicForge joins a domain as a read-only participant through one open-source binding (Eclipse CycloneDDS from PyPI) and reads the builtin discovery topics that the OMG DDS-RTPS protocol standardizes. Cyclone DDS, Fast DDS and Dust DDS participants have been observed on live buses: the Fast DDS ones on every CI run of the ROS 2 test bench (Humble and Jazzy with `rmw_fastrtps_cpp`) and in the OmniSim validation. RTI Connext, OpenDDS and CoreDX announce themselves through the same standard discovery, but none of them has been observed yet. This covers discovery only: participants, readers, writers and their QoS. See [`docs/dds-interop-matrix.md`](docs/dds-interop-matrix.md).
 
@@ -103,7 +103,7 @@ The server speaks MCP over stdio and waits for a client, so wire it into one. Fo
 
 Then ask it to list the topics or to analyze `/tmp/demo.mcap`. For Claude Code: `claude mcp add topicforge -- topicforge`. If the client cannot launch the server (WSL2 to Windows, a robot over an SSH tunnel), `topicforge --transport streamable-http --port 8765` serves `http://127.0.0.1:8765/mcp` on loopback only; see [`docs/CLIENTS.md`](docs/CLIENTS.md#local-http-transport).
 
-**Other MCP clients.** Ready-to-paste configs for Claude Desktop, Cursor, VS Code, Windsurf, Cline, Roo Code, Continue, Zed, JetBrains, Codex, Gemini CLI, Goose and more are in [`docs/CLIENTS.md`](docs/CLIENTS.md). One-click: [Add to Cursor](https://cursor.com/install-mcp?name=topicforge&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJ0b3BpY2ZvcmdlPT0wLjcuMSIsInRvcGljZm9yZ2UiXSwiZW52Ijp7IlRPUElDRk9SR0VfTU9ERSI6ImF1dG8iLCJUT1BJQ0ZPUkdFX0REU19CQUNLRU5EIjoiY3ljbG9uZSIsIlRPUElDRk9SR0VfRERTX0RPTUFJTl9JRCI6IjAifX0%3D) | [Install in VS Code](https://vscode.dev/redirect/mcp/install?name=topicforge&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22--from%22%2C%22topicforge%3D%3D0.7.1%22%2C%22topicforge%22%5D%2C%22env%22%3A%7B%22TOPICFORGE_MODE%22%3A%22auto%22%2C%22TOPICFORGE_DDS_BACKEND%22%3A%22cyclone%22%2C%22TOPICFORGE_DDS_DOMAIN_ID%22%3A%220%22%7D%7D).
+**Other MCP clients.** Ready-to-paste configs for Claude Desktop, Cursor, VS Code, Windsurf, Cline, Roo Code, Continue, Zed, JetBrains, Codex, Gemini CLI, Goose and more are in [`docs/CLIENTS.md`](docs/CLIENTS.md). One-click: [Add to Cursor](https://cursor.com/install-mcp?name=topicforge&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJ0b3BpY2ZvcmdlPT0wLjcuMiIsInRvcGljZm9yZ2UiXSwiZW52Ijp7IlRPUElDRk9SR0VfTU9ERSI6ImF1dG8iLCJUT1BJQ0ZPUkdFX0REU19CQUNLRU5EIjoiY3ljbG9uZSIsIlRPUElDRk9SR0VfRERTX0RPTUFJTl9JRCI6IjAifX0%3D) | [Install in VS Code](https://vscode.dev/redirect/mcp/install?name=topicforge&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22--from%22%2C%22topicforge%3D%3D0.7.2%22%2C%22topicforge%22%5D%2C%22env%22%3A%7B%22TOPICFORGE_MODE%22%3A%22auto%22%2C%22TOPICFORGE_DDS_BACKEND%22%3A%22cyclone%22%2C%22TOPICFORGE_DDS_DOMAIN_ID%22%3A%220%22%7D%7D).
 
 Setup for a real ROS2 environment (WSL2, Linux, Docker, native Windows) is in [`docs/TESTING.md`](docs/TESTING.md); recurring monitoring prompts and the privacy contract are in [`docs/TUTORIEL.md`](docs/TUTORIEL.md).
 
@@ -118,6 +118,7 @@ Every response except `health_check` carries `mode_effective` (`"live"` or `"moc
 | `get_topic_info`        | Message type, publisher/subscriber counts and QoS for one topic                                  |
 | `list_nodes`            | ROS 2 nodes on the graph: names, namespaces, duplicate names (one `ros2 node list` call)         |
 | `get_node_info`         | One node's publishers, subscribers, services, actions, parameters (secrets masked) and `use_sim_time`; a node that does not answer is reported, not an error |
+| `inspect_tf`            | The TF tree from `/tf_static` and `/tf`: roots, stale and two-parent frames, disconnected trees, sim-time-safe ages and rates, optional path between two frames |
 | `sample_messages`       | Peek recent messages on a ROS2 topic (count capped at 50)                                        |
 | `analyze_bag`           | Summarize a `.mcap` / `.db3` recording or `rosbag2_*` directory (via `ros2 bag info`)            |
 | `list_participants`     | DDS participants on the domain: vendor, `name` (EntityName QoS, Cyclone) and `hostname`          |
@@ -150,7 +151,7 @@ pip install "topicforge[dds]"                    # alias, kept so older commands
 TOPICFORGE_DDS_BACKEND=cyclone python -m topicforge
 ```
 
-`TOPICFORGE_DDS_BACKEND` accepts `mock` (default), `cyclone`, `fast` and `auto` (`fast`, then `cyclone`, then `mock`, whichever binding imports). The default `mock` selects no DDS backend: installing the Cyclone binding is not enough, you must also set `TOPICFORGE_DDS_BACKEND=cyclone`. With `TOPICFORGE_MODE=live` and no backend selected, the DDS tools raise `DDS module is not active: ...` with the actual cause (backend not selected, binding not installed, or binding installed but the adapter failed to start), and `health_check` reports `dds_backend: "none"` plus `dds_inactive_note`. An explicit value is honoured with or without `ros2` on PATH, in any mode except `mock`. If the binding is missing or the participant cannot start, the server logs a warning naming the cause and falls back to the ROS2 CLI alone, or to the mock fixtures. When both `ros2` and a DDS backend are up, a composite adapter routes the six `ros2` CLI tools (`list_topics`, `get_topic_info`, `list_nodes`, `get_node_info`, `sample_messages`, `analyze_bag`) to the CLI and the six DDS tools to the DDS backend; `peek_bag_samples` reads bags without the CLI.
+`TOPICFORGE_DDS_BACKEND` accepts `mock` (default), `cyclone`, `fast` and `auto` (`fast`, then `cyclone`, then `mock`, whichever binding imports). The default `mock` selects no DDS backend: installing the Cyclone binding is not enough, you must also set `TOPICFORGE_DDS_BACKEND=cyclone`. With `TOPICFORGE_MODE=live` and no backend selected, the DDS tools raise `DDS module is not active: ...` with the actual cause (backend not selected, binding not installed, or binding installed but the adapter failed to start), and `health_check` reports `dds_backend: "none"` plus `dds_inactive_note`. An explicit value is honoured with or without `ros2` on PATH, in any mode except `mock`. If the binding is missing or the participant cannot start, the server logs a warning naming the cause and falls back to the ROS2 CLI alone, or to the mock fixtures. When both `ros2` and a DDS backend are up, a composite adapter routes the seven `ros2` CLI tools (`list_topics`, `get_topic_info`, `list_nodes`, `get_node_info`, `inspect_tf`, `sample_messages`, `analyze_bag`) to the CLI and the six DDS tools to the DDS backend; `peek_bag_samples` reads bags without the CLI.
 
 A Fast DDS adapter exists but has never run against a bus, and its `fastdds` Python binding is not on PyPI: build it from eProsima's sources and install it next to TopicForge. There is no `[dds-fast]` extra. Any other value (`rti`, `opensplice`, `coredx`, `intercom`, `opendds`, `dust`) is rejected at startup with an error that lists the valid ones; Cyclone already sees those vendors' participants through standard discovery. Full backend selection, the routing table and the QoS mismatch scenario are in [`docs/DDS_QUICKSTART.md`](docs/DDS_QUICKSTART.md); error messages are in [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md).
 
@@ -202,10 +203,10 @@ When on, each tool call emits one event with exactly six fields:
 
 | Field        | Example         | Notes                                                       |
 | ------------ | --------------- | ----------------------------------------------------------- |
-| `tool_name`  | `"list_topics"` | One of the fourteen tools, never argument values            |
+| `tool_name`  | `"list_topics"` | One of the fifteen tools, never argument values            |
 | `latency_ms` | `12.34`         | Handler wall-clock duration, 2 decimals                     |
 | `mode`       | `"mock"`        | Mode of the adapter actually serving: `mock` or `live`      |
-| `version`    | `"0.7.1"`       | TopicForge server version                                   |
+| `version`    | `"0.7.2"`       | TopicForge server version                                   |
 | `session_id` | `"a1b2c3..."`   | Random UUID per process, never persisted                    |
 | `success`    | `true`          | Whether the handler returned or raised                      |
 

{topicforge-0.7.1 → topicforge-0.7.2}/README.md

@@ -12,7 +12,7 @@ A read-only MCP (Model Context Protocol) server that lets an AI agent inspect a
 
 Every tool also declares itself read-only in the MCP protocol (`readOnlyHint`, `destructiveHint=false`, `idempotentHint`, with an honest `openWorldHint`), and a test fails if any tool lacks it. See [`SECURITY.md`](SECURITY.md#read-only-guarantee-architecture-declaration-proof) for the guarantee and its limits.
 
-It gives the agent fourteen typed tools that return frozen Pydantic schemas (output contract 2: one object per tool, one `note`, units in the field names; see [`docs/CONTRACT.md`](docs/CONTRACT.md)), identical whether the server talks to a real robot or to its built-in mock fixtures. Ask why `nav_planner` gets no scan, and the agent reads the bus, finds the BEST_EFFORT writer facing a RELIABLE reader and names the incompatible policy (see [`examples/02-debug-qos-mismatch.md`](examples/02-debug-qos-mismatch.md)). It is meant for ROS2 developers, robotics ML/CV engineers and teams that cannot accept a write path into a production stack.
+It gives the agent fifteen typed tools that return frozen Pydantic schemas (output contract 2: one object per tool, one `note`, units in the field names; see [`docs/CONTRACT.md`](docs/CONTRACT.md)), identical whether the server talks to a real robot or to its built-in mock fixtures. Ask why `nav_planner` gets no scan, and the agent reads the bus, finds the BEST_EFFORT writer facing a RELIABLE reader and names the incompatible policy (see [`examples/02-debug-qos-mismatch.md`](examples/02-debug-qos-mismatch.md)). It is meant for ROS2 developers, robotics ML/CV engineers and teams that cannot accept a write path into a production stack.
 
 For DDS, TopicForge joins a domain as a read-only participant through one open-source binding (Eclipse CycloneDDS from PyPI) and reads the builtin discovery topics that the OMG DDS-RTPS protocol standardizes. Cyclone DDS, Fast DDS and Dust DDS participants have been observed on live buses: the Fast DDS ones on every CI run of the ROS 2 test bench (Humble and Jazzy with `rmw_fastrtps_cpp`) and in the OmniSim validation. RTI Connext, OpenDDS and CoreDX announce themselves through the same standard discovery, but none of them has been observed yet. This covers discovery only: participants, readers, writers and their QoS. See [`docs/dds-interop-matrix.md`](docs/dds-interop-matrix.md).
 
@@ -42,7 +42,7 @@ The server speaks MCP over stdio and waits for a client, so wire it into one. Fo
 
 Then ask it to list the topics or to analyze `/tmp/demo.mcap`. For Claude Code: `claude mcp add topicforge -- topicforge`. If the client cannot launch the server (WSL2 to Windows, a robot over an SSH tunnel), `topicforge --transport streamable-http --port 8765` serves `http://127.0.0.1:8765/mcp` on loopback only; see [`docs/CLIENTS.md`](docs/CLIENTS.md#local-http-transport).
 
-**Other MCP clients.** Ready-to-paste configs for Claude Desktop, Cursor, VS Code, Windsurf, Cline, Roo Code, Continue, Zed, JetBrains, Codex, Gemini CLI, Goose and more are in [`docs/CLIENTS.md`](docs/CLIENTS.md). One-click: [Add to Cursor](https://cursor.com/install-mcp?name=topicforge&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJ0b3BpY2ZvcmdlPT0wLjcuMSIsInRvcGljZm9yZ2UiXSwiZW52Ijp7IlRPUElDRk9SR0VfTU9ERSI6ImF1dG8iLCJUT1BJQ0ZPUkdFX0REU19CQUNLRU5EIjoiY3ljbG9uZSIsIlRPUElDRk9SR0VfRERTX0RPTUFJTl9JRCI6IjAifX0%3D) | [Install in VS Code](https://vscode.dev/redirect/mcp/install?name=topicforge&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22--from%22%2C%22topicforge%3D%3D0.7.1%22%2C%22topicforge%22%5D%2C%22env%22%3A%7B%22TOPICFORGE_MODE%22%3A%22auto%22%2C%22TOPICFORGE_DDS_BACKEND%22%3A%22cyclone%22%2C%22TOPICFORGE_DDS_DOMAIN_ID%22%3A%220%22%7D%7D).
+**Other MCP clients.** Ready-to-paste configs for Claude Desktop, Cursor, VS Code, Windsurf, Cline, Roo Code, Continue, Zed, JetBrains, Codex, Gemini CLI, Goose and more are in [`docs/CLIENTS.md`](docs/CLIENTS.md). One-click: [Add to Cursor](https://cursor.com/install-mcp?name=topicforge&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJ0b3BpY2ZvcmdlPT0wLjcuMiIsInRvcGljZm9yZ2UiXSwiZW52Ijp7IlRPUElDRk9SR0VfTU9ERSI6ImF1dG8iLCJUT1BJQ0ZPUkdFX0REU19CQUNLRU5EIjoiY3ljbG9uZSIsIlRPUElDRk9SR0VfRERTX0RPTUFJTl9JRCI6IjAifX0%3D) | [Install in VS Code](https://vscode.dev/redirect/mcp/install?name=topicforge&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22--from%22%2C%22topicforge%3D%3D0.7.2%22%2C%22topicforge%22%5D%2C%22env%22%3A%7B%22TOPICFORGE_MODE%22%3A%22auto%22%2C%22TOPICFORGE_DDS_BACKEND%22%3A%22cyclone%22%2C%22TOPICFORGE_DDS_DOMAIN_ID%22%3A%220%22%7D%7D).
 
 Setup for a real ROS2 environment (WSL2, Linux, Docker, native Windows) is in [`docs/TESTING.md`](docs/TESTING.md); recurring monitoring prompts and the privacy contract are in [`docs/TUTORIEL.md`](docs/TUTORIEL.md).
 
@@ -57,6 +57,7 @@ Every response except `health_check` carries `mode_effective` (`"live"` or `"moc
 | `get_topic_info`        | Message type, publisher/subscriber counts and QoS for one topic                                  |
 | `list_nodes`            | ROS 2 nodes on the graph: names, namespaces, duplicate names (one `ros2 node list` call)         |
 | `get_node_info`         | One node's publishers, subscribers, services, actions, parameters (secrets masked) and `use_sim_time`; a node that does not answer is reported, not an error |
+| `inspect_tf`            | The TF tree from `/tf_static` and `/tf`: roots, stale and two-parent frames, disconnected trees, sim-time-safe ages and rates, optional path between two frames |
 | `sample_messages`       | Peek recent messages on a ROS2 topic (count capped at 50)                                        |
 | `analyze_bag`           | Summarize a `.mcap` / `.db3` recording or `rosbag2_*` directory (via `ros2 bag info`)            |
 | `list_participants`     | DDS participants on the domain: vendor, `name` (EntityName QoS, Cyclone) and `hostname`          |
@@ -89,7 +90,7 @@ pip install "topicforge[dds]"                    # alias, kept so older commands
 TOPICFORGE_DDS_BACKEND=cyclone python -m topicforge
 ```
 
-`TOPICFORGE_DDS_BACKEND` accepts `mock` (default), `cyclone`, `fast` and `auto` (`fast`, then `cyclone`, then `mock`, whichever binding imports). The default `mock` selects no DDS backend: installing the Cyclone binding is not enough, you must also set `TOPICFORGE_DDS_BACKEND=cyclone`. With `TOPICFORGE_MODE=live` and no backend selected, the DDS tools raise `DDS module is not active: ...` with the actual cause (backend not selected, binding not installed, or binding installed but the adapter failed to start), and `health_check` reports `dds_backend: "none"` plus `dds_inactive_note`. An explicit value is honoured with or without `ros2` on PATH, in any mode except `mock`. If the binding is missing or the participant cannot start, the server logs a warning naming the cause and falls back to the ROS2 CLI alone, or to the mock fixtures. When both `ros2` and a DDS backend are up, a composite adapter routes the six `ros2` CLI tools (`list_topics`, `get_topic_info`, `list_nodes`, `get_node_info`, `sample_messages`, `analyze_bag`) to the CLI and the six DDS tools to the DDS backend; `peek_bag_samples` reads bags without the CLI.
+`TOPICFORGE_DDS_BACKEND` accepts `mock` (default), `cyclone`, `fast` and `auto` (`fast`, then `cyclone`, then `mock`, whichever binding imports). The default `mock` selects no DDS backend: installing the Cyclone binding is not enough, you must also set `TOPICFORGE_DDS_BACKEND=cyclone`. With `TOPICFORGE_MODE=live` and no backend selected, the DDS tools raise `DDS module is not active: ...` with the actual cause (backend not selected, binding not installed, or binding installed but the adapter failed to start), and `health_check` reports `dds_backend: "none"` plus `dds_inactive_note`. An explicit value is honoured with or without `ros2` on PATH, in any mode except `mock`. If the binding is missing or the participant cannot start, the server logs a warning naming the cause and falls back to the ROS2 CLI alone, or to the mock fixtures. When both `ros2` and a DDS backend are up, a composite adapter routes the seven `ros2` CLI tools (`list_topics`, `get_topic_info`, `list_nodes`, `get_node_info`, `inspect_tf`, `sample_messages`, `analyze_bag`) to the CLI and the six DDS tools to the DDS backend; `peek_bag_samples` reads bags without the CLI.
 
 A Fast DDS adapter exists but has never run against a bus, and its `fastdds` Python binding is not on PyPI: build it from eProsima's sources and install it next to TopicForge. There is no `[dds-fast]` extra. Any other value (`rti`, `opensplice`, `coredx`, `intercom`, `opendds`, `dust`) is rejected at startup with an error that lists the valid ones; Cyclone already sees those vendors' participants through standard discovery. Full backend selection, the routing table and the QoS mismatch scenario are in [`docs/DDS_QUICKSTART.md`](docs/DDS_QUICKSTART.md); error messages are in [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md).
 
@@ -141,10 +142,10 @@ When on, each tool call emits one event with exactly six fields:
 
 | Field        | Example         | Notes                                                       |
 | ------------ | --------------- | ----------------------------------------------------------- |
-| `tool_name`  | `"list_topics"` | One of the fourteen tools, never argument values            |
+| `tool_name`  | `"list_topics"` | One of the fifteen tools, never argument values            |
 | `latency_ms` | `12.34`         | Handler wall-clock duration, 2 decimals                     |
 | `mode`       | `"mock"`        | Mode of the adapter actually serving: `mock` or `live`      |
-| `version`    | `"0.7.1"`       | TopicForge server version                                   |
+| `version`    | `"0.7.2"`       | TopicForge server version                                   |
 | `session_id` | `"a1b2c3..."`   | Random UUID per process, never persisted                    |
 | `success`    | `true`          | Whether the handler returned or raised                      |
 

{topicforge-0.7.1 → topicforge-0.7.2}/docs/CLIENTS.md

@@ -6,7 +6,7 @@ TopicForge (ROS 2 / DDS) is a local, read-only MCP server that speaks stdio.
 Every client below launches it as a child process with the same command:
 
 ```
-uvx --from "topicforge==0.7.1" topicforge
+uvx --from "topicforge==0.7.2" topicforge
 ```
 
 and the same three environment variables:
@@ -21,7 +21,7 @@ The registry name is `io.github.yaniswav/topicforge`. Where a client asks for a
 display name, use **TopicForge (ROS 2 / DDS)**: an unrelated SEO product is also
 called TopicForge in the MCP registries.
 
-The version pin (`==0.7.1`) is moved on every release together with the other
+The version pin (`==0.7.2`) is moved on every release together with the other
 version strings; a test keeps them in sync.
 
 ## Before you start
@@ -44,7 +44,7 @@ version strings; a test keeps them in sync.
   `"--from"` in the args. To build the binding yourself, install the Cyclone C library and
   run `pip install "topicforge[dds]"`. The `[dds]` and `[dds-cyclone]` extras still work
   as aliases, so older commands keep installing.
-- **pip alternative.** `pip install "topicforge==0.7.1"`, then use
+- **pip alternative.** `pip install "topicforge==0.7.2"`, then use
   `"command": "topicforge"` (or `"command": "python", "args": ["-m", "topicforge"]`)
   with no `args` for uvx. Use the absolute path of the binary if the client does
   not see your venv.
@@ -72,7 +72,7 @@ say where the file lives and what differs.
   "mcpServers": {
     "topicforge": {
       "command": "uvx",
-      "args": ["--from", "topicforge==0.7.1", "topicforge"],
+      "args": ["--from", "topicforge==0.7.2", "topicforge"],
       "env": {
         "TOPICFORGE_MODE": "auto",
         "TOPICFORGE_DDS_BACKEND": "cyclone",
@@ -95,7 +95,7 @@ claude plugin install topicforge@topicforge
 Or just the server:
 
 ```
-claude mcp add topicforge --env TOPICFORGE_MODE=auto --env TOPICFORGE_DDS_BACKEND=cyclone --env TOPICFORGE_DDS_DOMAIN_ID=0 -- uvx --from "topicforge==0.7.1" topicforge
+claude mcp add topicforge --env TOPICFORGE_MODE=auto --env TOPICFORGE_DDS_BACKEND=cyclone --env TOPICFORGE_DDS_DOMAIN_ID=0 -- uvx --from "topicforge==0.7.2" topicforge
 ```
 
 ## Claude Desktop
@@ -112,9 +112,9 @@ the common JSON shape above and restart the app completely. On Windows, if
 
 The one-click links in this page and in the README are https redirects, because GitHub and PyPI strip `cursor://` and `vscode:` links. Only the raw schemes are documented by Cursor and VS Code; the https forms (`cursor.com/install-mcp`, `vscode.dev/redirect/mcp/install`) were observed to redirect correctly on 2026-10-06 but are not in the vendors' docs (unverified, last checked 2026-10-06). The raw links are given as a fallback.
 
-One click: [Add TopicForge to Cursor](https://cursor.com/install-mcp?name=topicforge&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJ0b3BpY2ZvcmdlPT0wLjcuMSIsInRvcGljZm9yZ2UiXSwiZW52Ijp7IlRPUElDRk9SR0VfTU9ERSI6ImF1dG8iLCJUT1BJQ0ZPUkdFX0REU19CQUNLRU5EIjoiY3ljbG9uZSIsIlRPUElDRk9SR0VfRERTX0RPTUFJTl9JRCI6IjAifX0%3D)
+One click: [Add TopicForge to Cursor](https://cursor.com/install-mcp?name=topicforge&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJ0b3BpY2ZvcmdlPT0wLjcuMiIsInRvcGljZm9yZ2UiXSwiZW52Ijp7IlRPUElDRk9SR0VfTU9ERSI6ImF1dG8iLCJUT1BJQ0ZPUkdFX0REU19CQUNLRU5EIjoiY3ljbG9uZSIsIlRPUElDRk9SR0VfRERTX0RPTUFJTl9JRCI6IjAifX0%3D)
 
-If that page does not open Cursor, use the raw deeplink: `cursor://anysphere.cursor-deeplink/mcp/install?name=topicforge&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJ0b3BpY2ZvcmdlPT0wLjcuMSIsInRvcGljZm9yZ2UiXSwiZW52Ijp7IlRPUElDRk9SR0VfTU9ERSI6ImF1dG8iLCJUT1BJQ0ZPUkdFX0REU19CQUNLRU5EIjoiY3ljbG9uZSIsIlRPUElDRk9SR0VfRERTX0RPTUFJTl9JRCI6IjAifX0=`
+If that page does not open Cursor, use the raw deeplink: `cursor://anysphere.cursor-deeplink/mcp/install?name=topicforge&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJ0b3BpY2ZvcmdlPT0wLjcuMiIsInRvcGljZm9yZ2UiXSwiZW52Ijp7IlRPUElDRk9SR0VfTU9ERSI6ImF1dG8iLCJUT1BJQ0ZPUkdFX0REU19CQUNLRU5EIjoiY3ljbG9uZSIsIlRPUElDRk9SR0VfRERTX0RPTUFJTl9JRCI6IjAifX0%3D`
 
 Or paste the common JSON shape into `~/.cursor/mcp.json` (all projects) or
 `.cursor/mcp.json` (one project).
@@ -125,9 +125,9 @@ The `plugin/` folder of this repository is also an [Agent Plugins](https://agent
 
 ## VS Code / GitHub Copilot
 
-One click: [Install in VS Code](https://vscode.dev/redirect/mcp/install?name=topicforge&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22--from%22%2C%22topicforge%3D%3D0.7.1%22%2C%22topicforge%22%5D%2C%22env%22%3A%7B%22TOPICFORGE_MODE%22%3A%22auto%22%2C%22TOPICFORGE_DDS_BACKEND%22%3A%22cyclone%22%2C%22TOPICFORGE_DDS_DOMAIN_ID%22%3A%220%22%7D%7D)
+One click: [Install in VS Code](https://vscode.dev/redirect/mcp/install?name=topicforge&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22--from%22%2C%22topicforge%3D%3D0.7.2%22%2C%22topicforge%22%5D%2C%22env%22%3A%7B%22TOPICFORGE_MODE%22%3A%22auto%22%2C%22TOPICFORGE_DDS_BACKEND%22%3A%22cyclone%22%2C%22TOPICFORGE_DDS_DOMAIN_ID%22%3A%220%22%7D%7D)
 
-Fallback, the raw URL handler: `vscode:mcp/install?%7B%22name%22%3A%22topicforge%22%2C%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22--from%22%2C%22topicforge%3D%3D0.7.1%22%2C%22topicforge%22%5D%2C%22env%22%3A%7B%22TOPICFORGE_MODE%22%3A%22auto%22%2C%22TOPICFORGE_DDS_BACKEND%22%3A%22cyclone%22%2C%22TOPICFORGE_DDS_DOMAIN_ID%22%3A%220%22%7D%7D`
+Fallback, the raw URL handler: `vscode:mcp/install?%7B%22name%22%3A%22topicforge%22%2C%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22--from%22%2C%22topicforge%3D%3D0.7.2%22%2C%22topicforge%22%5D%2C%22env%22%3A%7B%22TOPICFORGE_MODE%22%3A%22auto%22%2C%22TOPICFORGE_DDS_BACKEND%22%3A%22cyclone%22%2C%22TOPICFORGE_DDS_DOMAIN_ID%22%3A%220%22%7D%7D`
 
 Or put this in `.vscode/mcp.json` (the key is `servers`, not `mcpServers`), or run
 "MCP: Add Server" from the Command Palette:
@@ -138,7 +138,7 @@ Or put this in `.vscode/mcp.json` (the key is `servers`, not `mcpServers`), or r
     "topicforge": {
       "type": "stdio",
       "command": "uvx",
-      "args": ["--from", "topicforge==0.7.1", "topicforge"],
+      "args": ["--from", "topicforge==0.7.2", "topicforge"],
       "env": {
         "TOPICFORGE_MODE": "auto",
         "TOPICFORGE_DDS_BACKEND": "cyclone",
@@ -167,7 +167,7 @@ Servers", and paste the common JSON shape (the file is
 Project file `.roo/mcp.json` (takes precedence) or the global `mcp_settings.json`
 opened from the MCP view. Paste the common JSON shape. Roo's docs say Windows
 needs a `cmd /c` wrapper for `npx`; for `uvx`, try it directly first and fall back
-to `"command": "cmd", "args": ["/c", "uvx", "--from", "topicforge==0.7.1",
+to `"command": "cmd", "args": ["/c", "uvx", "--from", "topicforge==0.7.2",
 "topicforge"]` if it fails to start.
 
 ## Continue
@@ -184,7 +184,7 @@ mcpServers:
     command: uvx
     args:
       - "--from"
-      - "topicforge==0.7.1"
+      - "topicforge==0.7.2"
       - "topicforge"
     env:
       TOPICFORGE_MODE: auto
@@ -201,7 +201,7 @@ In `settings.json`, under `context_servers`:
   "context_servers": {
     "topicforge": {
       "command": "uvx",
-      "args": ["--from", "topicforge==0.7.1", "topicforge"],
+      "args": ["--from", "topicforge==0.7.2", "topicforge"],
       "env": {
         "TOPICFORGE_MODE": "auto",
         "TOPICFORGE_DDS_BACKEND": "cyclone",
@@ -227,7 +227,7 @@ run with the dds extra can exceed, so set it to 60 s:
 ```toml
 [mcp_servers.topicforge]
 command = "uvx"
-args = ["--from", "topicforge==0.7.1", "topicforge"]
+args = ["--from", "topicforge==0.7.2", "topicforge"]
 startup_timeout_sec = 60
 
 [mcp_servers.topicforge.env]
@@ -258,7 +258,7 @@ extensions:
     name: TopicForge (ROS 2 / DDS)
     type: stdio
     cmd: uvx
-    args: [--from, "topicforge==0.7.1", topicforge]
+    args: [--from, "topicforge==0.7.2", topicforge]
     enabled: true
     envs: { "TOPICFORGE_MODE": "auto", "TOPICFORGE_DDS_BACKEND": "cyclone", "TOPICFORGE_DDS_DOMAIN_ID": "0" }
     timeout: 300
@@ -269,7 +269,7 @@ extensions:
 Program tab > Install > Edit `mcp.json` (same notation as Cursor), then paste the
 common JSON shape. LM Studio's docs only show remote examples; local command
 servers follow the Cursor notation but are not documented explicitly. Small
-local models may struggle with fourteen tools.
+local models may struggle with fifteen tools.
 
 ## Amazon Q Developer / Kiro
 
@@ -325,7 +325,7 @@ when the question matches.
 
 ## Troubleshooting
 
-- Run the command by hand first: `uvx --from "topicforge==0.7.1" topicforge --version`.
+- Run the command by hand first: `uvx --from "topicforge==0.7.2" topicforge --version`.
 - Server starts but sees no DDS participants: check the domain id, and that the
   client machine is on the same network as the robot (DDS discovery uses
   multicast UDP). Ask the assistant to call `health_check`.

{topicforge-0.7.1 → topicforge-0.7.2}/docs/CONTRACT.md

@@ -171,7 +171,7 @@ The 45 s are wall time from the request to the response, lock wait included. The
 enforces it (`topicforge.tools.guard`, with `topicforge.budget` passing the deadline down):
 
 - Calls run in two lanes with one lock each: ROS (`list_topics`, `get_topic_info`,
-  `list_nodes`, `get_node_info`, `sample_messages`, `analyze_bag`) and DDS (`list_participants`, `detect_qos_mismatches`, `peek_dds_samples`,
+  `list_nodes`, `get_node_info`, `inspect_tf`, `sample_messages`, `analyze_bag`) and DDS (`list_participants`, `detect_qos_mismatches`, `peek_dds_samples`,
   `participant_events`, `topic_metrics`, `list_endpoints`).
   `health_check` never takes a lock and never runs the `ros2` CLI; `peek_bag_samples` reads
   a file in pure Python and takes none either.
@@ -324,6 +324,17 @@ rather than absent). There is no `participant_name` value: since Foxy the partic
 carries the name of the enclave, not of a node. The field exists because Fast DDS
 participants all announce the name `/`.
 
+Filled since 0.7.2 on the Cyclone backend (`node_names_source` `ros_discovery_info`) and
+by the mock. A fourth reader on `ros_discovery_info` (type
+`rmw_dds_common::msg::dds_::ParticipantEntitiesInfo_`, RELIABLE, TRANSIENT_LOCAL, KEEP_ALL)
+feeds a cache keyed by the 12-byte GUID prefix; `adapters/common/ros_discovery.py` decodes
+the XCDR1 payload by hand and accepts the gid width (24 or 16) that consumes the buffer
+exactly. The decoder was checked on captures from real rmw_fastrtps nodes (Humble: 24,
+Jazzy: 16, both in WSL), and the Docker ROS 2 bench names every node on Humble and Jazzy
+with both rmw_fastrtps and rmw_cyclonedds; Connext writers are untested. A
+participant that has left keeps the last non-empty list it announced. Fast DDS and RTI
+backends leave it `none`.
+
 Risk: `ros_discovery_info` is a user topic whose `Gid.data` is 24 bytes on Humble
 and 16 bytes from Iron. Fallback: `ros2_cli`, through the GID prefixes printed by
 `ros2 topic info -v /parameter_events` and `/rosout`.
@@ -658,7 +669,9 @@ shows only added properties.
 ### 9.1 Listing size
 
 `tools/list` carries the description, input schema and output schema of every tool, and some
-clients truncate it. In 0.7.0 it was about 178 KB compact (14 tools); 0.7.1 serves about 113 KB.
+clients truncate it. In 0.7.0 it was about 178 KB compact (14 tools); 0.7.2 serves about 119 KB
+(measured 118,884 bytes against the 120,000 test ceiling), so the next tool needs the schema
+compaction planned for 0.7.3 first.
 How:
 
 - Pydantic's generated `title` is dropped from every property and nested model, and the
@@ -671,6 +684,20 @@ How:
 
 Rule for new fields: one sentence, no history, no restating the name.
 
+### 9.1b `is_topicforge_cli` and `restarts_by_node` (0.7.2)
+
+Both additive. `ParticipantInfo.is_topicforge_cli` (default `false`) marks the `ros2` CLI
+process that a TopicForge call (`list_nodes`, `get_node_info`, `sample_messages`, ...)
+spawned: it joins the domain as a participant and stays 0.3-2 s after exiting, so a bus
+of 7 looked like 8. A participant is flagged, never removed, when one of these matches a
+pid TopicForge started in the last 30 s: its `/_ros2cli_<pid>` node name; the pid in a
+Fast DDS GUID prefix (bytes 4-5, low 16 bits); a Cyclone `__Pid` property. The listing
+`note` says so, and counts participants that merely appeared within 5 s of a CLI call.
+Only the composite (ROS CLI plus DDS) adapter flags; the pid check is unavailable where the
+launcher is not the process that joins DDS (Windows `ros2.exe`), the note still applies.
+`ParticipantListing.restarts_by_node` is `restarts_by_name` keyed by node full name, over
+the participants that announced node names, the CLI ghosts left out.
+
 ### 9.2 `restarts_by_name`
 
 A restarted ROS 2 node is a new DDS participant with a new GUID and the same name, so
@@ -774,3 +801,29 @@ value; compare against `health_check.now_ns` when needed.
   a reader `deadline_ns` tighter than the writer's is incompatible.
 - `HealthReport.ros2_distro` discloses `ROS_DISTRO` by design under the local-trust threat model
   (README "Security model"); a hosted multi-tenant endpoint would scrub it.
+
+### 9.8 `inspect_tf` (tool 15)
+
+Tool 15, additive, ROS lane, open-world, `ros2` CLI only (a DDS-only setup raises the usual
+error). It returns `TfReport`. Inputs: `window_s` (1..20, default 5), `stale_after_s` (default
+2), `source_frame` and `target_frame` (both or neither).
+
+- The tree comes from the transforms: `/tf_static` is read once (transient_local, one latched
+  message per publisher; it stops as soon as they are in, and waits at most the longer of
+  `window_s` and 6 s), concurrently with `/tf`, which is streamed uncut for `window_s`, at most
+  3000 messages. A topic that is absent or has no publisher is a `note`; when both streams fail for any
+  other reason the call raises an error instead of returning an empty tree.
+- Time is the header stamp. `age_s` is the distance between a frame's newest stamp and the
+  newest `/tf` stamp (`reference_ns`), so it is correct on sim time. `stale` is `age_s` above
+  `stale_after_s`; static frames have no age. `observed_frequency_hz` uses the arrival time,
+  `sim_frequency_hz` the stamps, `real_time_factor` is their ratio (about 1 on a real robot).
+- `findings.kind` is an open set (1.9): `stale`, `two_parents`, `disconnected` (more than one
+  root), `static_and_dynamic` (a frame on both topics), `cycle`, `no_path` (unknown or
+  unconnected frames). A sound tree has none.
+- Ages are measured against the newest `/tf` stamp, so one publisher with a future stamp or a
+  zero stamp skews the staleness of every other frame: a frame can read as stale because
+  another one runs ahead. Check `stamp_span_s` and the stamps when many frames go stale at once.
+- `echo` can drop messages at high rates: the structure and the findings hold, the exact
+  message counts and frequencies are approximate (`truncated` says when messages were lost).
+- The mock `/tf_static` topic carries the fixed frames of the demo robot; mock `inspect_tf`
+  is a fixed 5 s capture and ignores `window_s`.

{topicforge-0.7.1 → topicforge-0.7.2}/docs/DDS_QUICKSTART.md

@@ -76,7 +76,7 @@ Order of checks per reader/writer pair: Partition first (wildcards `*` and `?` o
 
 ## 4. Composite adapter and backend selection
 
-When `ros2` is on PATH and a DDS backend starts, TopicForge builds both a `Ros2CliAdapter` and the DDS adapter behind a `CompositeAdapter`: the six `ros2` CLI tools (`list_topics`, `get_topic_info`, `list_nodes`, `get_node_info`, `sample_messages`, `analyze_bag`) go to the CLI and the six DDS tools to the DDS backend; `peek_bag_samples` reads bags without the CLI. An explicit DDS backend (`cyclone`, `fast`, `auto`) is honoured in every mode except `mock`, including on a host without `ros2`.
+When `ros2` is on PATH and a DDS backend starts, TopicForge builds both a `Ros2CliAdapter` and the DDS adapter behind a `CompositeAdapter`: the seven `ros2` CLI tools (`list_topics`, `get_topic_info`, `list_nodes`, `get_node_info`, `inspect_tf`, `sample_messages`, `analyze_bag`) go to the CLI and the six DDS tools to the DDS backend; `peek_bag_samples` reads bags without the CLI. An explicit DDS backend (`cyclone`, `fast`, `auto`) is honoured in every mode except `mock`, including on a host without `ros2`.
 
 | `TOPICFORGE_MODE` | `TOPICFORGE_DDS_BACKEND` | `ros2` on PATH | Active adapter | ROS2 graph and bag tools | DDS tools |
 | --- | --- | --- | --- | --- | --- |

{topicforge-0.7.1 → topicforge-0.7.2}/docs/TESTING.md

@@ -4,7 +4,7 @@ How to get a working ROS2 environment to point TopicForge at, and how to wire it
 
 | You want to... | Time | Path |
 | --- | --- | --- |
-| Try the fourteen tools without installing ROS2 | 5 min | [Mock mode](#mock-mode) |
+| Try the fifteen tools without installing ROS2 | 5 min | [Mock mode](#mock-mode) |
 | Live mode on Windows | 45 min | [WSL2 + Humble](#wsl2--ros2-humble-windows-recommended) |
 | Live mode on Ubuntu | 20 min | [Linux native](#linux-native) |
 | Throwaway environment | 15 min | [Docker](#docker) |
@@ -15,7 +15,7 @@ How to get a working ROS2 environment to point TopicForge at, and how to wire it
 ```bash
 python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\Activate.ps1
 pip install topicforge
-python -m topicforge --version                      # -> topicforge 0.7.1
+python -m topicforge --version                      # -> topicforge 0.7.2
 TOPICFORGE_MODE=mock python -m topicforge           # blocks on stdio; MCP clients spawn it
 ```
 
@@ -41,7 +41,7 @@ python3 -m venv ~/topicforge-venv && source ~/topicforge-venv/bin/activate
 pip install topicforge          # Ubuntu 22.04 ships Python 3.10, which is enough
 ```
 
-Then run live mode with three terminals. In the first, `ros2 run demo_nodes_cpp talker` publishes `/chatter` at about 1 Hz. In the second, `ros2 topic list` should show `/chatter`. In the third, source ROS2, activate the venv and run `TOPICFORGE_MODE=live python -m topicforge`. The startup line reads `topicforge 0.7.1 ready (mode=live, requested_mode=live, adapter=ros2_cli, telemetry=off)`; `mode=mock` means `ros2` was not found and the server fell back to fixtures.
+Then run live mode with three terminals. In the first, `ros2 run demo_nodes_cpp talker` publishes `/chatter` at about 1 Hz. In the second, `ros2 topic list` should show `/chatter`. In the third, source ROS2, activate the venv and run `TOPICFORGE_MODE=live python -m topicforge`. The startup line reads `topicforge 0.7.2 ready (mode=live, requested_mode=live, adapter=ros2_cli, telemetry=off)`; `mode=mock` means `ros2` was not found and the server fell back to fixtures.
 
 ## Linux native
 
@@ -75,7 +75,7 @@ TopicForge resolves the `ros2` launcher with `shutil.which` (normally `ros2.exe`
 
 ## Test scenarios
 
-Discover the graph. Ask "What topics are currently being published, and what message types do they carry?" TopicForge calls `list_topics`. Live mode shows `/chatter` plus `/rosout` and `/parameter_events`; mock mode shows `/cmd_vel`, `/odom`, `/scan`, `/tf` and `/camera/image_raw`.
+Discover the graph. Ask "What topics are currently being published, and what message types do they carry?" TopicForge calls `list_topics`. Live mode shows `/chatter` plus `/rosout` and `/parameter_events`; mock mode shows `/cmd_vel`, `/odom`, `/scan`, `/tf`, `/tf_static` and `/camera/image_raw`.
 
 Inspect and sample. Ask "Show me the latest message on /chatter." TopicForge calls `get_topic_info` then `sample_messages`. The payload has the message fields as nested named values. `timestamp_ns` is the `header.stamp` and the body time of `/clock`, `/tf` and `/rosout`, and `0` for other headerless types such as `std_msgs/String` (`stamp_source` says which).
 
@@ -102,4 +102,4 @@ TopicForge speaks MCP over stdio; any compliant client can spawn it with a comma
 }
 ```
 
-That is the Claude Desktop shape (`claude_desktop_config.json`); restart the app and the fourteen tools appear under the hammer icon. For Claude Code run `claude mcp add topicforge -- topicforge`. Cursor, Continue and Cline accept the same stdio config; ready-to-paste configs for every major client are in [`CLIENTS.md`](CLIENTS.md). If the `topicforge` script is not on PATH, use `"command": "python", "args": ["-m", "topicforge"]`, or the absolute path of the binary inside your venv: desktop clients do not inherit your shell's PATH or venv activation.
+That is the Claude Desktop shape (`claude_desktop_config.json`); restart the app and the fifteen tools appear under the hammer icon. For Claude Code run `claude mcp add topicforge -- topicforge`. Cursor, Continue and Cline accept the same stdio config; ready-to-paste configs for every major client are in [`CLIENTS.md`](CLIENTS.md). If the `topicforge` script is not on PATH, use `"command": "python", "args": ["-m", "topicforge"]`, or the absolute path of the binary inside your venv: desktop clients do not inherit your shell's PATH or venv activation.

{topicforge-0.7.1 → topicforge-0.7.2}/docs/TOOLS.md

@@ -5,7 +5,7 @@ served in mock mode. Do not edit by hand: `tests/test_contract_snapshots.py`
 fails when this file is out of date. The rules behind the shapes are in
 [CONTRACT.md](CONTRACT.md).
 
-14 tools, all read-only.
+15 tools, all read-only.
 
 | Tool | Title | World |
 | --- | --- | --- |
@@ -14,6 +14,7 @@ fails when this file is out of date. The rules behind the shapes are in
 | [`get_node_info`](#get_node_info) | Get node info | open |
 | [`get_topic_info`](#get_topic_info) | Get topic info | open |
 | [`health_check`](#health_check) | Health check | closed |
+| [`inspect_tf`](#inspect_tf) | Inspect TF tree | open |
 | [`list_endpoints`](#list_endpoints) | List DDS endpoints | open |
 | [`list_nodes`](#list_nodes) | List ROS 2 nodes | open |
 | [`list_participants`](#list_participants) | List DDS participants | open |
@@ -196,6 +197,48 @@ None.
 | `ros_backend` | `"mock" \| "ros2_cli" \| "none"` | no | ROS 2 backend: `ros2_cli`, `mock` or `none`. |
 | `note` | `str \| null` | no | One sentence of context, or `None`. |
 
+## `inspect_tf`
+
+**Inspect TF tree**
+
+Annotations: `destructiveHint=false`, `idempotentHint=true`, `openWorldHint=true`, `readOnlyHint=true`
+
+ROS 2 graph only. Rebuild the TF tree from the transforms on `/tf_static` (latched) and `/tf` (listened to for `window_s`) and flag what breaks lookups. Returns a `TfReport`: `frames` (parent, `kind` static/dynamic/both, `age_s`, `stale`, `observed_frequency_hz` on wall time, `sim_frequency_hz` on stamps), `roots`, counts and `findings` `{kind, frames, text}`: `stale` (a frame trails the newest `/tf` stamp by more than `stale_after_s`), `two_parents`, `disconnected` (several roots), `static_and_dynamic`, `cycle`, `no_path`. Ages and rates use header stamps, so they hold on sim time (`real_time_factor` far from 1 means sim). Give `source_frame` and `target_frame` for the `path` between them. **Empty `frames`** when nothing is published (read `note`). The listening is capped (3000 messages): `echo` can drop messages at high rates, so the tree is exact but frequencies are approximate (`truncated`). **Raises an MCP error** without a `ros2` CLI. **Mock mode**: a fixed 5 s capture of the demo robot with one stale frame. **Duration**: runs the `ros2` CLI behind the ROS lock (one call at a time); the whole call, lock wait included, ends within 45 s, and if another `ros2` call holds the lock it fails at once with a `busy` error (retry).
+
+### Input parameters
+
+| Name | Type | Required | Default | Constraints | Description |
+| --- | --- | --- | --- | --- | --- |
+| `window_s` | `float` | no | `5.0` | >= 1.0, <= 20.0 | Seconds to listen to `/tf`, 1..20, default 5. |
+| `stale_after_s` | `float` | no | `2.0` | >= 0.1, <= 3600.0 | A frame is stale past this many seconds of stamp time, default 2. |
+| `source_frame` | `str \| null` | no | `null` | - | Frame name, e.g. `base_link`. Give `source_frame` and `target_frame` together to get the chain between them in `path`. |
+| `target_frame` | `str \| null` | no | `null` | - | See `source_frame`. |
+
+### Output (top-level fields)
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `frames` | `list[TfFrame]` | yes | Sorted by name. |
+| `roots` | `list[str]` | yes | Frames with no parent; one in a sound tree. |
+| `frame_count` | `int` | yes | - |
+| `static_count` | `int` | yes | Frames with a static transform. |
+| `dynamic_count` | `int` | yes | Frames with a dynamic transform. |
+| `stale_count` | `int` | yes | - |
+| `transform_count` | `int` | yes | Distinct parent-child pairs. |
+| `message_count` | `int` | yes | Transforms captured, repeats included. |
+| `findings` | `list[TfFinding]` | yes | Empty when the tree is sound. |
+| `hints` | `list[str]` | yes | - |
+| `path` | `list[str] \| null` | no | Frames from `source_frame` to `target_frame`. |
+| `path_note` | `str \| null` | no | Why `path` is `None`, or context. |
+| `reference_ns` | `int \| null` | yes | Newest `/tf` stamp: the clock for `age_s`. |
+| `window_s` | `float` | yes | - |
+| `window_actual_s` | `float` | yes | - |
+| `stamp_span_s` | `float \| null` | yes | - |
+| `real_time_factor` | `float \| null` | yes | Stamp time over wall time: about 1 on a real robot, other on sim. |
+| `truncated` | `bool` | yes | Messages were dropped or the cap was hit. |
+| `mode_effective` | `"mock" \| "live"` | yes | `live` or `mock` (fixtures). |
+| `note` | `str \| null` | no | One sentence of context, or `None`. |
+
 ## `list_endpoints`
 
 **List DDS endpoints**
@@ -287,6 +330,7 @@ List DDS participants observed on the bus as a `ParticipantListing`: `guid`, `ve
 | `note` | `str \| null` | no | One sentence of context, or `None`. |
 | `restarts_by_name` | `dict[str, NameLifecycle]` | no | Names seen with several GUIDs or lost at least once (absent: ran once and stayed). A restart is a new GUID with the same name. |
 | `restarts_note` | `str \| null` | no | Set when unnamed participants were left out of `restarts_by_name`. |
+| `restarts_by_node` | `dict[str, NameLifecycle]` | no | `restarts_by_name` keyed by ROS 2 node full name. |
 
 ## `list_topics`
 

{topicforge-0.7.1 → topicforge-0.7.2}/docs/TROUBLESHOOTING.md

@@ -31,7 +31,7 @@ You called a ROS2 graph or bag tool (`list_topics`, `get_topic_info`, `sample_me
 2. Re-run with `TOPICFORGE_MODE=live` and your existing `TOPICFORGE_DDS_BACKEND`.
 3. Check `health_check`: `ros_backend` should be `"ros2_cli"` and `dds_backend` your vendor.
 
-If you want a DDS-only deployment, the message is expected: you use the six DDS tools and `peek_bag_samples` (it reads bags without the CLI), and the six ros2-CLI tools (`list_topics`, `get_topic_info`, `list_nodes`, `get_node_info`, `sample_messages`, `analyze_bag`) raise it. For offline work use `TOPICFORGE_MODE=mock`. The opposite error, "DDS module is not active: ...", ends with the cause: the backend was not selected (`TOPICFORGE_DDS_BACKEND` is `mock`, the default, which means no DDS backend; set it to `cyclone` even when the binding is installed), the binding is not installed, or it is installed but the adapter failed to start (the server log has the error). `health_check` shows the same text as `dds_inactive_note`.
+If you want a DDS-only deployment, the message is expected: you use the six DDS tools and `peek_bag_samples` (it reads bags without the CLI), and the seven ros2-CLI tools (`list_topics`, `get_topic_info`, `list_nodes`, `get_node_info`, `inspect_tf`, `sample_messages`, `analyze_bag`) raise it. For offline work use `TOPICFORGE_MODE=mock`. The opposite error, "DDS module is not active: ...", ends with the cause: the backend was not selected (`TOPICFORGE_DDS_BACKEND` is `mock`, the default, which means no DDS backend; set it to `cyclone` even when the binding is installed), the binding is not installed, or it is installed but the adapter failed to start (the server log has the error). `health_check` shows the same text as `dds_inactive_note`.
 
 ## "rosbags"
 

{topicforge-0.7.1 → topicforge-0.7.2}/docs/TUTORIEL.md

@@ -31,7 +31,7 @@ Add it to your MCP client. For Claude Desktop, edit `claude_desktop_config.json`
 }
 ```
 
-Restart Claude Desktop. All fourteen tools appear under the hammer icon. Ask something like:
+Restart Claude Desktop. All fifteen tools appear under the hammer icon. Ask something like:
 
 > What topics are being published right now, and what message types do they carry?
 

{topicforge-0.7.1 → topicforge-0.7.2}/examples/README.md

@@ -17,6 +17,6 @@ TOPICFORGE_MODE=mock python -m topicforge
 # Windows PowerShell: $env:TOPICFORGE_MODE="mock"; python -m topicforge
 ```
 
-Point any MCP client at the server with `"env": { "TOPICFORGE_MODE": "mock" }`. The mock exposes all 14 tools against deterministic fixtures, so every example is reproducible byte for byte.
+Point any MCP client at the server with `"env": { "TOPICFORGE_MODE": "mock" }`. The mock exposes all 15 tools against deterministic fixtures, so every example is reproducible byte for byte.
 
 To run against a real bus, use `TOPICFORGE_MODE=live` and, for the DDS tools, `TOPICFORGE_DDS_BACKEND=cyclone` (see [`docs/DDS_QUICKSTART.md`](../docs/DDS_QUICKSTART.md)). The mock shows the shape of every response, not the behaviour of the live DDS adapters, which differ in two ways that examples 02 and 04 call out: user-topic payloads are not decoded, and `topic_metrics` only has data for the builtin discovery topics.

{topicforge-0.7.1 → topicforge-0.7.2}/plugin/README.md

@@ -4,7 +4,7 @@ TopicForge is a read-only MCP server for ROS 2 and DDS. This plugin bundles the
 
 ## What is included
 
-- MCP server `topicforge`, started with `uvx` from the `topicforge` package on PyPI (version pinned to 0.7.1). It exposes fourteen read-only tools: `health_check`, `list_topics`, `get_topic_info`, `list_nodes`, `get_node_info`, `sample_messages`, `analyze_bag`, `peek_bag_samples`, `list_participants`, `list_endpoints`, `detect_qos_mismatches`, `participant_events`, `peek_dds_samples`, `topic_metrics`.
+- MCP server `topicforge`, started with `uvx` from the `topicforge` package on PyPI (version pinned to 0.7.2). It exposes fifteen read-only tools: `health_check`, `list_topics`, `get_topic_info`, `list_nodes`, `get_node_info`, `sample_messages`, `analyze_bag`, `peek_bag_samples`, `list_participants`, `list_endpoints`, `detect_qos_mismatches`, `participant_events`, `peek_dds_samples`, `topic_metrics`, `inspect_tf`.
 - Skill `diagnose-dds-bus`: what to call, and in which order, when nodes do not talk, a topic gets no data, or a node crashed or restarts.
 - Skill `inspect-ros2-robot`: listing topics, sampling messages and reading bags, including large arrays and simulation time.
 - The server itself also offers both procedures as MCP prompts (`diagnose-dds-bus`, `inspect-ros2-robot`) and short server instructions, for clients that load MCP prompts instead of skills. The skills use output contract 2 (`health_check.contract_version` is 2, 0.7.0 and later).

{topicforge-0.7.1 → topicforge-0.7.2}/plugin/pyproject.toml

@@ -4,12 +4,12 @@
 # After a release reaches PyPI, regenerate the lock: `cd plugin && uv lock`.
 [project]
 name = "topicforge-claude-plugin"
-version = "0.7.1"
+version = "0.7.2"
 description = "Locked launch manifest for the TopicForge Claude plugin."
 # cyclonedds ships wheels for CPython 3.10 to 3.13 only (checked on PyPI 2026-10-07).
 requires-python = ">=3.10,<3.14"
 dependencies = [
-    "topicforge==0.7.1",
+    "topicforge==0.7.2",
 ]
 
 [tool.uv]