topicforge 0.6.4__tar.gz → 0.7.1__tar.gz

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

@@ -7,6 +7,279 @@ and this project adheres to [Semantic Versioning 2.0.0](https://semver.org/spec/
 
 ## [Unreleased]
 
+## [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
+input was renamed, removed or retyped (`docs/CONTRACT.md` section 9).
+
+### Added
+
+- `detect_qos_mismatches` fills `suggested_fixes` (output contract 2, additive; see
+  `docs/CONTRACT.md` section 3.1): "diagnose, propose the exact fix, verify". Each QoS
+  mismatch report and each `partition` split gets up to one fix per side that can change
+  (`MismatchReport.suggested_fixes`, and the new `NotMatchedPair.suggested_fixes`), with its
+  tradeoff and a `verify_with` call. A ROS 2 topic with a Reliability or Durability finding
+  gets a `qos_override` parameter-file entry; every other case gets a `dds_profile` (Fast DDS
+  XML plus the cyclonedds-python equivalent, since Cyclone DDS has no XML QoS profile).
+  Covered: Reliability, Durability, Deadline, Liveliness, Ownership, LatencyBudget and
+  Partition; other findings get a hint instead. Identical findings on a topic share the
+  first report's fixes. Text only: TopicForge never applies a fix, and a test fails any
+  suggestion containing a stop, remove or write verb.
+- `list_participants` and `participant_events`: `restarts_by_name` (`{name: {lives,
+  departures}}` for names seen with several GUIDs or lost) and `restarts_note`, so an agent
+  no longer counts GUIDs to find a restart loop.
+- `participant_events`: `age_s` on each event, seconds between the event and the response
+  (`null` in mock mode).
+- `detect_qos_mismatches`: `summary`, a one-line reading of the scan that says when pairs are
+  not matched and no data flows, even with an empty `reports`.
+- `list_endpoints`: optional input `fields` (`full` default, or `compact`) with the output
+  fields `fields` and `qos_summary`; compact replaces each `qos` by a one-line summary and
+  drops `type_id`, `announced_ns` and `ros_topic_note`.
+
+### Changed
+
+- `tools/list` is about 37 percent smaller (about 178 KB to 113 KB compact), because some
+  clients truncated it: tool and field descriptions are shorter, and the generated schema
+  titles and nested-model docstrings are no longer served. Names, types, defaults and
+  constraints are unchanged. The long explanations moved to `docs/CONTRACT.md` section 9.
+- `domain_id` on `list_participants`, `participant_events`, `topic_metrics` and
+  `list_endpoints`: the description now opens with "Ignored", and a non-zero value that
+  differs from the domain joined at startup adds an explicit sentence to the response `note`
+  (the response `domain_id` already named the observed domain).
+
+### Fixed
+
+- `scripts/ground_truth/compare.py` counts only active DDS participants: the `ros2` CLI
+  processes that `get_node_info` starts stay listed with status `left` and inflated the count
+  (found on the OmniSim kit run of 2026-10-14 on 0.7.0: 76 checks passed, 0 failed).
+
+## [0.7.0] - 2026-10-12
+
+Breaking release: output contract 2 (see `docs/MIGRATION-0.7.md`), the move to the MCP SDK
+2.x, and a tool surface of 14 tools (`list_nodes` and `get_node_info` are new).
+
+### Breaking
+
+Output contract 2 (`health_check.contract_version` is 2; 0.6.x is implicitly 1). The tool
+list and the input defaults are unchanged except where noted. `docs/CONTRACT.md` is the
+specification and `docs/MIGRATION-0.7.md` expands this list.
+
+One object per tool, never a bare list:
+
+- `list_topics`: `list[TopicInfo]` -> `TopicListing {topics, returned, total, truncated,
+  mode_effective, note}`.
+- `list_participants`: `list[ParticipantInfo]` -> `ParticipantListing {participants, returned,
+  total, truncated, domain_id, mode_effective, note}`.
+- `participant_events`: `list[ParticipantEvent]` -> `ParticipantEventListing {events,
+  returned, total, truncated, domain_id, mode_effective, note}`. The silent 200-event cap is
+  now `truncated` plus a `note`.
+
+Topic models:
+
+- `TopicInfo` splits: `list_topics` returns `TopicListItem` (`name`, `message_type`,
+  `publisher_count`, `subscriber_count`, no QoS, no `mode_effective`); `get_topic_info`
+  returns `TopicInfo`.
+- `TopicInfo.qos_reliability` and `qos_durability` (publishers only) -> `publisher_qos` and
+  `subscription_qos` (`{reliability, durability, endpoint_count}`, `mixed` when the endpoints
+  of a side disagree), each with a `_note` when it is `null`. A topic with subscribers only
+  no longer reports nothing.
+- `TopicInfo` gains `publisher_nodes` and `subscriber_nodes` (fully qualified node names read
+  from `ros2 topic info --verbose`) and a `note`.
+- Removed because no adapter ever filled them: `TopicInfo.reader_count`, `writer_count` and
+  `qos_profile`; `BagAnalysis.samples_decoded_count`, `participants_recorded` and
+  `recording_duration_ns`.
+
+Renames (unit suffixes, `_reason` -> `_note`):
+
+- `BagAnalysis.duration_seconds` -> `duration_s`.
+- `TopicMetrics.window_seconds` -> `window_s`, `window_seconds_actual` -> `window_actual_s`,
+  `frequency_hz_observed` -> `observed_frequency_hz`, `frequency_hz_declared` ->
+  `declared_frequency_hz`.
+- Tool inputs: `topic_metrics.window_seconds` -> `window_s`, `participant_events.lookback_seconds`
+  -> `lookback_s`.
+- `EndpointListing.departed_endpoints` -> `departed_endpoint_count`,
+  `excluded_observer_endpoints` -> `excluded_observer_endpoint_count`, `total_discovered` ->
+  `total`.
+- `HealthReport.dds_inactive_reason` -> `dds_inactive_note`, `payload_decoding_reason` ->
+  `payload_decoding_note`.
+
+`list_endpoints`:
+
+- `EndpointInfo.topic` -> `dds_topic` (raw name, `rt/scan`) plus `ros_topic` (`/scan`, `null`
+  with `ros_topic_note` for a DDS topic that is not a ROS 2 topic). `TopicSummary.topic` ->
+  `dds_topic` plus `ros_topic`.
+- New input `include_internal` (default false): the ROS 2 service and action endpoints
+  (`rq/`, `rr/`, `rs/`, `rp/`, `ra/` and `ros_discovery_info`) are hidden unless it is true;
+  `hidden_internal_endpoint_count` says how many were left out.
+- `EndpointInfo.activity` (always `null`) and `activity_note` (the same sentence on every
+  endpoint) are removed; the sentence is stated once in the new root-level `hints`.
+- `EndpointInfo.domain_id` and `mode_effective` are removed (the listing carries them once).
+
+Nested items no longer repeat the envelope: `mode_effective` is removed from
+`ParticipantInfo`, `ParticipantEvent`, `EndpointInfo` and `MismatchReport`.
+
+`stamp_source` (every `MessageSample`) is required and has five values: `header`, `payload`,
+`recorded`, `dds_source`, `none`. It was nullable with four. `peek_dds_samples` now says
+`dds_source` (builtin discovery topics, from the announcement timestamp) or `none`.
+
+`sample_messages.timeout_s` accepts 1..40 (see Changed).
+
+Configuration and Python API:
+
+- `TOPICFORGE_DDS_BACKEND` accepts `mock`, `cyclone`, `fast` and `auto` only. `opendds` and
+  `dust` (stub adapters that never served) and the long-rejected `rti`, `opensplice`, `coredx`
+  and `intercom` now fail at startup with an error that names the valid values.
+  `health_check.dds_backend` no longer returns `opendds` or `dust`.
+- `RosAdapter` (an alias of `MiddlewareAdapter`) is removed from `topicforge.adapters`.
+
+### Added (contract 2)
+
+- `health_check`: `contract_version` (2), `rmw_implementation` and `rmw_source` (`env`,
+  `distro_default` or `none`; `ros2_cli` is reserved), and a `note`. The RMW comes from
+  `RMW_IMPLEMENTATION` or the default of `ROS_DISTRO`, never from the running graph.
+- A `note` on `get_topic_info`, `detect_qos_mismatches`, `topic_metrics` and `health_check`.
+- `analyze_bag` topics gain `kind`: `user`, `rosbag2_internal` (`/events/write_split`) or
+  `ros_builtin` (`/parameter_events`, `/rosout`).
+- Reserved optional fields: `ParticipantInfo.node_names` and `node_names_source` (empty and
+  `none` until a tool fills them), `MismatchReport.suggested_fixes` (empty).
+- `tests/test_contract_shape.py` (every tool returns one object and one text block),
+  `tests/test_field_names.py` (no `_seconds`, `_sec`, `_ms`, `_hertz`, `_reason` and similar
+  suffixes in any input or output field).
+
+### Added
+
+- Ground-truth comparator in CI (`scripts/ground_truth/`): one `compare.py`, two producers of
+  ground truth. The OmniSim kit (external, manual, kept as confirmation) and the Docker bench
+  publisher, which now writes its own `ground_truth.json` in the same schema subset
+  (`tests/integration/ros2/ground_truth.py`: topics, types, endpoint counts and QoS, the
+  synthetic 541-beam scan and its sector minima, configured rates, `use_sim_time` per node,
+  RMW and distro). `drive.py` is the parameterised MCP stdio driver and `calls.json` the
+  default call list (graph calls before any sampling). Every `ros2-live.yml` matrix cell
+  (Humble/Jazzy x Fast DDS/Cyclone) runs both after the integration tests, fails on any FAIL
+  or SHAPE row, prints the measured rate `interval_cv` values (the `STABLE_CV` evidence for
+  `docs/CONTRACT.md` section 4) and uploads `COMPARISON.md`, `comparison.json` and the raw
+  results as an artifact. `compare.py` also reads a bag with `rosbags` (`--bag-truth`) to
+  check `analyze_bag` and `peek_bag_samples` independently.
+- Two tools, additive: `list_nodes` and `get_node_info` (the surface is now fourteen tools).
+  - `list_nodes` -> `NodeListing {nodes, returned, total, truncated, duplicates,
+    mode_effective, note}`: one `ros2 node list` call, names, namespaces and the full names used
+    by more than one node (`duplicate_count`).
+  - `get_node_info(node, timeout_s)` -> `NodeInfo`: publishers, subscribers, service servers and
+    clients, action servers and clients (each `{name, type}`) from `ros2 node info`, then the
+    parameters from `ros2 param dump` (YAML on stdout, never an output option, so nothing is
+    written to disk) and `use_sim_time`. `timeout_s` is 1..20, default 8. A node that does not
+    answer its parameter read in time gives `parameters` null and a `parameters_note` (its
+    executor is probably blocked): a finding, not an error. A value whose name contains
+    password, secret, token, api_key or credential is masked; a value over 2048 characters or
+    128 list elements (a robot description) is cut and flagged; the dump is capped at 1 MiB.
+    A name used by several nodes is flagged in `duplicate_count` and `note`. An unknown node
+    raises an error that lists close matches.
+  - Both run the `ros2` CLI in the ROS lane; DDS-only setups raise a clear error. The only
+    request TopicForge ever sends is a parameter read (list/get) (SECURITY.md).
+  - The `inspect-ros2-robot` prompt and plugin skill gain the node step.
+- Per-type message summaries and an observed rate with a verdict on `sample_messages` and
+  `peek_bag_samples` (additive; no new input, no new tool).
+  - `MessageSample.summary`: `laser_scan` (beam count, angle geometry, finite / `inf` /
+    `-inf` / `nan` counts, closest obstacle, front / left / right / rear sector minima by
+    bearing in the sensor frame), `odometry` (speed, angular z, position, yaw), `imu` (roll,
+    pitch, yaw, angular velocity and acceleration norms, orientation validity), `image`
+    (size, encoding, step, buffer length) and `point_cloud2` (point count, layout). `null`
+    for any other type. Units are meters, radians and seconds with no unit suffix
+    (docs/CONTRACT.md section 4).
+  - The summary is computed on the whole message even when `payload` is cut: a scan is
+    streamed uncut (`--full-length`, up to 4 MiB per message while streaming), summarized,
+    then cut to `max_array_length` as before; `Image` and `PointCloud2` never read their
+    buffers; a bag scan is decoded whole.
+  - `SampleResult.rate`: `message_count`, `window_s`, mean / median / max interval,
+    `interval_cv`, `observed_frequency_hz` (wall clock: `received_ns`, or `recorded_ns` for a
+    bag), `sim_frequency_hz` (from the messages' own stamps), `trailing_gap_s` and a
+    `verdict`: `silent`, `insufficient`, `intermittent`, `stable`, `jittery` or `erratic`.
+    Thresholds confirmed at 0.2 and 0.5 on both bases; the `jittery` note gives the longest
+    gap as a multiple of the median. Physical quantities carry no unit suffix (CONTRACT 1.4).
+  - `peek_bag_samples` now returns non-finite floats as the strings `nan`, `inf`, `-inf`
+    (they could not be written as JSON numbers).
+  - Mock mode: `/scan` is a 720-beam scan in a walled room, and `/imu/data` is a new mock
+    topic.
+- MCP prompts `diagnose-dds-bus` (optional `topic`, `symptom`) and `inspect-ros2-robot`
+  (optional `topic`, `bag_path`), the plugin skills in client-neutral wording, and server
+  `instructions` in the `initialize` result (read-only guarantee, which tool first,
+  `contract_version`) for clients that do not show prompts. They are snapshotted in
+  `tests/contract/_prompts.json`.
+- `tests/test_tool_descriptions.py`: no history words (`v0.x`, `Phase`, `ceiling`, `TODO`,
+  `since 0.`) in any tool or field description, and every tool that takes a lane lock states
+  its 45 s bound.
+- `docs/MIGRATION-0.7.md`: every old field and its new name, with before and after JSON.
+- Optional local HTTP transport: `topicforge --transport streamable-http --port N` serves the
+  tools on `http://127.0.0.1:N/mcp`. stdio stays the default. The bind address is fixed to
+  127.0.0.1 (no flag changes it) and DNS-rebinding protection is on (loopback `Host` and
+  `Origin` only). There is no authentication: use an SSH tunnel to reach a robot. See
+  `docs/CLIENTS.md`.
+- `docs/CONTRACT.md`: the output contract (one object per tool, a single `note`, no silent
+  null, suffix vocabulary, enum casing by layer, non-finite floats, reserved optional fields,
+  rate verdicts) and the complete list of renames and splits.
+- `docs/TOOLS.md`: tool reference generated from the served tools.
+- Golden snapshots of every tool (`tests/contract/*.json`), generated by
+  `scripts/contract/snapshot_tools.py`, and `tests/test_contract_snapshots.py`, which fails
+  with a diff on any change to a description, schema or annotation and when `TOOLS.md` is
+  stale.
+
+### Removed
+
+- The `opendds` and `dust` stub adapters (`topicforge.adapters.dds_opendds`,
+  `dds_dust`), their tests and the `requires_opendds` / `requires_dust` markers. The Pro tier
+  and `topicforge_pro` hook were already gone in 0.5.3: no code, setting or documentation
+  mentions `TOPICFORGE_LICENSE_KEY` any more.
+- The `RosAdapter` alias (see Breaking).
+
+### Changed
+
+- Tool descriptions state present behaviour only, name the lock they take and their worst-case
+  duration (45 s, lock wait included), and the description of `SampleResult.count` no longer
+  contradicts itself on the maximum of 50.
+- Moved to the MCP Python SDK 2.x: the dependency is now `mcp>=2.3,<3` (it was `mcp>=1.0.0,<2`).
+  `FastMCP` became `MCPServer`; the server reports `name` and `version` through the
+  constructor, which replaces the private-attribute workaround of 0.6.4. Handlers, tool
+  names, parameters and the stdio transport are unchanged. The SDK brings new dependencies
+  (`mcp-types`, `httpx2`, `opentelemetry-api`, `anyio`, `pydantic>=2.12`). The served schemas
+  differ only where the SDK serializes differently (see the golden snapshot commit).
+- Tool calls are serialized per backend (`topicforge.tools.guard`): the 2.x SDK runs
+  synchronous handlers in worker threads, and neither the Cyclone binding nor the `ros2` CLI
+  adapter can take overlapping calls. There are two locks: a ROS lane (six tools: `list_topics`,
+  `get_topic_info`, `list_nodes`, `get_node_info`, `sample_messages`, `analyze_bag`) and a
+  DDS lane (six tools: `list_participants`, `detect_qos_mismatches`, `peek_dds_samples`,
+  `participant_events`, `topic_metrics`, `list_endpoints`), so a slow `sample_messages` no longer delays a DDS call.
+  `health_check` and `peek_bag_samples` take no lock.
+- A tool call has a wall budget of 45 s, lock wait included. A call that waited for its lane
+  runs with the time that is left (the `ros2` timeouts shrink accordingly), and one that cannot
+  start with at least 5 s left fails at once with `busy: another ros call is running, retry`
+  (or `dds`) instead of waiting. At most 16 calls queue per lane.
+- `sample_messages` `timeout_s` now accepts 1..40 (it was 1..45), so that the timeout plus
+  stopping the CLI and decoding stays under the 45 s budget. The default is unchanged (10).
+- `health_check` `sim_clock_published` no longer runs `ros2 topic info /clock`: it reports
+  what the last `list_topics` (or `get_topic_info` on `/clock`) saw, `null` before the first
+  graph read and two minutes after it. This is what lets `health_check` always answer.
+- CI builds the wheel and installs it into a fresh venv on Ubuntu and Windows.
+
+### Fixed
+
+- `rosbags` 0.11.6 is excluded: it builds message definitions with `PosixPath` and fails
+  on Windows for types with nested arrays, which broke opening some bags there.
+- The server can no longer freeze on a hung `ros2` CLI. Every `ros2` call now goes through one
+  process runner (`adapters/ros2_live/process_runner.py`) instead of `subprocess.run`: the
+  process starts in its own kill unit (Windows Job Object with a `taskkill /T` fallback, POSIX
+  process group with SIGINT then SIGKILL), runs under a hard deadline, and its whole tree is
+  killed at the deadline, so the stock `ros2` launcher can no longer leave an orphan holding
+  the output pipes. Output is capped at 8 MiB per stream. Error messages are unchanged.
+- `health_check` always answers, also while a `sample_messages` call is running.
+- The server no longer blocks the asyncio event loop during a long tool call (a 45 s
+  `sample_messages`, a hung `ros2` CLI): handlers run in worker threads, so the transport
+  keeps answering pings and cancellations.
+- `AdapterError` messages still reach the client as `isError` text. The 2.x SDK keeps the
+  text of any exception other than `ToolError` on the server, so every handler now
+  re-raises `AdapterError` as `ToolError` with the same message. Unexpected exceptions
+  stay redacted ("Error executing tool X") and leak no traceback.
+- `rate.observed_frequency_hz` on `received_ns` no longer counts the start-up drain of `ros2 topic echo` (up to 5 queued messages printed at once, which read `/clock` at 91 Hz for 50 Hz): the leading run of near-zero intervals is set aside and reported in the new additive `startup_burst_count`; the ground-truth comparator gates FAIL and STABLE_CV on 10 messages spanning 0.9 s.
+
 ## [0.6.4] - 2026-10-08
 
 ### Added
@@ -1388,7 +1661,9 @@ 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.6.4...HEAD
+[Unreleased]: https://github.com/yaniswav/TopicForge/compare/v0.7.1...HEAD
+[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
 [0.6.3]: https://github.com/yaniswav/TopicForge/compare/v0.6.2...v0.6.3
 [0.6.2]: https://github.com/yaniswav/TopicForge/compare/v0.6.1...v0.6.2

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: topicforge
-Version: 0.6.4
+Version: 0.7.1
 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
@@ -39,12 +39,13 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.10
 Requires-Dist: cyclonedds>=0.10; python_version < '3.14' and ((platform_system == 'Linux' and platform_machine == 'x86_64') or (platform_system == 'Windows' and platform_machine == 'AMD64') or platform_system == 'Darwin')
-Requires-Dist: mcp<2,>=1.0.0
+Requires-Dist: mcp<3,>=2.3
 Requires-Dist: pydantic>=2.6
 Requires-Dist: pyyaml>=6
-Requires-Dist: rosbags>=0.11.3
+Requires-Dist: rosbags!=0.11.6,>=0.11.3
 Provides-Extra: all
 Requires-Dist: cyclonedds>=0.10; extra == 'all'
 Provides-Extra: bags
@@ -72,9 +73,9 @@ 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 twelve typed tools that return frozen Pydantic schemas, 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 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.
 
-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. So far the author has observed Cyclone DDS and Dust DDS participants on a live bus. RTI Connext, OpenDDS, CoreDX and Fast DDS 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).
+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).
 
 ## Quickstart
 
@@ -100,21 +101,23 @@ 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`.
+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=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJ0b3BpY2ZvcmdlPT0wLjYuNCIsInRvcGljZm9yZ2UiXSwiZW52Ijp7IlRPUElDRk9SR0VfTU9ERSI6ImF1dG8iLCJUT1BJQ0ZPUkdFX0REU19CQUNLRU5EIjoiY3ljbG9uZSIsIlRPUElDRk9SR0VfRERTX0RPTUFJTl9JRCI6IjAifX0%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.6.4%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=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).
 
 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).
 
 ## Tools
 
-Every response except `health_check` carries `mode_effective` (`"live"` or `"mock"`), so a caller can tell a real graph from fixtures.
+Every response except `health_check` carries `mode_effective` (`"live"` or `"mock"`), so a caller can tell a real graph from fixtures, and a single `note` that explains anything unusual. `health_check.contract_version` is `2`. The full reference, with every field, is generated in [`docs/TOOLS.md`](docs/TOOLS.md); upgrading from 0.6.x: [`docs/MIGRATION-0.7.md`](docs/MIGRATION-0.7.md).
 
 | Tool                    | Purpose                                                                                          |
 | ----------------------- | ------------------------------------------------------------------------------------------------ |
 | `health_check`          | Environment and mode introspection. Always succeeds; reports `mode` next to `requested_mode`      |
 | `list_topics`           | Discover the ROS2 graph                                                                          |
 | `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 |
 | `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`          |
@@ -125,6 +128,8 @@ Every response except `health_check` carries `mode_effective` (`"live"` or `"moc
 | `peek_bag_samples`      | Decoded samples from a recorded bag, including ROS 1 `.bag` (`rosbags` ships with the package) |
 | `list_endpoints`        | DDS writers and readers with structured QoS, per-topic roll-up that flags orphans (writer with no reader, reader with no writer) |
 
+The server also offers two MCP prompts, `diagnose-dds-bus` and `inspect-ros2-robot`, that give a client the read-only call order, and short server `instructions` for clients that do not show prompts (see [`docs/CLIENTS.md`](docs/CLIENTS.md#prompts-and-instructions)).
+
 Walkthroughs against the mock, each with the exact tool calls and payloads, are in [`examples/`](examples/README.md). To run the DDS tools against a real bus with several programs and vendors, see [`examples/dds/README.md`](examples/dds/README.md) (`python examples/dds/run_all.py`).
 
 ## Modes
@@ -145,9 +150,9 @@ 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_reason`. 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 five ROS2 graph and bag tools to the CLI and the seven DDS tools to the DDS backend.
+`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.
 
-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. `opendds` and `dust` are permanent stubs that never serve. `rti`, `opensplice`, `coredx` and `intercom` are rejected with a configuration error,; 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).
+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).
 
 ## Configuration reference
 
@@ -157,26 +162,28 @@ A Fast DDS adapter exists but has never run against a bus, and its `fastdds` Pyt
 | `TOPICFORGE_LOG_LEVEL`     | `INFO`  | `DEBUG`, `INFO`, `WARNING`, `ERROR`                                                               |
 | `TOPICFORGE_ROS2_BIN`      | `ros2`  | Name or path of the ROS2 CLI binary                                                               |
 | `TOPICFORGE_TELEMETRY`     | `off`   | Opt-in anonymous telemetry; an unrecognized value aborts startup. See [Telemetry](#telemetry)     |
-| `TOPICFORGE_DDS_BACKEND`   | `mock`  | `mock` (no DDS backend), `cyclone`, `fast`, `auto` (`opendds` and `dust` are stubs)                |
+| `TOPICFORGE_DDS_BACKEND`   | `mock`  | `mock` (no DDS backend), `cyclone`, `fast`, `auto`; anything else is rejected                      |
 | `TOPICFORGE_DDS_DOMAIN_ID` | `0`     | DDS domain observed (0..232). Joined at startup; changing it needs a restart                      |
 | `TOPICFORGE_MAX_SAMPLE_BYTES` | `1048576` | Size cap for one sampled message (1 KiB..64 MiB); a call returns at most 4 times that. Over-cap messages are dropped with a note |
 
+Command-line options (not environment variables): `--transport stdio|streamable-http` (default `stdio`) and `--port N` (default 8765, only with `streamable-http`). The HTTP transport binds `127.0.0.1` only, with DNS-rebinding protection and no authentication; see [docs/CLIENTS.md](docs/CLIENTS.md#local-http-transport).
+
 Samples with comments are in [`.env.example`](.env.example). Any invalid value stops the server with `topicforge: configuration error: ...` and exit code 2, so a typo cannot silently change behaviour.
 
 ## Limitations
 
-External validation against a simulated robot's ground truth: [docs/VALIDATION.md](docs/VALIDATION.md).
+External validation against a simulated robot's ground truth (OmniSim): [docs/VALIDATION.md](docs/VALIDATION.md).
 
-- DDS validation is partial. The Cyclone adapter has run against a real bus, with Cyclone and Dust DDS participants, on Windows and in CI on Ubuntu and Windows (`.github/workflows/demo.yml`). The Fast DDS adapter has never run against a bus, and no RTI, OpenDDS, CoreDX or OpenSplice participant has been observed by this project. The multi-vendor claim rests on the RTPS protocol guarantee, not on a recorded cross-vendor run.
+- DDS validation is partial. The Cyclone adapter has run against real buses with Cyclone, Fast DDS and Dust DDS participants, on Windows and in CI on Ubuntu and Windows (`.github/workflows/demo.yml`, `.github/workflows/ros2-live.yml`). The Fast DDS adapter (TopicForge joining through the `fastdds` binding) has never run against a bus, and no RTI, OpenDDS, CoreDX or OpenSplice participant has been observed by this project. The multi-vendor claim rests on the RTPS protocol guarantee, not on a recorded cross-vendor run.
 - User-topic payloads are not decoded. `peek_dds_samples` on a user topic returns count 0 and a note that the topic is announced on the bus; no traffic is read. `topic_metrics` therefore has data only for the builtin discovery topics and says so in its `status`. It is a discovery-layer probe, not a publish-rate monitor.
 - Liveliness at runtime is not observed. A writer that is alive but silent (a hung process whose lease is still renewed) looks healthy, because TopicForge reads discovery, not data. An opt-in data probe is planned. A crash and a clean leave cannot be told apart, and `lost_ns` is an upper bound of the death.
 - Cyclone vendor ids: participants that do not follow the RTPS vendor-id convention in their GUID prefix (Dust DDS, and RTI by default) are reported with vendor `unknown`.
 - Single domain: the server observes the domain it joined at startup; changing it needs a restart.
 - DDS Security is not handled. A participant without credentials sees an empty secure bus. `detect_qos_mismatches` checks Partition, type name, Reliability, Durability, Deadline, Liveliness, LatencyBudget, Ownership (kind), DestinationOrder and DataRepresentation (History as a risk); Presentation, XTypes assignability and runtime behavior are not checked, and the result lists them in `policies_unchecked`. It returns a `MismatchScan` envelope: read `reports` for the mismatches.
 - Fast DDS serves no `list_endpoints`.
-- `sample_messages` (live) streams `ros2 topic echo` until `count` messages arrive or `timeout_s` (1..45, default 10, for the whole call) runs out, and returns what arrived with a `note` (`N of M messages within T s`, saying whether a publisher exists). QoS is matched to the publishers, so latched topics work. The payload has nested named fields (`payload.header.stamp.sec`); `timestamp_ns` is `header.stamp` (the publisher's clock, sim time on a simulation), the time in the body of `/clock`, `/tf` and `/rosout` messages (`stamp_source` `payload`), or 0 for other headerless types, with `stamp_source` and `received_ns` (wall clock when the CLI printed it). Arrays are cut at 128 elements by default; `max_array_length` (1..65536, or null for no cut) and `arrays_summary_only` change that, and a cut is listed under `_truncated_fields`. `nan` and `inf` come back as strings. `count` above 50 is capped with a note.
+- `sample_messages` (live) streams `ros2 topic echo` until `count` messages arrive or `timeout_s` (1..40, default 10, for the whole call) runs out, and returns what arrived with a `note` (`N of M messages within T s`, saying whether a publisher exists). QoS is matched to the publishers, so latched topics work. The payload has nested named fields (`payload.header.stamp.sec`); `timestamp_ns` is `header.stamp` (the publisher's clock, sim time on a simulation), the time in the body of `/clock`, `/tf` and `/rosout` messages (`stamp_source` `payload`), or 0 for other headerless types, with `stamp_source` and `received_ns` (wall clock when the CLI printed it). Arrays are cut at 128 elements by default; `max_array_length` (1..65536, or null for no cut) and `arrays_summary_only` change that, and a cut is listed under `_truncated_fields`. `nan` and `inf` come back as strings. `count` above 50 is capped with a note.
 - `analyze_bag` (live) parses `ros2 bag info` text for the totals and counts; anomaly detection is mock-only. Per-topic times, rates (`(n - 1) / span`) and `latched` are added when the bag can be read locally (`.db3` with the standard library, `.mcap` with `rosbags`), else rates fall back to count / bag duration (`frequency_basis`). `peek_bag_samples` reads the file itself, through `rosbags`, returns the first `count` messages in recording order (not the last), and is served only by the ROS2 CLI adapter or the mock; its `timestamp_ns` is the message's `header.stamp` (`stamp_source` `header`), the body time of `Clock`, `TFMessage` and `Log` messages (`payload`) or, without either, the bag record time (`stamp_source` `recorded`), and `recorded_ns` is always the bag record time; bags that embed no message definitions (Humble `.db3`) are decoded with the Humble definitions, or the distro the bag records, and `note` says so. Without `ros2`, bag tools return fixtures: check `health_check` for `mode: "mock"` before trusting bag output. `health_check` also reports `sim_clock_published` (live only): true when `/clock` has a publisher, a hint that header stamps may be simulation time.
-- Synchronous handlers: the tools run on the MCP event loop; on Windows a hung `ros2` launcher can block the server.
+- Calls are serialized per backend (one `ros2` call at a time, one DDS call at a time) and each call has a 45 s wall budget, lock wait included; a call that cannot get its lane fails at once with `busy`. `health_check` and `peek_bag_samples` take no lock.
 - No streaming or push subscriptions: tools are strictly request/response.
 
 Next: an opt-in probe to tell a hung writer from a healthy one, wider real-bus validation (Fast DDS, RTI, OpenDDS), and DDS Security. Open work is tracked in [issues](https://github.com/yaniswav/TopicForge/issues).
@@ -195,10 +202,10 @@ When on, each tool call emits one event with exactly six fields:
 
 | Field        | Example         | Notes                                                       |
 | ------------ | --------------- | ----------------------------------------------------------- |
-| `tool_name`  | `"list_topics"` | One of the twelve tools, never argument values              |
+| `tool_name`  | `"list_topics"` | One of the fourteen 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.6.4"`       | TopicForge server version                                   |
+| `version`    | `"0.7.1"`       | TopicForge server version                                   |
 | `session_id` | `"a1b2c3..."`   | Random UUID per process, never persisted                    |
 | `success`    | `true`          | Whether the handler returned or raised                      |
 
@@ -230,14 +237,14 @@ Tests run against the mock adapter, the live adapter's pure parsers and the bind
 
 ## Upgrading
 
-TopicForge is pre-1.0; [`CHANGELOG.md`](CHANGELOG.md) lists every change, including the yanked releases and removed extras.
+TopicForge is pre-1.0; [`CHANGELOG.md`](CHANGELOG.md) lists every change, including the yanked releases and removed extras. 0.7.0 changed the shape of tool results (`contract_version` 2): [`docs/MIGRATION-0.7.md`](docs/MIGRATION-0.7.md) maps every old field to its new one.
 
 ## Layout
 
 ```
 src/topicforge/
-  server/      MCP bootstrap, build_app(settings)
-  tools/       thin FastMCP handlers, no backend logic
+  server/      MCP bootstrap, build_app(settings), prompts and instructions
+  tools/       thin MCPServer handlers, no backend logic
   services/    input validation, orchestration, adapter factory
   adapters/    ros2_live, ros2_mock, dds_cyclone, dds_fast, common/ (binding-free logic)
   models/      frozen Pydantic schemas, the contract with MCP clients

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

@@ -12,9 +12,9 @@ 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 twelve typed tools that return frozen Pydantic schemas, 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 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.
 
-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. So far the author has observed Cyclone DDS and Dust DDS participants on a live bus. RTI Connext, OpenDDS, CoreDX and Fast DDS 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).
+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).
 
 ## Quickstart
 
@@ -40,21 +40,23 @@ 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`.
+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=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJ0b3BpY2ZvcmdlPT0wLjYuNCIsInRvcGljZm9yZ2UiXSwiZW52Ijp7IlRPUElDRk9SR0VfTU9ERSI6ImF1dG8iLCJUT1BJQ0ZPUkdFX0REU19CQUNLRU5EIjoiY3ljbG9uZSIsIlRPUElDRk9SR0VfRERTX0RPTUFJTl9JRCI6IjAifX0%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.6.4%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=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).
 
 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).
 
 ## Tools
 
-Every response except `health_check` carries `mode_effective` (`"live"` or `"mock"`), so a caller can tell a real graph from fixtures.
+Every response except `health_check` carries `mode_effective` (`"live"` or `"mock"`), so a caller can tell a real graph from fixtures, and a single `note` that explains anything unusual. `health_check.contract_version` is `2`. The full reference, with every field, is generated in [`docs/TOOLS.md`](docs/TOOLS.md); upgrading from 0.6.x: [`docs/MIGRATION-0.7.md`](docs/MIGRATION-0.7.md).
 
 | Tool                    | Purpose                                                                                          |
 | ----------------------- | ------------------------------------------------------------------------------------------------ |
 | `health_check`          | Environment and mode introspection. Always succeeds; reports `mode` next to `requested_mode`      |
 | `list_topics`           | Discover the ROS2 graph                                                                          |
 | `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 |
 | `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`          |
@@ -65,6 +67,8 @@ Every response except `health_check` carries `mode_effective` (`"live"` or `"moc
 | `peek_bag_samples`      | Decoded samples from a recorded bag, including ROS 1 `.bag` (`rosbags` ships with the package) |
 | `list_endpoints`        | DDS writers and readers with structured QoS, per-topic roll-up that flags orphans (writer with no reader, reader with no writer) |
 
+The server also offers two MCP prompts, `diagnose-dds-bus` and `inspect-ros2-robot`, that give a client the read-only call order, and short server `instructions` for clients that do not show prompts (see [`docs/CLIENTS.md`](docs/CLIENTS.md#prompts-and-instructions)).
+
 Walkthroughs against the mock, each with the exact tool calls and payloads, are in [`examples/`](examples/README.md). To run the DDS tools against a real bus with several programs and vendors, see [`examples/dds/README.md`](examples/dds/README.md) (`python examples/dds/run_all.py`).
 
 ## Modes
@@ -85,9 +89,9 @@ 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_reason`. 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 five ROS2 graph and bag tools to the CLI and the seven DDS tools to the DDS backend.
+`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.
 
-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. `opendds` and `dust` are permanent stubs that never serve. `rti`, `opensplice`, `coredx` and `intercom` are rejected with a configuration error,; 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).
+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).
 
 ## Configuration reference
 
@@ -97,26 +101,28 @@ A Fast DDS adapter exists but has never run against a bus, and its `fastdds` Pyt
 | `TOPICFORGE_LOG_LEVEL`     | `INFO`  | `DEBUG`, `INFO`, `WARNING`, `ERROR`                                                               |
 | `TOPICFORGE_ROS2_BIN`      | `ros2`  | Name or path of the ROS2 CLI binary                                                               |
 | `TOPICFORGE_TELEMETRY`     | `off`   | Opt-in anonymous telemetry; an unrecognized value aborts startup. See [Telemetry](#telemetry)     |
-| `TOPICFORGE_DDS_BACKEND`   | `mock`  | `mock` (no DDS backend), `cyclone`, `fast`, `auto` (`opendds` and `dust` are stubs)                |
+| `TOPICFORGE_DDS_BACKEND`   | `mock`  | `mock` (no DDS backend), `cyclone`, `fast`, `auto`; anything else is rejected                      |
 | `TOPICFORGE_DDS_DOMAIN_ID` | `0`     | DDS domain observed (0..232). Joined at startup; changing it needs a restart                      |
 | `TOPICFORGE_MAX_SAMPLE_BYTES` | `1048576` | Size cap for one sampled message (1 KiB..64 MiB); a call returns at most 4 times that. Over-cap messages are dropped with a note |
 
+Command-line options (not environment variables): `--transport stdio|streamable-http` (default `stdio`) and `--port N` (default 8765, only with `streamable-http`). The HTTP transport binds `127.0.0.1` only, with DNS-rebinding protection and no authentication; see [docs/CLIENTS.md](docs/CLIENTS.md#local-http-transport).
+
 Samples with comments are in [`.env.example`](.env.example). Any invalid value stops the server with `topicforge: configuration error: ...` and exit code 2, so a typo cannot silently change behaviour.
 
 ## Limitations
 
-External validation against a simulated robot's ground truth: [docs/VALIDATION.md](docs/VALIDATION.md).
+External validation against a simulated robot's ground truth (OmniSim): [docs/VALIDATION.md](docs/VALIDATION.md).
 
-- DDS validation is partial. The Cyclone adapter has run against a real bus, with Cyclone and Dust DDS participants, on Windows and in CI on Ubuntu and Windows (`.github/workflows/demo.yml`). The Fast DDS adapter has never run against a bus, and no RTI, OpenDDS, CoreDX or OpenSplice participant has been observed by this project. The multi-vendor claim rests on the RTPS protocol guarantee, not on a recorded cross-vendor run.
+- DDS validation is partial. The Cyclone adapter has run against real buses with Cyclone, Fast DDS and Dust DDS participants, on Windows and in CI on Ubuntu and Windows (`.github/workflows/demo.yml`, `.github/workflows/ros2-live.yml`). The Fast DDS adapter (TopicForge joining through the `fastdds` binding) has never run against a bus, and no RTI, OpenDDS, CoreDX or OpenSplice participant has been observed by this project. The multi-vendor claim rests on the RTPS protocol guarantee, not on a recorded cross-vendor run.
 - User-topic payloads are not decoded. `peek_dds_samples` on a user topic returns count 0 and a note that the topic is announced on the bus; no traffic is read. `topic_metrics` therefore has data only for the builtin discovery topics and says so in its `status`. It is a discovery-layer probe, not a publish-rate monitor.
 - Liveliness at runtime is not observed. A writer that is alive but silent (a hung process whose lease is still renewed) looks healthy, because TopicForge reads discovery, not data. An opt-in data probe is planned. A crash and a clean leave cannot be told apart, and `lost_ns` is an upper bound of the death.
 - Cyclone vendor ids: participants that do not follow the RTPS vendor-id convention in their GUID prefix (Dust DDS, and RTI by default) are reported with vendor `unknown`.
 - Single domain: the server observes the domain it joined at startup; changing it needs a restart.
 - DDS Security is not handled. A participant without credentials sees an empty secure bus. `detect_qos_mismatches` checks Partition, type name, Reliability, Durability, Deadline, Liveliness, LatencyBudget, Ownership (kind), DestinationOrder and DataRepresentation (History as a risk); Presentation, XTypes assignability and runtime behavior are not checked, and the result lists them in `policies_unchecked`. It returns a `MismatchScan` envelope: read `reports` for the mismatches.
 - Fast DDS serves no `list_endpoints`.
-- `sample_messages` (live) streams `ros2 topic echo` until `count` messages arrive or `timeout_s` (1..45, default 10, for the whole call) runs out, and returns what arrived with a `note` (`N of M messages within T s`, saying whether a publisher exists). QoS is matched to the publishers, so latched topics work. The payload has nested named fields (`payload.header.stamp.sec`); `timestamp_ns` is `header.stamp` (the publisher's clock, sim time on a simulation), the time in the body of `/clock`, `/tf` and `/rosout` messages (`stamp_source` `payload`), or 0 for other headerless types, with `stamp_source` and `received_ns` (wall clock when the CLI printed it). Arrays are cut at 128 elements by default; `max_array_length` (1..65536, or null for no cut) and `arrays_summary_only` change that, and a cut is listed under `_truncated_fields`. `nan` and `inf` come back as strings. `count` above 50 is capped with a note.
+- `sample_messages` (live) streams `ros2 topic echo` until `count` messages arrive or `timeout_s` (1..40, default 10, for the whole call) runs out, and returns what arrived with a `note` (`N of M messages within T s`, saying whether a publisher exists). QoS is matched to the publishers, so latched topics work. The payload has nested named fields (`payload.header.stamp.sec`); `timestamp_ns` is `header.stamp` (the publisher's clock, sim time on a simulation), the time in the body of `/clock`, `/tf` and `/rosout` messages (`stamp_source` `payload`), or 0 for other headerless types, with `stamp_source` and `received_ns` (wall clock when the CLI printed it). Arrays are cut at 128 elements by default; `max_array_length` (1..65536, or null for no cut) and `arrays_summary_only` change that, and a cut is listed under `_truncated_fields`. `nan` and `inf` come back as strings. `count` above 50 is capped with a note.
 - `analyze_bag` (live) parses `ros2 bag info` text for the totals and counts; anomaly detection is mock-only. Per-topic times, rates (`(n - 1) / span`) and `latched` are added when the bag can be read locally (`.db3` with the standard library, `.mcap` with `rosbags`), else rates fall back to count / bag duration (`frequency_basis`). `peek_bag_samples` reads the file itself, through `rosbags`, returns the first `count` messages in recording order (not the last), and is served only by the ROS2 CLI adapter or the mock; its `timestamp_ns` is the message's `header.stamp` (`stamp_source` `header`), the body time of `Clock`, `TFMessage` and `Log` messages (`payload`) or, without either, the bag record time (`stamp_source` `recorded`), and `recorded_ns` is always the bag record time; bags that embed no message definitions (Humble `.db3`) are decoded with the Humble definitions, or the distro the bag records, and `note` says so. Without `ros2`, bag tools return fixtures: check `health_check` for `mode: "mock"` before trusting bag output. `health_check` also reports `sim_clock_published` (live only): true when `/clock` has a publisher, a hint that header stamps may be simulation time.
-- Synchronous handlers: the tools run on the MCP event loop; on Windows a hung `ros2` launcher can block the server.
+- Calls are serialized per backend (one `ros2` call at a time, one DDS call at a time) and each call has a 45 s wall budget, lock wait included; a call that cannot get its lane fails at once with `busy`. `health_check` and `peek_bag_samples` take no lock.
 - No streaming or push subscriptions: tools are strictly request/response.
 
 Next: an opt-in probe to tell a hung writer from a healthy one, wider real-bus validation (Fast DDS, RTI, OpenDDS), and DDS Security. Open work is tracked in [issues](https://github.com/yaniswav/TopicForge/issues).
@@ -135,10 +141,10 @@ When on, each tool call emits one event with exactly six fields:
 
 | Field        | Example         | Notes                                                       |
 | ------------ | --------------- | ----------------------------------------------------------- |
-| `tool_name`  | `"list_topics"` | One of the twelve tools, never argument values              |
+| `tool_name`  | `"list_topics"` | One of the fourteen 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.6.4"`       | TopicForge server version                                   |
+| `version`    | `"0.7.1"`       | TopicForge server version                                   |
 | `session_id` | `"a1b2c3..."`   | Random UUID per process, never persisted                    |
 | `success`    | `true`          | Whether the handler returned or raised                      |
 
@@ -170,14 +176,14 @@ Tests run against the mock adapter, the live adapter's pure parsers and the bind
 
 ## Upgrading
 
-TopicForge is pre-1.0; [`CHANGELOG.md`](CHANGELOG.md) lists every change, including the yanked releases and removed extras.
+TopicForge is pre-1.0; [`CHANGELOG.md`](CHANGELOG.md) lists every change, including the yanked releases and removed extras. 0.7.0 changed the shape of tool results (`contract_version` 2): [`docs/MIGRATION-0.7.md`](docs/MIGRATION-0.7.md) maps every old field to its new one.
 
 ## Layout
 
 ```
 src/topicforge/
-  server/      MCP bootstrap, build_app(settings)
-  tools/       thin FastMCP handlers, no backend logic
+  server/      MCP bootstrap, build_app(settings), prompts and instructions
+  tools/       thin MCPServer handlers, no backend logic
   services/    input validation, orchestration, adapter factory
   adapters/    ros2_live, ros2_mock, dds_cyclone, dds_fast, common/ (binding-free logic)
   models/      frozen Pydantic schemas, the contract with MCP clients