topicforge 0.7.2__tar.gz → 0.8.1__tar.gz

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

@@ -5,7 +5,195 @@ All notable changes to TopicForge are documented in this file.
 The format is based on [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.8.1] - 2026-10-26
+
+The 0.8.0 evaluation findings, a URDF read from the robot_state_publisher parameter, an optional
+HTTP bearer token, a Docker image and a SROS2 bench cell. Additive only (`docs/CONTRACT.md`
+section 9.18). `tools/list` is 97,315 bytes (+467).
+
+### Added
+
+- HTTP transport: `TOPICFORGE_HTTP_TOKEN` (at least 32 printable characters, environment only)
+  makes every request carry `Authorization: Bearer <token>`, compared in constant time, else
+  `401`. `--host` may bind an address other than loopback only with a token; such a bind lifts
+  the DNS-rebinding allow-list. Plain HTTP: SECURITY.md says what the token does not cover.
+- `inspect_tf` reads the URDF from the `robot_description` parameter of the node named
+  `robot_state_publisher` when no node publishes `/robot_description`; `urdf_note` names the node.
+- `reader_node` and `writer_node` on `detect_qos_mismatches` reports, `not_matched` and
+  `matched` pairs.
+- A root `Dockerfile`: a stdio image on `ros:jazzy-ros-core` with the `ros2` CLI and Cyclone DDS,
+  non-root. Live graphs need Linux `--network host`; docs/CLIENTS.md has the Docker Desktop
+  limits.
+- Bench: a `sros2` job (`run_bench.py --sros2`) with one node under SROS2 Enforce. Run on jazzy
+  with Cyclone and Fast DDS, 4 of 4 checks in each.
+- Eval harness: `restarts_at_first_call` in the `restart_loop` summary, counted at the agent's
+  first call rather than at `READY`.
+
+### Changed
+
+- `inspect_tf`: an edge with a steady rate silent for over ten of its periods (at least 1 s) is
+  stale even under `stale_after_s`. With the defaults, the evaluation's `tf_stale` read as healthy.
+- `restarts_by_name` leaves out the name `/` that every ROS 2 node shares on Fast DDS; the note
+  points to `restarts_by_node`.
+- `min_log_level` accepts `WARN`, `Error` and `warning`.
+- `detect_qos_mismatches` without `topic` leaves `ros_discovery_info` out, and folds orphan
+  topics into one hint per side instead of one hint each.
+- `param_diff_summary` names the `same` and `live_only` parameters.
+- A filtered `/rosout` read that received nothing says so, instead of mixing the no-match advice
+  with the latched-topic advice.
+
+## [0.8.0] - 2026-10-21
+
+Graph diff, declared-against-real checks, DDS visibility and a Nav2 prompt. It also carries the
+0.7.3 work (schema compaction, clock fields, `/rosout` filters, bag ranges, lifecycle nodes),
+which was never published on its own: see "Folded in from 0.7.3" below. Additive only
+(`docs/CONTRACT.md` section 9). Validated on the Docker ROS 2 bench (Humble and Jazzy,
+rmw_fastrtps and rmw_cyclonedds) and by a blind evaluation of 14 runs (`docs/EVAL.md`).
+
+### Added
+
+- `graph_diff`, the sixteenth tool: "what changed since it last worked". Each call snapshots the
+  ROS 2 graph (nodes, topics, types, publisher and subscriber counts, writer QoS when a DDS backend
+  is up) or a bag (`bag_path`: topics, types, rates, latching), keeps it in an in-memory ring of 16
+  (`snap-N` ids, emptied on restart, nothing written to disk) and compares it with `baseline`:
+  `previous`, a snapshot id or a bag path, in one string. The result is a sorted list of node,
+  topic, type, qos, rate and count differences with what could not be compared named in
+  `not_compared` (nodes and counts only live against live, rates only bag against bag, writer QoS
+  only with a DDS backend). Endpoint-count noise on `/rosout` and `/parameter_events` is tallied in
+  `builtin_changes_count`, never reported. ROS lane, read-only, open world. `docs/CONTRACT.md`
+  section 9.14.
+- The mock robot ships a `snap-0` baseline derived from its fixtures minus a node, a topic and a
+  QoS: the first mock call reports exactly three changes, the second none, and the mock bag is
+  accepted as a baseline.
+- Bench: `drive.py` gains `{"spawn": PATH}` (the
+  process is stopped when the session ends), `tests/integration/ros2/graph_change.py` adds the
+  node `/bench_v2`, the topic `/scan_v2` and a second `/cmd_vel_out` writer, and
+  `scripts/ground_truth/calls_graph_diff.json` runs the first, steady, v2 and bag calls. The
+  comparator gets a `graph_diff` section: the steady graph must give zero changes, the v2 graph
+  exactly three, a bag baseline no removal and no type or QoS change.
+- The `diagnose-nav2` prompt (the third, with optional `symptom` and `namespace`) and the plugin
+  skill of the same name: a read-only call order for a Nav2 stack (node list and lifecycle flags,
+  `lifecycle_manager` parameters, `/bond` heartbeats, the hidden latched `_action/status` topics
+  read with `sample_messages`, `inspect_tf` map to base_link, filtered `/rosout`, the controller's
+  velocity output) and a list of what TopicForge cannot see (lifecycle state, costmaps, the
+  behavior tree). No tool added, 0 bytes in `tools/list`. `docs/CONTRACT.md` section 9.17. Nav2
+  itself was not run: the prompt is verified on its primitives, not on a real stack.
+- Bench for those primitives: the image adds
+  `example_interfaces` and `bond`, `publisher.py` serves a never-called action `/bench_fib` and
+  publishes `/bond` (`bond/msg/Status`, id `bench_robot`, 1 Hz), `calls_nav_primitives.json` runs
+  `40_action_status` and `41_bond`, and the comparator gets a `nav_primitives` section (one latched
+  sample with an empty `status_list`, the action in `get_node_info.action_servers`, the status
+  topic absent from `list_topics`, the bond id on every `/bond` sample).
+- DDS visibility (lot C), without any verdict on security. `health_check` reports
+  `ros_security_enabled`, `ros_security_strategy`, `ros_security_keystore_set` (never the path)
+  and, when enabled, `ros_security_note` (a secured node's participant stays visible through SPDP,
+  its endpoints and data do not), all `null` without the `ros2` CLI. `ParticipantInfo.endpoint_count`
+  counts the endpoints seen per participant, and `list_participants` notes the ones with none for
+  more than 10 s, naming both causes (endpoint-less, or hidden by DDS Security). `EndpointInfo.node_name`
+  names the ROS 2 node of each endpoint, read from the `ros_discovery_info` gids (bytes 0 to 15 of
+  the 24-byte or 16-byte gid are the endpoint GUID), and `TopicSummary.writer_nodes` and
+  `reader_nodes` roll it up: the answer to "who writes `/scan`" when every Fast DDS participant is
+  called `/`. `tools/list` grows by 1,078 bytes. `docs/CONTRACT.md` section 9.16. Bench:
+  a `visibility` section checks the `/scan` writer is `/bench_robot`, its
+  participant has at least 12 endpoints and the security fields are `false` and `null`. No SROS2
+  cell yet.
+- Declared against real (lot B), `docs/CONTRACT.md` section 9.15. `inspect_tf` reads the latched
+  `/robot_description` after the capture and compares the URDF links with the TF frames:
+  `urdf_source`, `urdf_link_count`, `declared_frames_missing`, `frames_not_in_urdf`, `urdf_note`
+  and a `declared_not_published` finding (a link nothing publishes, with a reminder that a
+  non-fixed joint needs `/joint_states`). It needs `robot_state_publisher` (a topic; a URDF held
+  only as a parameter is not read) and a missing or refused document is a note, never an error.
+  `get_node_info` takes `params_file`, a server-side ROS 2 parameter YAML (`.yaml`/`.yml`, 1 MiB,
+  `yaml.safe_load`, never sent to the CLI or the node, nothing written) and returns `param_diff`
+  (`different`, `declared_only`, `masked`), `param_diff_summary` and `param_diff_note`; secrets
+  are never echoed from the file. The comparison runs in the service, so the `MiddlewareAdapter`
+  protocol is unchanged, and it works in mock mode. The mock robot publishes `/robot_description`
+  with a `gripper_link` nothing publishes (`list_topics` gains one topic). `tools/list` grows by
+  1,377 bytes. Bench: the publisher
+  latches a URDF with an unpublished `arm_link` and declares three parameters,
+  `bench_params.yaml` disagrees on `max_range` and adds `extra_gain`, `calls_declared.json` runs
+  `03p_node_info_params`, and the comparator gets a `declared` section.
+- Evaluation tooling for the 0.8.0 campaign (lot E; results in `docs/EVAL.md`, "0.8.0
+  campaign (v2)"). `scripts/agent_eval/tf.py list --brief` prints one line per tool (name, inputs
+  with `*` on required ones, first sentence): 2,309 bytes against 35,514 for the full listing on
+  the mock server; `list --tool NAME` prints one tool in full and `--host` reaches a broker on
+  another machine. `broker.py` gains `--server-cmd` (any command that starts TopicForge, such as
+  `/opt/tfenv/bin/topicforge` in the bench image), `--mode`, `--dds-backend`, repeatable `--env`
+  and `--calls-log` (one JSON line per request, so the runner counts an agent's tool calls itself);
+  it still listens on 127.0.0.1 unless `--host 0.0.0.0` is given. `publisher.py --fault NAME`
+  turns the bench robot into a clean robot with one fault: `healthy`, `blocked_executor`,
+  `tf_stale`, `qos_mismatch` (a best_effort `/scan_edge` writer against a reliable
+  `/edge_viewer`), `restart_loop` (a node that dies every 6 s and is started again),
+  `declared_drift` and `graph_v1_v2`; the faults live in the bench, TopicForge stays read-only, and
+  `publisher.py` without the flag is unchanged. `scripts/agent_eval/ros2_scenarios.py` starts one
+  scenario (broker, robot, companions) and writes the agent's workspace and prompt, with a
+  `--variant prompt` that adds the text of `inspect-ros2-robot` or `diagnose-nav2`; the expected
+  diagnoses are in `scripts/agent_eval/TRUTH_ROS2.md`. The image copies `scripts/agent_eval`.
+
+### Changed
+
+- `tools/list` is 96,848 bytes with sixteen tools (118,884 with fifteen in 0.7.2), under the
+  100,000-byte test ceiling. `graph_diff` itself costs nothing net: two levers pay for it (`docs/CONTRACT.md`
+  section 9.13, wire-compatible): the `**Duration**` lane note is one sentence, and
+  `anyOf: [X, null]` is served as `type: [X, "null"]` in output schemas only. A new test validates
+  every mock result against the output schema the server serves.
+- The ROS lane now serves eight tools (`graph_diff` joins the seven `ros2` CLI tools). The
+  `MiddlewareAdapter` protocol is unchanged.
+- Bench: `test_a_short_latched_result_hints_count_one` waits 6 s instead of 3 (it got no sample once
+  on a loaded Jazzy and Fast DDS runner).
+
+### Folded in from 0.7.3 (never published separately)
+
+#### Added
+
+- `list_nodes` flags lifecycle (managed) nodes: `NodeListItem.lifecycle`, plus
+  `NodeListing.lifecycle_count`, `lifecycle_note` (set when the service list failed, never a
+  silent false) and `by_namespace` (distinct node names per namespace). `NodeInfo.lifecycle`
+  likewise. A node is lifecycle when it serves `<full_name>/get_state` of type
+  `lifecycle_msgs/srv/GetState`; the state is never read. Costs one extra
+  `ros2 service list -t` (`docs/CONTRACT.md` section 9.10). The mock `camera_driver` is a
+  lifecycle node, which adds the topic `/camera_driver/transition_event` to the mock graph.
+  The bench gains `/robot1/bench_lifecycle` and the comparator rows for both fields.
+- `TopicRate` clock fields on `sample_messages` and `peek_bag_samples` (`docs/CONTRACT.md`
+  section 9.11): `clock_basis` (`wall`, `sim`, `none`, `mixed`), `stamp_age_median_s` and
+  `stamp_age_p95_s` (arrival minus stamp, wall-stamped topics only) and `stamp_regression_count`.
+  Additive, all with defaults. The bench gains `/imu/data`, `/pose_mixed` and `/stamps_regress`.
+- `sample_messages` filters `/rosout` (`rcl_interfaces/msg/Log`) with `min_log_level`
+  (`debug` .. `fatal`) and `node` (`/ns/name`, `name` or `ns.name`; exact or child logger, never a
+  prefix). A Log topic is read with a depth-2000 reader to receive the 10 s transient_local
+  buffer; with a filter the call streams until `timeout_s`, filters after decoding and returns the
+  NEWEST `count` matches in stamp order, with a `M of N matched` note. A filter on any other topic
+  is an error. `docs/CONTRACT.md` section 9.12.
+- `peek_bag_samples` gains `start_s` / `end_s` (bag-relative seconds on the record time,
+  `[start, end)`) and the same log filter (the FIRST `count` matches in range, bag order), and
+  `analyze_bag` returns `start_ns`, the record time of the bag's first message. The mock gains a
+  `/rosout` topic and bag topic. The bench logs WARN/ERROR/INFO, records `/rosout`, and the
+  comparator gets a `logs` section.
+
+#### Changed
+
+- `MiddlewareAdapter.sample_messages` gains keyword arguments `min_log_level` and `node`, and
+  `peek_bag_samples` gains `start_s`, `end_s`, `min_log_level` and `node` (all default `None`),
+  like `capture_tf` in 0.7.2. Custom adapters must accept them.
+- `tools/list` shrinks from 118,884 to about 95 KB (94,957 bytes, `docs/CONTRACT.md` section 9.9),
+  about 5 KB under the new 100,000-byte test ceiling, which is the headroom left before
+  `graph_diff`. Additive: `MessageSample.summary` is
+  advertised as an open object keyed by `summary_type` (the five strict shapes are still built
+  and validated by the server, and documented in `docs/TOOLS.md`), and `default` keywords are
+  dropped from output schemas only. Payloads are unchanged.
+- The ground-truth comparator checks the `tools/list` size (< 100,000 bytes).
+- The mock graph gained `/camera_driver/transition_event` and `/rosout`, so mock `list_topics`
+  totals change (two more topics).
+- A filtered bag read (`peek_bag_samples` with a log filter or a range) stops after 20 s or when
+  the call budget runs out and says so in `note`. A bag that starts at 0 (sim time) reports
+  `start_ns` 0, not `null`. The live `/rosout` depth-2000 reader is used only when a log filter
+  is set; an unfiltered read behaves as in 0.7.2.
+
+#### Fixed
+
+- `inspect_tf`: the `no_path` finding for unknown frames named every requested frame, even one
+  that exists ("No frame named camera_optical_frame or base_laser was seen"). Its text and
+  `frames` now list only the missing ones, like `path_note`.
 
 ## [0.7.2] - 2026-10-18
 
@@ -1713,7 +1901,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.7.2...HEAD
+[Unreleased]: https://github.com/yaniswav/TopicForge/compare/v0.8.1...HEAD
+[0.8.1]: https://github.com/yaniswav/TopicForge/compare/v0.8.0...v0.8.1
+[0.8.0]: https://github.com/yaniswav/TopicForge/compare/v0.7.2...v0.8.0
 [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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: topicforge
-Version: 0.7.2
+Version: 0.8.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
@@ -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 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.
+It gives the agent sixteen 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).
 
@@ -101,9 +101,9 @@ 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).
+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 (another `--host` needs a bearer token in `TOPICFORGE_HTTP_TOKEN`); 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=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).
+**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=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJ0b3BpY2ZvcmdlPT0wLjguMSIsInRvcGljZm9yZ2UiXSwiZW52Ijp7IlRPUElDRk9SR0VfTU9ERSI6ImF1dG8iLCJUT1BJQ0ZPUkdFX0REU19CQUNLRU5EIjoiY3ljbG9uZSIsIlRPUElDRk9SR0VfRERTX0RPTUFJTl9JRCI6IjAifX0%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.8.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).
 
@@ -119,6 +119,7 @@ Every response except `health_check` carries `mode_effective` (`"live"` or `"moc
 | `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 |
+| `graph_diff`            | What changed since it last worked: snapshots the ROS 2 graph (or a bag) and diffs it with `previous`, a `snap-N` id or a bag: nodes, topics, types, writer QoS, counts, bag rates |
 | `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`          |
@@ -129,7 +130,7 @@ 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)).
+The server also offers three MCP prompts, `diagnose-dds-bus`, `inspect-ros2-robot` and `diagnose-nav2`, 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`).
 
@@ -151,7 +152,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 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.
+`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 eight `ros2` CLI tools (`list_topics`, `get_topic_info`, `list_nodes`, `get_node_info`, `inspect_tf`, `graph_diff`, `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).
 
@@ -167,7 +168,7 @@ A Fast DDS adapter exists but has never run against a bus, and its `fastdds` Pyt
 | `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).
+Command-line options (not environment variables): `--transport stdio|streamable-http` (default `stdio`), `--port N` (default 8765) and `--host ADDR` (default `127.0.0.1`), the last two only with `streamable-http`. The HTTP transport binds `127.0.0.1` with DNS-rebinding protection; `TOPICFORGE_HTTP_TOKEN` (at least 32 characters) makes every request carry `Authorization: Bearer <token>` and is required for any other `--host` (plain HTTP, so prefer an SSH tunnel); 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.
 
@@ -203,10 +204,10 @@ When on, each tool call emits one event with exactly six fields:
 
 | Field        | Example         | Notes                                                       |
 | ------------ | --------------- | ----------------------------------------------------------- |
-| `tool_name`  | `"list_topics"` | One of the fifteen tools, never argument values            |
+| `tool_name`  | `"list_topics"` | One of the sixteen 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.2"`       | TopicForge server version                                   |
+| `version`    | `"0.8.1"`       | TopicForge server version                                   |
 | `session_id` | `"a1b2c3..."`   | Random UUID per process, never persisted                    |
 | `success`    | `true`          | Whether the handler returned or raised                      |
 

{topicforge-0.7.2 → topicforge-0.8.1}/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 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.
+It gives the agent sixteen 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).
 
@@ -40,9 +40,9 @@ 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).
+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 (another `--host` needs a bearer token in `TOPICFORGE_HTTP_TOKEN`); 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=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).
+**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=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJ0b3BpY2ZvcmdlPT0wLjguMSIsInRvcGljZm9yZ2UiXSwiZW52Ijp7IlRPUElDRk9SR0VfTU9ERSI6ImF1dG8iLCJUT1BJQ0ZPUkdFX0REU19CQUNLRU5EIjoiY3ljbG9uZSIsIlRPUElDRk9SR0VfRERTX0RPTUFJTl9JRCI6IjAifX0%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.8.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).
 
@@ -58,6 +58,7 @@ Every response except `health_check` carries `mode_effective` (`"live"` or `"moc
 | `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 |
+| `graph_diff`            | What changed since it last worked: snapshots the ROS 2 graph (or a bag) and diffs it with `previous`, a `snap-N` id or a bag: nodes, topics, types, writer QoS, counts, bag rates |
 | `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`          |
@@ -68,7 +69,7 @@ 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)).
+The server also offers three MCP prompts, `diagnose-dds-bus`, `inspect-ros2-robot` and `diagnose-nav2`, 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`).
 
@@ -90,7 +91,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 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.
+`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 eight `ros2` CLI tools (`list_topics`, `get_topic_info`, `list_nodes`, `get_node_info`, `inspect_tf`, `graph_diff`, `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).
 
@@ -106,7 +107,7 @@ A Fast DDS adapter exists but has never run against a bus, and its `fastdds` Pyt
 | `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).
+Command-line options (not environment variables): `--transport stdio|streamable-http` (default `stdio`), `--port N` (default 8765) and `--host ADDR` (default `127.0.0.1`), the last two only with `streamable-http`. The HTTP transport binds `127.0.0.1` with DNS-rebinding protection; `TOPICFORGE_HTTP_TOKEN` (at least 32 characters) makes every request carry `Authorization: Bearer <token>` and is required for any other `--host` (plain HTTP, so prefer an SSH tunnel); 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.
 
@@ -142,10 +143,10 @@ When on, each tool call emits one event with exactly six fields:
 
 | Field        | Example         | Notes                                                       |
 | ------------ | --------------- | ----------------------------------------------------------- |
-| `tool_name`  | `"list_topics"` | One of the fifteen tools, never argument values            |
+| `tool_name`  | `"list_topics"` | One of the sixteen 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.2"`       | TopicForge server version                                   |
+| `version`    | `"0.8.1"`       | TopicForge server version                                   |
 | `session_id` | `"a1b2c3..."`   | Random UUID per process, never persisted                    |
 | `success`    | `true`          | Whether the handler returned or raised                      |
 

{topicforge-0.7.2 → topicforge-0.8.1}/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.2" topicforge
+uvx --from "topicforge==0.8.1" 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.2`) is moved on every release together with the other
+The version pin (`==0.8.1`) 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.2"`, then use
+- **pip alternative.** `pip install "topicforge==0.8.1"`, 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.2", "topicforge"],
+      "args": ["--from", "topicforge==0.8.1", "topicforge"],
       "env": {
         "TOPICFORGE_MODE": "auto",
         "TOPICFORGE_DDS_BACKEND": "cyclone",
@@ -85,7 +85,7 @@ say where the file lives and what differs.
 
 ## Claude Code
 
-Plugin (server plus two skills, asks for backend and domain at install):
+Plugin (server plus three skills, asks for backend and domain at install):
 
 ```
 claude plugin marketplace add yaniswav/TopicForge
@@ -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.2" topicforge
+claude mcp add topicforge --env TOPICFORGE_MODE=auto --env TOPICFORGE_DDS_BACKEND=cyclone --env TOPICFORGE_DDS_DOMAIN_ID=0 -- uvx --from "topicforge==0.8.1" topicforge
 ```
 
 ## Claude Desktop
@@ -112,22 +112,22 @@ 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=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJ0b3BpY2ZvcmdlPT0wLjcuMiIsInRvcGljZm9yZ2UiXSwiZW52Ijp7IlRPUElDRk9SR0VfTU9ERSI6ImF1dG8iLCJUT1BJQ0ZPUkdFX0REU19CQUNLRU5EIjoiY3ljbG9uZSIsIlRPUElDRk9SR0VfRERTX0RPTUFJTl9JRCI6IjAifX0%3D)
+One click: [Add TopicForge to Cursor](https://cursor.com/install-mcp?name=topicforge&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJ0b3BpY2ZvcmdlPT0wLjguMSIsInRvcGljZm9yZ2UiXSwiZW52Ijp7IlRPUElDRk9SR0VfTU9ERSI6ImF1dG8iLCJUT1BJQ0ZPUkdFX0REU19CQUNLRU5EIjoiY3ljbG9uZSIsIlRPUElDRk9SR0VfRERTX0RPTUFJTl9JRCI6IjAifX0%3D)
 
-If that page does not open Cursor, use the raw deeplink: `cursor://anysphere.cursor-deeplink/mcp/install?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=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJ0b3BpY2ZvcmdlPT0wLjguMSIsInRvcGljZm9yZ2UiXSwiZW52Ijp7IlRPUElDRk9SR0VfTU9ERSI6ImF1dG8iLCJUT1BJQ0ZPUkdFX0REU19CQUNLRU5EIjoiY3ljbG9uZSIsIlRPUElDRk9SR0VfRERTX0RPTUFJTl9JRCI6IjAifX0%3D`
 
 Or paste the common JSON shape into `~/.cursor/mcp.json` (all projects) or
 `.cursor/mcp.json` (one project).
 
 ## Agent Plugins (Cursor and other compatible clients)
 
-The `plugin/` folder of this repository is also an [Agent Plugins](https://agent-plugins.org) 1.0.0 package: `plugin.json` (manifest), `mcp.json` (the same pinned `uvx` launch) and `skills/` (two skills). Clients that load that format, such as Cursor, can install it as a plugin and get the server and the skills in one step; the plain JSON config above remains the simplest route for everything else. The format has no user-configuration prompt, so the backend is fixed to `cyclone` and the domain to `0`; edit the `env` block of `mcp.json` to change them (see `plugin/README.md`). Cursor Directory (cursor.directory/plugins/new) and the Cursor marketplace take a repository URL; a repo-root `.cursor-plugin/marketplace.json` points Cursor at the `plugin/` subfolder. Whether each directory scanner accepts a subfolder is unverified.
+The `plugin/` folder of this repository is also an [Agent Plugins](https://agent-plugins.org) 1.0.0 package: `plugin.json` (manifest), `mcp.json` (the same pinned `uvx` launch) and `skills/` (three skills). Clients that load that format, such as Cursor, can install it as a plugin and get the server and the skills in one step; the plain JSON config above remains the simplest route for everything else. The format has no user-configuration prompt, so the backend is fixed to `cyclone` and the domain to `0`; edit the `env` block of `mcp.json` to change them (see `plugin/README.md`). Cursor Directory (cursor.directory/plugins/new) and the Cursor marketplace take a repository URL; a repo-root `.cursor-plugin/marketplace.json` points Cursor at the `plugin/` subfolder. Whether each directory scanner accepts a subfolder is unverified.
 
 ## 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.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)
+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.8.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`
+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.8.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`
 
 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.2", "topicforge"],
+      "args": ["--from", "topicforge==0.8.1", "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.2",
+to `"command": "cmd", "args": ["/c", "uvx", "--from", "topicforge==0.8.1",
 "topicforge"]` if it fails to start.
 
 ## Continue
@@ -184,7 +184,7 @@ mcpServers:
     command: uvx
     args:
       - "--from"
-      - "topicforge==0.7.2"
+      - "topicforge==0.8.1"
       - "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.2", "topicforge"],
+      "args": ["--from", "topicforge==0.8.1", "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.2", "topicforge"]
+args = ["--from", "topicforge==0.8.1", "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.2", topicforge]
+    args: [--from, "topicforge==0.8.1", 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 fifteen tools.
+local models may struggle with sixteen tools.
 
 ## Amazon Q Developer / Kiro
 
@@ -297,19 +297,61 @@ The endpoint is `http://127.0.0.1:8765/mcp`. Two cases it is meant for:
 - A robot: run it on the robot, then `ssh -L 8765:127.0.0.1:8765 robot` and use the same URL
   on your laptop.
 
-Threat model: the server has no authentication, so anything that can reach the port can read
-your robot graph. It therefore binds `127.0.0.1` only (there is no flag to change that) and
-rejects any request whose `Host` or `Origin` is not a loopback name with the served port, which
-stops a web page in your browser from reaching it through DNS rebinding. Do not forward the
-port to a network interface; use an SSH tunnel instead.
+Threat model: without a token the server has no authentication, so anything that can reach the
+port can read your robot graph. It therefore binds `127.0.0.1` by default and rejects any
+request whose `Host` or `Origin` is not a loopback name with the served port, which stops a web
+page in your browser from reaching it through DNS rebinding. Do not forward the port to a
+network interface; use an SSH tunnel instead.
+
+Bearer token (0.8.1). Set `TOPICFORGE_HTTP_TOKEN` to a secret of at least 32 printable
+characters (for example `openssl rand -hex 32`) and every request must then carry
+`Authorization: Bearer <token>`; a request without it gets `401`. The token is read from the
+environment only, never from a flag. Only with a token may `--host` name another address:
+
+```
+TOPICFORGE_HTTP_TOKEN=... topicforge --transport streamable-http --host 0.0.0.0 --port 8765
+```
+
+This is plain HTTP: the token and every answer cross the network in clear, so keep it to a
+network you trust, or put a TLS reverse proxy in front. The SSH tunnel above remains the safer
+way to reach a robot. Clients that support HTTP headers in their MCP config (Claude Code's
+`--header`, VS Code's `headers`, Cursor's `headers`) pass the token there.
+
+## Docker
+
+The repository's `Dockerfile` builds a stdio image on ROS 2 Jazzy (`ros:jazzy-ros-core`, the
+`ros2` CLI and Cyclone DDS included, a non-root user):
+
+```
+docker build -t topicforge .
+```
+
+Point a client at `docker` instead of `uvx`:
+
+```json
+{ "command": "docker", "args": ["run", "-i", "--rm", "topicforge"] }
+```
+
+What the container can see depends on its network:
+
+- Linux with `--network host` (and the robot's `ROS_DOMAIN_ID`, e.g. `-e ROS_DOMAIN_ID=0`):
+  the live graph, as a local install would.
+- Docker Desktop on Windows or macOS: the container does not see the host's DDS traffic. The
+  `ros2` CLI is in the image, so `auto` still picks live mode and finds an empty graph (only
+  `/rosout` and `/parameter_events`). Use it for bags, mounted with
+  `-v /path/to/bags:/bags:ro` (then ask about `/bags/run.mcap`), or for the demo robot with
+  `-e TOPICFORGE_MODE=mock`.
+
+The image is about 1 GB (ROS 2 Jazzy core plus Cyclone DDS).
 
 ## Prompts and instructions
 
-The server offers two MCP prompts, `diagnose-dds-bus` (nodes do not talk, a topic gets no data,
-a node crashed) and `inspect-ros2-robot` (what topics exist, what a bag contains), plus short
+The server offers three MCP prompts, `diagnose-dds-bus` (nodes do not talk, a topic gets no data,
+a node crashed), `inspect-ros2-robot` (what topics exist, what a bag contains) and `diagnose-nav2`
+(a Nav2 stack that does not start, aborts goals or does not move the robot), plus short
 server `instructions` sent in the `initialize` result (the read-only guarantee, which tool to
-call first, `contract_version`). Both prompts take optional arguments (`topic`, `symptom` or
-`bag_path`) that only focus the text; they run no tool by themselves.
+call first, `contract_version`). The prompts take optional arguments (`topic`, `symptom`,
+`bag_path` or `namespace`) that only focus the text; they run no tool by themselves.
 
 | Client | Prompts | Instructions |
 | --- | --- | --- |
@@ -325,7 +367,7 @@ when the question matches.
 
 ## Troubleshooting
 
-- Run the command by hand first: `uvx --from "topicforge==0.7.2" topicforge --version`.
+- Run the command by hand first: `uvx --from "topicforge==0.8.1" 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`.