topicforge 0.8.0__tar.gz → 0.8.1__tar.gz

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

@@ -5,6 +5,43 @@ 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).
 
+## [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
@@ -1864,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.8.0 → topicforge-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: topicforge
-Version: 0.8.0
+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
@@ -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=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJ0b3BpY2ZvcmdlPT0wLjguMCIsInRvcGljZm9yZ2UiXSwiZW52Ijp7IlRPUElDRk9SR0VfTU9ERSI6ImF1dG8iLCJUT1BJQ0ZPUkdFX0REU19CQUNLRU5EIjoiY3ljbG9uZSIsIlRPUElDRk9SR0VfRERTX0RPTUFJTl9JRCI6IjAifX0%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.0%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).
 
@@ -168,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.
 
@@ -207,7 +207,7 @@ When on, each tool call emits one event with exactly six fields:
 | `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.8.0"`       | 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.8.0 → topicforge-0.8.1}/README.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=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJ0b3BpY2ZvcmdlPT0wLjguMCIsInRvcGljZm9yZ2UiXSwiZW52Ijp7IlRPUElDRk9SR0VfTU9ERSI6ImF1dG8iLCJUT1BJQ0ZPUkdFX0REU19CQUNLRU5EIjoiY3ljbG9uZSIsIlRPUElDRk9SR0VfRERTX0RPTUFJTl9JRCI6IjAifX0%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.0%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).
 
@@ -107,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.
 
@@ -146,7 +146,7 @@ When on, each tool call emits one event with exactly six fields:
 | `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.8.0"`       | 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.8.0 → 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.8.0" 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.8.0`) 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.8.0"`, 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.8.0", "topicforge"],
+      "args": ["--from", "topicforge==0.8.1", "topicforge"],
       "env": {
         "TOPICFORGE_MODE": "auto",
         "TOPICFORGE_DDS_BACKEND": "cyclone",
@@ -95,7 +95,7 @@ claude plugin install topicforge@topicforge
 Or just the server:
 
 ```
-claude mcp add topicforge --env TOPICFORGE_MODE=auto --env TOPICFORGE_DDS_BACKEND=cyclone --env TOPICFORGE_DDS_DOMAIN_ID=0 -- uvx --from "topicforge==0.8.0" 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,9 +112,9 @@ the common JSON shape above and restart the app completely. On Windows, if
 
 The one-click links in this page and in the README are https redirects, because GitHub and PyPI strip `cursor://` and `vscode:` links. Only the raw schemes are documented by Cursor and VS Code; the https forms (`cursor.com/install-mcp`, `vscode.dev/redirect/mcp/install`) were observed to redirect correctly on 2026-10-06 but are not in the vendors' docs (unverified, last checked 2026-10-06). The raw links are given as a fallback.
 
-One click: [Add TopicForge to Cursor](https://cursor.com/install-mcp?name=topicforge&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJ0b3BpY2ZvcmdlPT0wLjguMCIsInRvcGljZm9yZ2UiXSwiZW52Ijp7IlRPUElDRk9SR0VfTU9ERSI6ImF1dG8iLCJUT1BJQ0ZPUkdFX0REU19CQUNLRU5EIjoiY3ljbG9uZSIsIlRPUElDRk9SR0VfRERTX0RPTUFJTl9JRCI6IjAifX0%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=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJ0b3BpY2ZvcmdlPT0wLjguMCIsInRvcGljZm9yZ2UiXSwiZW52Ijp7IlRPUElDRk9SR0VfTU9ERSI6ImF1dG8iLCJUT1BJQ0ZPUkdFX0REU19CQUNLRU5EIjoiY3ljbG9uZSIsIlRPUElDRk9SR0VfRERTX0RPTUFJTl9JRCI6IjAifX0%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).
@@ -125,9 +125,9 @@ The `plugin/` folder of this repository is also an [Agent Plugins](https://agent
 
 ## VS Code / GitHub Copilot
 
-One click: [Install in VS Code](https://vscode.dev/redirect/mcp/install?name=topicforge&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22--from%22%2C%22topicforge%3D%3D0.8.0%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.8.0%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.8.0", "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.8.0",
+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.8.0"
+      - "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.8.0", "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.8.0", "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.8.0", 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
@@ -297,11 +297,52 @@ 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
 
@@ -326,7 +367,7 @@ when the question matches.
 
 ## Troubleshooting
 
-- Run the command by hand first: `uvx --from "topicforge==0.8.0" 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`.

{topicforge-0.8.0 → topicforge-0.8.1}/docs/CONTRACT.md

@@ -1099,7 +1099,7 @@ New `TfReport` fields:
 
 | Field | Meaning |
 | --- | --- |
-| `urdf_source` | `robot_description` when a URDF was read and compared, else `none` (default) |
+| `urdf_source` | `robot_description` when a URDF was read and compared (from the topic, or since 0.8.1 from the parameter of the same name), else `none` (default) |
 | `urdf_link_count` | links in the URDF, `null` when none was read |
 | `declared_frames_missing` | URDF links with no TF frame, in URDF order |
 | `frames_not_in_urdf` | TF frames that are not a link, sorted. Informative: `map` and `odom` are legitimate |
@@ -1111,8 +1111,11 @@ missing link in `frames`; its `text` says that `robot_state_publisher` puts fixe
 `/tf_static` and the others on `/tf`, and names the links under a non-fixed joint, which have a
 frame only while `/joint_states` is published. With no TF frame captured at all nothing is
 compared (no finding, a note), so an empty capture does not read as "every link is missing".
-`/robot_description` is a topic only: a URDF held solely as a `robot_description` parameter is not
-read (`get_node_info` cuts long values) and gives `urdf_source` `none`; reading it is 0.8.1.
+In 0.8.0 `/robot_description` was a topic only. Since 0.8.1, when no node publishes the topic,
+`inspect_tf` reads the `robot_description` parameter of the first node named
+`robot_state_publisher` (any namespace) with one `ros2 param dump`, the same parameter read as
+`get_node_info`. `urdf_source` stays `robot_description` (a closed set does not grow between
+breaks, section 1.9) and `urdf_note` says the URDF came from that node's parameter.
 `docs/TOOLS.md` says that a robot needs `robot_state_publisher` for this.
 
 **`get_node_info(params_file=...)`.** `params_file` is a path on the machine the server runs on, to
@@ -1214,8 +1217,12 @@ its name; the Dust endpoint has none.
 `list_endpoints(topic="/scan")` call in `calls.json`): the `/scan` writer's `node_name` and
 `writer_nodes` are `/bench_robot`, the participant that hosts `/bench_robot` has an
 `endpoint_count` of at least 12, `ros_security_enabled` is `false` and `ros_security_note` is
-`null`. Written for the four Docker cells; not run in the session that added it. Not covered: a
-bus with SROS2 enabled (a SROS2 cell is planned for 0.8.1) and RTI.
+`null`. Written for the four Docker cells; not run in the session that added it. RTI is not
+covered. Since 0.8.1 the `sros2` job of `ros2-live.yml` (`run_bench.py --sros2`,
+`tests/integration/ros2/sros2_check.py`) covers a bus with SROS2 enabled: one node with the
+Enforce strategy, TopicForge without an identity sees its participant with `endpoint_count` 0 and
+the note above, and `health_check` reports the four fields with and without the variables. Run
+on 2026-10-23 on jazzy with Cyclone and Fast DDS: 4 of 4 checks passed in each cell.
 
 ### 9.17 The `diagnose-nav2` prompt and hidden topics (0.8.0)
 
@@ -1256,3 +1263,26 @@ latched status by hand, since an idle server publishes none) and must return one
 must be absent from `list_topics`; `41_bond` reads `/bond` (`bond/msg/Status`, id `bench_robot`,
 1 Hz) and every sample must carry the id. Comparator section `nav_primitives`. Written for the
 four Docker cells; not run in the session that added it, and Nav2 itself was never run.
+
+### 9.18 0.8.1: eval findings, URDF parameter, HTTP token
+
+Additive. `tools/list` grows by 467 bytes, to 97,315 (measured like `test_tool_listing_stays_small`).
+
+- `MismatchReport`, `NotMatchedPair` and `MatchedPair` gain `reader_node` and `writer_node`
+  (string or `null`), the `node_name` of each endpoint (section 9.16).
+- `detect_qos_mismatches` without `topic` leaves `ros_discovery_info` out (every ROS 2
+  participant reads and writes it with one QoS, about N x N matched pairs); `topic` can still
+  name it. Orphan topics that no near name explains are folded into one hint per side.
+- `TfFrame.stale` is also true for an edge with a steady rate (5 transforms or more) silent for
+  over ten of its periods, at least 1 s, even under `stale_after_s`. The finding text says which
+  limit applied.
+- `restarts_by_name` leaves out the name `/` (the ROS 2 enclave every node shares on Fast DDS);
+  those participants are counted in `restarts_note`, which points to `restarts_by_node`.
+- `min_log_level` accepts any case and `warning`; the schema keeps the lower-case enum.
+- `param_diff_summary` names the `same` and `live_only` parameters, up to ten each:
+  `1 same (frame_id), 1 live_only (use_sim_time)`.
+- A filtered `/rosout` read that received nothing says so in one note.
+- `inspect_tf` reads the URDF from the robot_state_publisher parameter when no node publishes
+  `/robot_description` (section 9.15).
+- HTTP transport: `TOPICFORGE_HTTP_TOKEN` and `--host` (SECURITY.md, docs/CLIENTS.md). No output
+  change.

{topicforge-0.8.0 → topicforge-0.8.1}/docs/TESTING.md

@@ -15,7 +15,7 @@ How to get a working ROS2 environment to point TopicForge at, and how to wire it
 ```bash
 python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\Activate.ps1
 pip install topicforge
-python -m topicforge --version                      # -> topicforge 0.8.0
+python -m topicforge --version                      # -> topicforge 0.8.1
 TOPICFORGE_MODE=mock python -m topicforge           # blocks on stdio; MCP clients spawn it
 ```
 
@@ -41,7 +41,7 @@ python3 -m venv ~/topicforge-venv && source ~/topicforge-venv/bin/activate
 pip install topicforge          # Ubuntu 22.04 ships Python 3.10, which is enough
 ```
 
-Then run live mode with three terminals. In the first, `ros2 run demo_nodes_cpp talker` publishes `/chatter` at about 1 Hz. In the second, `ros2 topic list` should show `/chatter`. In the third, source ROS2, activate the venv and run `TOPICFORGE_MODE=live python -m topicforge`. The startup line reads `topicforge 0.8.0 ready (mode=live, requested_mode=live, adapter=ros2_cli, telemetry=off)`; `mode=mock` means `ros2` was not found and the server fell back to fixtures.
+Then run live mode with three terminals. In the first, `ros2 run demo_nodes_cpp talker` publishes `/chatter` at about 1 Hz. In the second, `ros2 topic list` should show `/chatter`. In the third, source ROS2, activate the venv and run `TOPICFORGE_MODE=live python -m topicforge`. The startup line reads `topicforge 0.8.1 ready (mode=live, requested_mode=live, adapter=ros2_cli, telemetry=off)`; `mode=mock` means `ros2` was not found and the server fell back to fixtures.
 
 ## Linux native
 

{topicforge-0.8.0 → topicforge-0.8.1}/docs/TOOLS.md

@@ -125,7 +125,7 @@ ROS 2 graph only; on a DDS-only setup use `list_participants`. Describe one ROS
 | `mode_effective` | `"mock" \| "live"` | yes | `live` or `mock` (fixtures). |
 | `note` | `string \| null` | no | One sentence of context, or `None`. |
 | `param_diff` | `array \| null` | no | File against node: differences only. |
-| `param_diff_summary` | `string \| null` | no | Counts left out: same, live_only. |
+| `param_diff_summary` | `string \| null` | no | Left out of `param_diff`: same, live_only, with names. |
 | `param_diff_note` | `string \| null` | no | - |
 
 ## `get_topic_info`
@@ -564,9 +564,10 @@ Return temporal metrics (frequency, sequence gaps, latency percentiles) for a DD
 
 - `inspect_tf` compares the TF frames with the URDF on the `/robot_description`
   topic, which `robot_state_publisher` publishes (the default since ROS 2 Galactic).
-  A robot description held only as a node parameter is not read: `urdf_source` is
-  `none` and `urdf_note` says why. A link on a non-fixed joint has a TF frame only
-  while `/joint_states` is published.
+  Without that topic it reads the `robot_description` parameter of the node named
+  `robot_state_publisher` (`urdf_note` then names that node and parameter);
+  otherwise `urdf_source` is `none` and `urdf_note` says why. A link on a non-fixed
+  joint has a TF frame only while `/joint_states` is published.
 - `get_node_info(params_file=...)` reads a YAML file from the disk of the machine
   running TopicForge (`.yaml` or `.yml`, at most 1 MiB, read-only). The path is never
   sent to a node or to the `ros2` CLI, and nothing is written.

{topicforge-0.8.0 → topicforge-0.8.1}/plugin/README.md

@@ -4,7 +4,7 @@ TopicForge is a read-only MCP server for ROS 2 and DDS. This plugin bundles the
 
 ## What is included
 
-- MCP server `topicforge`, started with `uvx` from the `topicforge` package on PyPI (version pinned to 0.8.0). It exposes sixteen read-only tools: `health_check`, `list_topics`, `get_topic_info`, `list_nodes`, `get_node_info`, `sample_messages`, `analyze_bag`, `peek_bag_samples`, `list_participants`, `list_endpoints`, `detect_qos_mismatches`, `participant_events`, `peek_dds_samples`, `topic_metrics`, `inspect_tf`, `graph_diff`.
+- MCP server `topicforge`, started with `uvx` from the `topicforge` package on PyPI (version pinned to 0.8.1). It exposes sixteen read-only tools: `health_check`, `list_topics`, `get_topic_info`, `list_nodes`, `get_node_info`, `sample_messages`, `analyze_bag`, `peek_bag_samples`, `list_participants`, `list_endpoints`, `detect_qos_mismatches`, `participant_events`, `peek_dds_samples`, `topic_metrics`, `inspect_tf`, `graph_diff`.
 - Skill `diagnose-dds-bus`: what to call, and in which order, when nodes do not talk, a topic gets no data, or a node crashed or restarts.
 - Skill `inspect-ros2-robot`: listing topics, sampling messages and reading bags, including large arrays and simulation time.
 - Skill `diagnose-nav2`: the call order for a Nav2 stack that does not start, aborts goals or does not move the robot (lifecycle managers, bonds, goal status, TF, logs), and what TopicForge cannot see there.

{topicforge-0.8.0 → topicforge-0.8.1}/plugin/pyproject.toml

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

{topicforge-0.8.0 → topicforge-0.8.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "topicforge"
-version = "0.8.0"
+version = "0.8.1"
 description = "ROS Topic Inspector & Bag Analyzer MCP server for AI agents"
 readme = "README.md"
 requires-python = ">=3.10"

{topicforge-0.8.0 → topicforge-0.8.1}/src/topicforge/__init__.py

@@ -1,5 +1,5 @@
 """TopicForge: ROS Topic Inspector & Bag Analyzer MCP server."""
 
-__version__ = "0.8.0"
+__version__ = "0.8.1"
 
 __all__ = ["__version__"]

{topicforge-0.8.0 → topicforge-0.8.1}/src/topicforge/__main__.py

@@ -4,12 +4,20 @@ from __future__ import annotations
 
 import argparse
 import logging
+import os
 import sys
 
 from topicforge import __version__
 from topicforge.config import load_settings
 from topicforge.server import build_app
-from topicforge.server.http import DEFAULT_HTTP_PORT, LOOPBACK_HOST, serve_http
+from topicforge.server.http import (
+    DEFAULT_HTTP_PORT,
+    LOOPBACK_HOST,
+    TOKEN_ENV,
+    is_loopback,
+    serve_http,
+    validate_token,
+)
 
 
 def _build_arg_parser() -> argparse.ArgumentParser:
@@ -19,13 +27,15 @@ def _build_arg_parser() -> argparse.ArgumentParser:
             "ROS Topic Inspector & Bag Analyzer MCP server. "
             "Runs on stdio by default so MCP clients (Claude Desktop, Claude "
             "Code, etc.) can spawn it directly; --transport streamable-http "
-            "serves it on 127.0.0.1 only."
+            "serves it on 127.0.0.1 (another --host needs a bearer token)."
         ),
         epilog=(
             "Configuration is read from environment variables: "
             "TOPICFORGE_MODE (mock|live|auto, default auto), "
             "TOPICFORGE_LOG_LEVEL (DEBUG|INFO|WARNING|ERROR, default INFO), "
-            "TOPICFORGE_ROS2_BIN (default 'ros2')."
+            "TOPICFORGE_ROS2_BIN (default 'ros2'), "
+            f"{TOKEN_ENV} (bearer token for --transport streamable-http, at least 32 "
+            "characters; required for a --host other than loopback)."
         ),
     )
     parser.add_argument(
@@ -38,8 +48,16 @@ def _build_arg_parser() -> argparse.ArgumentParser:
         choices=("stdio", "streamable-http"),
         default="stdio",
         help=(
-            "stdio (default) or streamable-http, a local HTTP endpoint bound to "
-            f"{LOOPBACK_HOST} only (no authentication; reach it through an SSH tunnel)."
+            "stdio (default) or streamable-http, an HTTP endpoint bound to "
+            f"{LOOPBACK_HOST} by default (reach it through an SSH tunnel)."
+        ),
+    )
+    parser.add_argument(
+        "--host",
+        default=None,
+        help=(
+            f"Bind address for --transport streamable-http (default {LOOPBACK_HOST}). "
+            f"Anything but loopback requires {TOKEN_ENV}; the traffic is plain HTTP."
         ),
     )
     parser.add_argument(
@@ -55,11 +73,26 @@ def main(argv: list[str] | None = None) -> int:
     """Build the MCP app from environment settings and run it on stdio."""
     parser = _build_arg_parser()
     args = parser.parse_args(argv)
-    if args.port is not None and args.transport != "streamable-http":
-        parser.error("--port only applies to --transport streamable-http")
+    for flag, value in (("--port", args.port), ("--host", args.host)):
+        if value is not None and args.transport != "streamable-http":
+            parser.error(f"{flag} only applies to --transport streamable-http")
     port = DEFAULT_HTTP_PORT if args.port is None else args.port
     if not 1 <= port <= 65535:
         parser.error("--port must be in 1..65535")
+    host = LOOPBACK_HOST if args.host is None else args.host.strip()
+    token = os.environ.get(TOKEN_ENV) or None
+    if args.transport == "streamable-http":
+        if token is not None:
+            try:
+                validate_token(token)
+            except ValueError as exc:
+                parser.error(str(exc))
+        if not host:
+            parser.error("--host must not be empty")
+        if token is None and not is_loopback(host):
+            parser.error(
+                f"--host {host} needs {TOKEN_ENV}: without a token only loopback is served"
+            )
 
     try:
         settings = load_settings()
@@ -78,7 +111,7 @@ def main(argv: list[str] | None = None) -> int:
     app = build_app(settings)
     try:
         if args.transport == "streamable-http":
-            serve_http(app, port)
+            serve_http(app, port, host, token)
         else:
             app.run()
     except KeyboardInterrupt:

{topicforge-0.8.0 → topicforge-0.8.1}/src/topicforge/adapters/common/log_filter.py

@@ -35,13 +35,15 @@ def is_log_type(message_type: str) -> bool:
 def level_threshold(min_log_level: str | None) -> int | None:
     """Numeric threshold of a level name; `None` for no level filter.
 
-    Raises `AdapterError` for a name outside `debug`, `info`, `warn`, `error`, `fatal`.
+    Case is ignored and `warning` means `warn`. Raises `AdapterError` for any other name
+    outside `debug`, `info`, `warn`, `error`, `fatal`.
     """
     if min_log_level is None:
         return None
     try:
-        return LOG_LEVELS[min_log_level]
-    except (KeyError, TypeError):
+        name = min_log_level.strip().lower()
+        return LOG_LEVELS["warn" if name == "warning" else name]
+    except (KeyError, TypeError, AttributeError):
         raise AdapterError(
             f"min_log_level must be one of {', '.join(LOG_LEVELS)}, got {min_log_level!r}"
         ) from None