topicforge 0.6.0__tar.gz → 0.6.2__tar.gz

{topicforge-0.6.0 → topicforge-0.6.2}/CHANGELOG.md

@@ -5,6 +5,59 @@ 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.6.2] - 2026-10-06
+
+### Added
+
+- [docs/CLIENTS.md](docs/CLIENTS.md): ready-to-paste local stdio configs for Claude
+  Code, Claude Desktop, Cursor, VS Code / Copilot, Windsurf / Devin, Cline, Roo Code,
+  Continue, Zed, JetBrains, Codex CLI, Gemini CLI, Goose, LM Studio, Amazon Q / Kiro
+  and Warp, with one-click install links for Cursor and VS Code, and a note on why
+  ChatGPT web and a hosted endpoint are out of scope. Linked from the README.
+- `gemini-extension.json` and `GEMINI.md`: install in Gemini CLI with
+  `gemini extensions install https://github.com/yaniswav/TopicForge`.
+- `mcpb/`: an MCP Bundle (`uv` server type, no vendored dependencies) for one-click
+  Claude Desktop install. The release workflow packs it and attaches it to the GitHub
+  release.
+- `publish.yml` publishes `server.json` to the official MCP Registry after the PyPI
+  publish succeeds (pinned, checksum-verified `mcp-publisher`, GitHub OIDC), so the
+  registry no longer lags behind PyPI.
+- `tests/test_version_consistency.py`: fails when the package, `server.json`, plugin,
+  Gemini extension, MCP Bundle and the pins in `docs/CLIENTS.md` disagree.
+
+## [0.6.1] - 2026-10-06
+
+### Added
+
+- A Claude plugin bundle in `plugin/`: the TopicForge MCP server (started with
+  `uvx`, version pinned) and two skills, `diagnose-dds-bus` and
+  `inspect-ros2-robot`. Install with `claude plugin marketplace add
+  yaniswav/TopicForge`.
+- [docs/VALIDATION.md](docs/VALIDATION.md): the OmniSim team's external validation
+  against a simulated robot's ground truth, published as approved by them.
+- `MessageSample.recorded_ns`: the bag record time of a `peek_bag_samples` sample.
+- `MessageSample.stamp_source` value `recorded`: `timestamp_ns` is the bag record
+  time because the message has no top-level header.
+- `HealthReport.sim_clock_published` (live ROS 2 only, else null): whether `/clock`
+  has a publisher, a hint that nodes may run on simulated time.
+
+### Changed
+
+- `peek_bag_samples` `timestamp_ns` is now `header.stamp` when the message has a
+  top-level header (`stamp_source` `header`), else the bag record time (`stamp_source`
+  `recorded`). It used to be the bag record time for every message, with
+  `stamp_source` null. The tool description says it returns the first `count`
+  messages, not the last.
+- CI: `actions/checkout` v7, `actions/setup-python` v7, `actions/cache` v6. Jobs
+  that run tests or the demos use `ubuntu-24.04` instead of `ubuntu-latest`.
+
+### Fixed
+
+- `peek_bag_samples` payloads no longer carry `__msgtype__` in every nested object
+  nor a top-level `_msgtype`; the message type stays at the sample level.
+
 ## [0.6.0] - 2026-10-05
 
 `sample_messages` (live) rewritten after the OmniSim team's report (count
@@ -1263,7 +1316,9 @@ Initial MVP release of TopicForge: ROS Topic Inspector & Bag Analyzer MCP server
 - The write path (publishing, commanding robots) is intentionally out of scope for the MVP.
 - `analyze_bag` in live mode parses `ros2 bag info` text output; deeper anomaly detection remains mock-only for now.
 
-[Unreleased]: https://github.com/yaniswav/TopicForge/compare/v0.6.0...HEAD
+[Unreleased]: https://github.com/yaniswav/TopicForge/compare/v0.6.2...HEAD
+[0.6.2]: https://github.com/yaniswav/TopicForge/compare/v0.6.1...v0.6.2
+[0.6.1]: https://github.com/yaniswav/TopicForge/compare/v0.6.0...v0.6.1
 [0.6.0]: https://github.com/yaniswav/TopicForge/compare/v0.5.6...v0.6.0
 [0.5.6]: https://github.com/yaniswav/TopicForge/compare/v0.5.5...v0.5.6
 [0.5.5]: https://github.com/yaniswav/TopicForge/compare/v0.5.4...v0.5.5

{topicforge-0.6.0 → topicforge-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: topicforge
-Version: 0.6.0
+Version: 0.6.2
 Summary: ROS Topic Inspector & Bag Analyzer MCP server for AI agents
 Project-URL: Homepage, https://github.com/yaniswav/TopicForge
 Project-URL: Repository, https://github.com/yaniswav/TopicForge
@@ -98,7 +98,11 @@ 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`. 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).
+Then ask it to list the topics or to analyze `/tmp/demo.mcap`. For Claude Code: `claude mcp add topicforge -- topicforge`.
+
+**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=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJ0b3BpY2ZvcmdlW2Rkc109PTAuNi4yIiwidG9waWNmb3JnZSJdLCJlbnYiOnsiVE9QSUNGT1JHRV9NT0RFIjoiYXV0byIsIlRPUElDRk9SR0VfRERTX0JBQ0tFTkQiOiJjeWNsb25lIiwiVE9QSUNGT1JHRV9ERFNfRE9NQUlOX0lEIjoiMCJ9fQ%3D%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%5Bdds%5D%3D%3D0.6.2%22%2C%22topicforge%22%5D%2C%22env%22%3A%7B%22TOPICFORGE_MODE%22%3A%22auto%22%2C%22TOPICFORGE_DDS_BACKEND%22%3A%22cyclone%22%2C%22TOPICFORGE_DDS_DOMAIN_ID%22%3A%220%22%7D%7D).
+
+Setup for a real ROS2 environment (WSL2, Linux, Docker, native Windows) is in [`docs/TESTING.md`](docs/TESTING.md); recurring monitoring prompts and the privacy contract are in [`docs/TUTORIEL.md`](docs/TUTORIEL.md).
 
 ## Tools
 
@@ -158,6 +162,8 @@ Samples with comments are in [`.env.example`](.env.example). Any invalid value s
 
 ## Limitations
 
+External validation against a simulated robot's ground truth: [docs/VALIDATION.md](docs/VALIDATION.md).
+
 - DDS validation is partial. The Cyclone adapter has run against a real bus, with Cyclone and Dust DDS participants, on Windows and in CI on Ubuntu and Windows (`.github/workflows/demo.yml`). The Fast DDS adapter has never run against a bus, and no RTI, OpenDDS, CoreDX or OpenSplice participant has been observed by this project. The multi-vendor claim rests on the RTPS protocol guarantee, not on a recorded cross-vendor run.
 - User-topic payloads are not decoded. `peek_dds_samples` on a user topic returns count 0 and a note that the topic is announced on the bus; no traffic is read. `topic_metrics` therefore has data only for the builtin discovery topics and says so in its `status`. It is a discovery-layer probe, not a publish-rate monitor.
 - Liveliness at runtime is not observed. A writer that is alive but silent (a hung process whose lease is still renewed) looks healthy, because TopicForge reads discovery, not data. An opt-in data probe is planned. A crash and a clean leave cannot be told apart, and `lost_ns` is an upper bound of the death.
@@ -166,7 +172,7 @@ Samples with comments are in [`.env.example`](.env.example). Any invalid value s
 - DDS Security is not handled. A participant without credentials sees an empty secure bus. `detect_qos_mismatches` checks Partition, type name, Reliability, Durability, Deadline, Liveliness, LatencyBudget, Ownership (kind), DestinationOrder and DataRepresentation (History as a risk); Presentation, XTypes assignability and runtime behavior are not checked, and the result lists them in `policies_unchecked`. It returns a `MismatchScan` envelope: read `reports` for the mismatches.
 - Fast DDS serves no `list_endpoints`.
 - `sample_messages` (live) streams `ros2 topic echo` until `count` messages arrive or `timeout_s` (1..45, default 10, for the whole call) runs out, and returns what arrived with a `note` (`N of M messages within T s`, saying whether a publisher exists). QoS is matched to the publishers, so latched topics work. The payload has nested named fields (`payload.header.stamp.sec`); `timestamp_ns` is `header.stamp` (the publisher's clock, sim time on a simulation) or 0 for headerless types, with `stamp_source` and `received_ns` (wall clock when the CLI printed it). Arrays are cut at 128 elements by default; `max_array_length` (1..65536, or null for no cut) and `arrays_summary_only` change that, and a cut is listed under `_truncated_fields`. `nan` and `inf` come back as strings. `count` above 50 is capped with a note.
-- `analyze_bag` (live) parses `ros2 bag info` text for the totals and counts; anomaly detection is mock-only. Per-topic times, rates (`(n - 1) / span`) and `latched` are added when the bag can be read locally (`.db3` with the standard library, `.mcap` with `rosbags`), else rates fall back to count / bag duration (`frequency_basis`). `peek_bag_samples` reads the file itself, through `rosbags`, and is served only by the ROS2 CLI adapter or the mock; bags that embed no message definitions (Humble `.db3`) are decoded with the Humble definitions, or the distro the bag records, and `note` says so. Without `ros2`, bag tools return fixtures: check `health_check` for `mode: "mock"` before trusting bag output.
+- `analyze_bag` (live) parses `ros2 bag info` text for the totals and counts; anomaly detection is mock-only. Per-topic times, rates (`(n - 1) / span`) and `latched` are added when the bag can be read locally (`.db3` with the standard library, `.mcap` with `rosbags`), else rates fall back to count / bag duration (`frequency_basis`). `peek_bag_samples` reads the file itself, through `rosbags`, returns the first `count` messages in recording order (not the last), and is served only by the ROS2 CLI adapter or the mock; its `timestamp_ns` is the message's `header.stamp` (`stamp_source` `header`) or, without a top-level header, the bag record time (`stamp_source` `recorded`), and `recorded_ns` is always the bag record time; bags that embed no message definitions (Humble `.db3`) are decoded with the Humble definitions, or the distro the bag records, and `note` says so. Without `ros2`, bag tools return fixtures: check `health_check` for `mode: "mock"` before trusting bag output. `health_check` also reports `sim_clock_published` (live only): true when `/clock` has a publisher, a hint that header stamps may be simulation time.
 - Synchronous handlers: the tools run on the MCP event loop; on Windows a hung `ros2` launcher can block the server.
 - No streaming or push subscriptions: tools are strictly request/response.
 
@@ -189,7 +195,7 @@ When on, each tool call emits one event with exactly six fields:
 | `tool_name`  | `"list_topics"` | One of the twelve tools, never argument values              |
 | `latency_ms` | `12.34`         | Handler wall-clock duration, 2 decimals                     |
 | `mode`       | `"mock"`        | Mode of the adapter actually serving: `mock` or `live`      |
-| `version`    | `"0.6.0"`       | TopicForge server version                                   |
+| `version`    | `"0.6.2"`       | TopicForge server version                                   |
 | `session_id` | `"a1b2c3..."`   | Random UUID per process, never persisted                    |
 | `success`    | `true`          | Whether the handler returned or raised                      |
 

{topicforge-0.6.0 → topicforge-0.6.2}/README.md

@@ -38,7 +38,11 @@ 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`. 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).
+Then ask it to list the topics or to analyze `/tmp/demo.mcap`. For Claude Code: `claude mcp add topicforge -- topicforge`.
+
+**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=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJ0b3BpY2ZvcmdlW2Rkc109PTAuNi4yIiwidG9waWNmb3JnZSJdLCJlbnYiOnsiVE9QSUNGT1JHRV9NT0RFIjoiYXV0byIsIlRPUElDRk9SR0VfRERTX0JBQ0tFTkQiOiJjeWNsb25lIiwiVE9QSUNGT1JHRV9ERFNfRE9NQUlOX0lEIjoiMCJ9fQ%3D%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%5Bdds%5D%3D%3D0.6.2%22%2C%22topicforge%22%5D%2C%22env%22%3A%7B%22TOPICFORGE_MODE%22%3A%22auto%22%2C%22TOPICFORGE_DDS_BACKEND%22%3A%22cyclone%22%2C%22TOPICFORGE_DDS_DOMAIN_ID%22%3A%220%22%7D%7D).
+
+Setup for a real ROS2 environment (WSL2, Linux, Docker, native Windows) is in [`docs/TESTING.md`](docs/TESTING.md); recurring monitoring prompts and the privacy contract are in [`docs/TUTORIEL.md`](docs/TUTORIEL.md).
 
 ## Tools
 
@@ -98,6 +102,8 @@ Samples with comments are in [`.env.example`](.env.example). Any invalid value s
 
 ## Limitations
 
+External validation against a simulated robot's ground truth: [docs/VALIDATION.md](docs/VALIDATION.md).
+
 - DDS validation is partial. The Cyclone adapter has run against a real bus, with Cyclone and Dust DDS participants, on Windows and in CI on Ubuntu and Windows (`.github/workflows/demo.yml`). The Fast DDS adapter has never run against a bus, and no RTI, OpenDDS, CoreDX or OpenSplice participant has been observed by this project. The multi-vendor claim rests on the RTPS protocol guarantee, not on a recorded cross-vendor run.
 - User-topic payloads are not decoded. `peek_dds_samples` on a user topic returns count 0 and a note that the topic is announced on the bus; no traffic is read. `topic_metrics` therefore has data only for the builtin discovery topics and says so in its `status`. It is a discovery-layer probe, not a publish-rate monitor.
 - Liveliness at runtime is not observed. A writer that is alive but silent (a hung process whose lease is still renewed) looks healthy, because TopicForge reads discovery, not data. An opt-in data probe is planned. A crash and a clean leave cannot be told apart, and `lost_ns` is an upper bound of the death.
@@ -106,7 +112,7 @@ Samples with comments are in [`.env.example`](.env.example). Any invalid value s
 - DDS Security is not handled. A participant without credentials sees an empty secure bus. `detect_qos_mismatches` checks Partition, type name, Reliability, Durability, Deadline, Liveliness, LatencyBudget, Ownership (kind), DestinationOrder and DataRepresentation (History as a risk); Presentation, XTypes assignability and runtime behavior are not checked, and the result lists them in `policies_unchecked`. It returns a `MismatchScan` envelope: read `reports` for the mismatches.
 - Fast DDS serves no `list_endpoints`.
 - `sample_messages` (live) streams `ros2 topic echo` until `count` messages arrive or `timeout_s` (1..45, default 10, for the whole call) runs out, and returns what arrived with a `note` (`N of M messages within T s`, saying whether a publisher exists). QoS is matched to the publishers, so latched topics work. The payload has nested named fields (`payload.header.stamp.sec`); `timestamp_ns` is `header.stamp` (the publisher's clock, sim time on a simulation) or 0 for headerless types, with `stamp_source` and `received_ns` (wall clock when the CLI printed it). Arrays are cut at 128 elements by default; `max_array_length` (1..65536, or null for no cut) and `arrays_summary_only` change that, and a cut is listed under `_truncated_fields`. `nan` and `inf` come back as strings. `count` above 50 is capped with a note.
-- `analyze_bag` (live) parses `ros2 bag info` text for the totals and counts; anomaly detection is mock-only. Per-topic times, rates (`(n - 1) / span`) and `latched` are added when the bag can be read locally (`.db3` with the standard library, `.mcap` with `rosbags`), else rates fall back to count / bag duration (`frequency_basis`). `peek_bag_samples` reads the file itself, through `rosbags`, and is served only by the ROS2 CLI adapter or the mock; bags that embed no message definitions (Humble `.db3`) are decoded with the Humble definitions, or the distro the bag records, and `note` says so. Without `ros2`, bag tools return fixtures: check `health_check` for `mode: "mock"` before trusting bag output.
+- `analyze_bag` (live) parses `ros2 bag info` text for the totals and counts; anomaly detection is mock-only. Per-topic times, rates (`(n - 1) / span`) and `latched` are added when the bag can be read locally (`.db3` with the standard library, `.mcap` with `rosbags`), else rates fall back to count / bag duration (`frequency_basis`). `peek_bag_samples` reads the file itself, through `rosbags`, returns the first `count` messages in recording order (not the last), and is served only by the ROS2 CLI adapter or the mock; its `timestamp_ns` is the message's `header.stamp` (`stamp_source` `header`) or, without a top-level header, the bag record time (`stamp_source` `recorded`), and `recorded_ns` is always the bag record time; bags that embed no message definitions (Humble `.db3`) are decoded with the Humble definitions, or the distro the bag records, and `note` says so. Without `ros2`, bag tools return fixtures: check `health_check` for `mode: "mock"` before trusting bag output. `health_check` also reports `sim_clock_published` (live only): true when `/clock` has a publisher, a hint that header stamps may be simulation time.
 - Synchronous handlers: the tools run on the MCP event loop; on Windows a hung `ros2` launcher can block the server.
 - No streaming or push subscriptions: tools are strictly request/response.
 
@@ -129,7 +135,7 @@ When on, each tool call emits one event with exactly six fields:
 | `tool_name`  | `"list_topics"` | One of the twelve tools, never argument values              |
 | `latency_ms` | `12.34`         | Handler wall-clock duration, 2 decimals                     |
 | `mode`       | `"mock"`        | Mode of the adapter actually serving: `mock` or `live`      |
-| `version`    | `"0.6.0"`       | TopicForge server version                                   |
+| `version`    | `"0.6.2"`       | TopicForge server version                                   |
 | `session_id` | `"a1b2c3..."`   | Random UUID per process, never persisted                    |
 | `success`    | `true`          | Whether the handler returned or raised                      |
 

topicforge-0.6.2/docs/CLIENTS.md

@@ -0,0 +1,280 @@
+# Using TopicForge from your MCP client
+
+Last checked 2026-10-06.
+
+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[dds]==0.6.2" topicforge
+```
+
+and the same three environment variables:
+
+| Variable | Value | Meaning |
+| --- | --- | --- |
+| `TOPICFORGE_MODE` | `auto` | Use ROS 2 if it is on PATH, else fixtures. |
+| `TOPICFORGE_DDS_BACKEND` | `cyclone` | Join the DDS bus as a read-only participant (the `[dds]` extra provides the binding). Use `mock` for a demo with no robot. |
+| `TOPICFORGE_DDS_DOMAIN_ID` | `0` | The one DDS domain to observe (0-232). Fixed at startup: restart the server to change it. |
+
+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.6.2`) is moved on every release together with the other
+version strings; a test keeps them in sync.
+
+## Before you start
+
+- **uv.** `uvx` ships with [uv](https://docs.astral.sh/uv/getting-started/installation/).
+  Install it once, then check `uvx --version` in a new terminal.
+- **Desktop apps do not inherit your shell PATH.** On Windows especially, an app
+  started from the Start menu may not see `uvx`. If a client reports "command not
+  found", put the absolute path in `command` (find it with `where uvx` on Windows
+  or `which uvx` elsewhere, for example `C:/Users/you/.local/bin/uvx.exe`;
+  forward slashes are fine in JSON).
+- **First start is slow.** `uvx` downloads the package and the Cyclone DDS binding
+  the first time. Clients with a short startup timeout may need a retry or a
+  larger timeout (noted per client below).
+- **If resolution fails on a very new Python** (the Cyclone binding ships wheels for Python 3.10 to 3.13 only), add `"--python", "3.12"` before
+  `"--from"` in the args.
+- **pip alternative.** `pip install "topicforge[dds]==0.6.2"`, then use
+  `"command": "topicforge"` (or `"command": "python", "args": ["-m", "topicforge"]`)
+  with no `args` for uvx. Use the absolute path of the binary if the client does
+  not see your venv.
+- **No robot at hand?** Set `TOPICFORGE_DDS_BACKEND` to `mock` to try the tools
+  against deterministic fixtures.
+
+## What cannot work: ChatGPT and hosted endpoints
+
+ChatGPT on the web and in the desktop app cannot run local stdio MCP servers; it
+only talks to remote MCP endpoints. Use Codex (below), which runs local stdio
+servers, or any other client on this page.
+
+A hosted TopicForge endpoint is out of scope on purpose. TopicForge has to sit on
+the same network as the DDS participants it observes, and exposing a robot bus to
+the internet would contradict the read-only safety promise the product is built
+on.
+
+## The common JSON shape
+
+Most clients read an `mcpServers` object like this one. The per-client sections
+say where the file lives and what differs.
+
+```json
+{
+  "mcpServers": {
+    "topicforge": {
+      "command": "uvx",
+      "args": ["--from", "topicforge[dds]==0.6.2", "topicforge"],
+      "env": {
+        "TOPICFORGE_MODE": "auto",
+        "TOPICFORGE_DDS_BACKEND": "cyclone",
+        "TOPICFORGE_DDS_DOMAIN_ID": "0"
+      }
+    }
+  }
+}
+```
+
+## Claude Code
+
+Plugin (server plus two skills, asks for backend and domain at install):
+
+```
+claude plugin marketplace add yaniswav/TopicForge
+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[dds]==0.6.2" topicforge
+```
+
+## Claude Desktop
+
+From 0.6.2: download `topicforge-<version>.mcpb` from the latest GitHub release and double-click it. Claude Desktop asks for the DDS backend and domain id and manages Python and dependencies itself through uv.
+
+Or edit the config file by hand: `claude_desktop_config.json` (Settings > Developer > Edit Config):
+`%APPDATA%\Claude\claude_desktop_config.json` on Windows,
+`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS. Paste
+the common JSON shape above and restart the app completely. On Windows, if
+`uvx` is not found, use its absolute path as `command`.
+
+## Cursor
+
+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=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJ0b3BpY2ZvcmdlW2Rkc109PTAuNi4yIiwidG9waWNmb3JnZSJdLCJlbnYiOnsiVE9QSUNGT1JHRV9NT0RFIjoiYXV0byIsIlRPUElDRk9SR0VfRERTX0JBQ0tFTkQiOiJjeWNsb25lIiwiVE9QSUNGT1JHRV9ERFNfRE9NQUlOX0lEIjoiMCJ9fQ%3D%3D)
+
+If that page does not open Cursor, use the raw deeplink: `cursor://anysphere.cursor-deeplink/mcp/install?name=topicforge&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJ0b3BpY2ZvcmdlW2Rkc109PTAuNi4yIiwidG9waWNmb3JnZSJdLCJlbnYiOnsiVE9QSUNGT1JHRV9NT0RFIjoiYXV0byIsIlRPUElDRk9SR0VfRERTX0JBQ0tFTkQiOiJjeWNsb25lIiwiVE9QSUNGT1JHRV9ERFNfRE9NQUlOX0lEIjoiMCJ9fQ==`
+
+Or paste the common JSON shape into `~/.cursor/mcp.json` (all projects) or
+`.cursor/mcp.json` (one project).
+
+## 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%5Bdds%5D%3D%3D0.6.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%5Bdds%5D%3D%3D0.6.2%22%2C%22topicforge%22%5D%2C%22env%22%3A%7B%22TOPICFORGE_MODE%22%3A%22auto%22%2C%22TOPICFORGE_DDS_BACKEND%22%3A%22cyclone%22%2C%22TOPICFORGE_DDS_DOMAIN_ID%22%3A%220%22%7D%7D`
+
+Or put this in `.vscode/mcp.json` (the key is `servers`, not `mcpServers`), or run
+"MCP: Add Server" from the Command Palette:
+
+```json
+{
+  "servers": {
+    "topicforge": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["--from", "topicforge[dds]==0.6.2", "topicforge"],
+      "env": {
+        "TOPICFORGE_MODE": "auto",
+        "TOPICFORGE_DDS_BACKEND": "cyclone",
+        "TOPICFORGE_DDS_DOMAIN_ID": "0"
+      }
+    }
+  }
+}
+```
+
+## Windsurf / Devin (Cascade)
+
+Windsurf's docs now redirect to Devin's (unverified, last checked 2026-10-06). Edit `%APPDATA%\devin\mcp_config.json`
+(Windows) or `~/.config/devin/mcp_config.json` (macOS, Linux) and paste the common
+JSON shape. Older installs may still use `~/.codeium/windsurf/mcp_config.json` (unverified, last checked 2026-10-06).
+
+## Cline
+
+Open the MCP Servers icon in the Cline panel, then Configure, then "Configure MCP
+Servers", and paste the common JSON shape (the file is
+`~/.cline/data/settings/cline_mcp_settings.json` per docs.cline.bot on 2026-10-06; older VS Code installs kept it elsewhere, unverified). Optional fields such as
+`"disabled": false` and `"autoApprove": []` are accepted.
+
+## Roo Code
+
+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[dds]==0.6.2",
+"topicforge"]` if it fails to start.
+
+## Continue
+
+Create `.continue/mcpServers/topicforge.yaml` (MCP works in agent mode only):
+
+```yaml
+name: TopicForge (ROS 2 / DDS)
+version: 0.0.1
+schema: v1
+mcpServers:
+  - name: topicforge
+    type: stdio
+    command: uvx
+    args:
+      - "--from"
+      - "topicforge[dds]==0.6.2"
+      - "topicforge"
+    env:
+      TOPICFORGE_MODE: auto
+      TOPICFORGE_DDS_BACKEND: cyclone
+      TOPICFORGE_DDS_DOMAIN_ID: "0"
+```
+
+## Zed
+
+In `settings.json`, under `context_servers`:
+
+```json
+{
+  "context_servers": {
+    "topicforge": {
+      "command": "uvx",
+      "args": ["--from", "topicforge[dds]==0.6.2", "topicforge"],
+      "env": {
+        "TOPICFORGE_MODE": "auto",
+        "TOPICFORGE_DDS_BACKEND": "cyclone",
+        "TOPICFORGE_DDS_DOMAIN_ID": "0"
+      }
+    }
+  }
+}
+```
+
+## JetBrains AI Assistant
+
+Settings > Tools > AI Assistant > Model Context Protocol (MCP) > Add, then paste the
+common JSON shape. You can also use "Import from Claude" if you already set it up
+there.
+
+## OpenAI Codex CLI
+
+Codex runs local stdio servers (CLI, IDE extension and desktop app share
+`~/.codex/config.toml`). The default startup timeout is 10 s, which a first `uvx`
+run with the dds extra can exceed, so set it to 60 s:
+
+```toml
+[mcp_servers.topicforge]
+command = "uvx"
+args = ["--from", "topicforge[dds]==0.6.2", "topicforge"]
+startup_timeout_sec = 60
+
+[mcp_servers.topicforge.env]
+TOPICFORGE_MODE = "auto"
+TOPICFORGE_DDS_BACKEND = "cyclone"
+TOPICFORGE_DDS_DOMAIN_ID = "0"
+```
+
+## Gemini CLI
+
+As an extension (reads `gemini-extension.json` from this repository):
+
+```
+gemini extensions install https://github.com/yaniswav/TopicForge
+```
+
+Or paste the common JSON shape into `~/.gemini/settings.json` (or
+`.gemini/settings.json` in a project). Add `"timeout": 60000` (milliseconds) for
+the slow first start, and do not set `"trust": true`.
+
+## Goose
+
+In `~/.config/goose/config.yaml` (macOS, Linux; the Windows location is unverified, last checked 2026-10-06), or via the extensions screen:
+
+```yaml
+extensions:
+  topicforge:
+    name: TopicForge (ROS 2 / DDS)
+    type: stdio
+    cmd: uvx
+    args: [--from, "topicforge[dds]==0.6.2", topicforge]
+    enabled: true
+    envs: { "TOPICFORGE_MODE": "auto", "TOPICFORGE_DDS_BACKEND": "cyclone", "TOPICFORGE_DDS_DOMAIN_ID": "0" }
+    timeout: 300
+```
+
+## LM Studio
+
+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 twelve tools.
+
+## Amazon Q Developer / Kiro
+
+Kiro: `~/.kiro/settings/mcp.json` (user) or `.kiro/settings/mcp.json` (workspace,
+takes precedence); paste the common JSON shape. Amazon Q Developer CLI uses the
+same shape in `~/.aws/amazonq/mcp.json` (the Amazon Q path and the move to Kiro CLI are unverified, last checked 2026-10-06).
+
+## Warp
+
+Settings > MCP > "+ Add", then paste the common JSON shape (unverified, last checked 2026-10-06: the Warp docs page could not be fetched).
+
+## Troubleshooting
+
+- Run the command by hand first: `uvx --from "topicforge[dds]==0.6.2" topicforge --version`.
+- Server starts but sees no DDS participants: check the domain id, and that the
+  client machine is on the same network as the robot (DDS discovery uses
+  multicast UDP). Ask the assistant to call `health_check`.
+- More in [TROUBLESHOOTING.md](TROUBLESHOOTING.md) and [TESTING.md](TESTING.md).

{topicforge-0.6.0 → topicforge-0.6.2}/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.6.0
+python -m topicforge --version                      # -> topicforge 0.6.2
 TOPICFORGE_MODE=mock python -m topicforge           # blocks on stdio; MCP clients spawn it
 ```
 
@@ -41,7 +41,7 @@ python3 -m venv ~/topicforge-venv && source ~/topicforge-venv/bin/activate
 pip install topicforge          # Ubuntu 22.04 ships Python 3.10, which is enough
 ```
 
-Then run live mode with three terminals. In the first, `ros2 run demo_nodes_cpp talker` publishes `/chatter` at about 1 Hz. In the second, `ros2 topic list` should show `/chatter`. In the third, source ROS2, activate the venv and run `TOPICFORGE_MODE=live python -m topicforge`. The startup line reads `topicforge 0.6.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.6.2 ready (mode=live, requested_mode=live, adapter=ros2_cli, telemetry=off)`; `mode=mock` means `ros2` was not found and the server fell back to fixtures.
 
 ## Linux native
 
@@ -102,4 +102,4 @@ TopicForge speaks MCP over stdio; any compliant client can spawn it with a comma
 }
 ```
 
-That is the Claude Desktop shape (`claude_desktop_config.json`); restart the app and the twelve tools appear under the hammer icon. For Claude Code run `claude mcp add topicforge -- topicforge`. Cursor, Continue and Cline accept the same stdio config. If the `topicforge` script is not on PATH, use `"command": "python", "args": ["-m", "topicforge"]`, or the absolute path of the binary inside your venv: desktop clients do not inherit your shell's PATH or venv activation.
+That is the Claude Desktop shape (`claude_desktop_config.json`); restart the app and the twelve tools appear under the hammer icon. For Claude Code run `claude mcp add topicforge -- topicforge`. Cursor, Continue and Cline accept the same stdio config; ready-to-paste configs for every major client are in [`CLIENTS.md`](CLIENTS.md). If the `topicforge` script is not on PATH, use `"command": "python", "args": ["-m", "topicforge"]`, or the absolute path of the binary inside your venv: desktop clients do not inherit your shell's PATH or venv activation.

topicforge-0.6.2/docs/VALIDATION.md

@@ -0,0 +1,15 @@
+# External validation
+
+## OmniSim (October 2026)
+
+The OmniSim team ran TopicForge against a simulated robot and compared its answers with the simulator's ground truth.
+
+Setup: [OmniSim v9.1.3](https://github.com/omnilink-tech/omnisim/releases/tag/v9.1.3), a simulated Clearpath Husky with a 541-beam SICK LMS111 lidar in a room with walls at known positions, robot stationary. ROS 2 Humble on Ubuntu 22.04 (WSL2), Fast DDS. TopicForge 0.5.3 in live mode for the ROS 2 tools, and 0.5.5 with the Cyclone backend for the DDS tools.
+
+What matched:
+- Every lidar scan TopicForge sampled was bit-identical to the simulator's raw data on the beams it delivered.
+- `list_topics` and `get_topic_info` returned the same names, types and publisher/subscriber counts as the `ros2` CLI.
+- `analyze_bag` returned the same duration and message counts as `ros2 bag info` and an independent read of the bag.
+- With the Cyclone backend, TopicForge saw all seven Fast DDS participants of the ROS 2 graph without extra configuration, and reported participants leaving within about 10 ms of the actual time.
+
+What it found: seven discrepancies on TopicForge's side, including lidar arrays cut at 128 values, one message per `sample_messages` call, zero timestamps on simulated time, and Humble bags that `peek_bag_samples` could not decode. All seven are addressed in 0.5.6 and 0.6.0 (full arrays through a `max_array_length` option) and covered by a ROS 2 Humble/Jazzy test bench; the OmniSim run itself has not been repeated on these versions yet. The bag recorded during the run is part of TopicForge's test fixtures (`tests/fixtures/bags/omnisim_humble/`).

topicforge-0.6.2/plugin/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yanis ETHVIGNOT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

topicforge-0.6.2/plugin/README.md

@@ -0,0 +1,60 @@
+# TopicForge plugin for Claude
+
+TopicForge is a read-only MCP server for ROS 2 and DDS. This plugin bundles the server with two short skills so Claude can inspect a robot stack and diagnose a DDS bus. It cannot publish, command a robot, or change QoS: the server has no write path.
+
+## What is included
+
+- MCP server `topicforge`, started with `uvx` from the `topicforge` package on PyPI (version pinned to 0.6.2). It exposes twelve read-only tools: `health_check`, `list_topics`, `get_topic_info`, `sample_messages`, `analyze_bag`, `peek_bag_samples`, `list_participants`, `list_endpoints`, `detect_qos_mismatches`, `participant_events`, `peek_dds_samples`, `topic_metrics`.
+- 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.
+
+## Requirements
+
+- [`uv`](https://docs.astral.sh/uv/) on PATH, which provides `uvx`. The first start downloads the package and the Cyclone DDS binding, so it can take a little while.
+- A local MCP server: it runs on your machine, in Claude Code and in Cowork sessions that run on your computer. It does not run in claude.ai chat.
+- ROS 2 on PATH is optional. Without it the ROS 2 tools fall back to fixtures (a fictional demo robot) and `health_check` reports `mode: mock`. The DDS tools work without ROS 2.
+
+## Install
+
+From a marketplace, once the plugin is listed:
+
+```
+/plugin install topicforge
+```
+
+Meanwhile, from this repository (Claude Code):
+
+```
+claude plugin marketplace add yaniswav/TopicForge
+claude plugin install topicforge@topicforge
+```
+
+Or load the folder for one session: `claude --plugin-dir ./plugin`.
+
+## Configuration
+
+Claude Code asks for two options when the plugin is enabled:
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `dds_backend` | `cyclone` | `cyclone` joins the DDS bus as a read-only participant. `mock` serves fixtures. `auto` picks the best available. |
+| `dds_domain_id` | `0` | The one DDS domain observed (0 to 232). Fixed at startup. |
+
+The server runs with `TOPICFORGE_MODE=auto`: live ROS 2 when `ros2` is on PATH, fixtures otherwise. Cowork does not prompt for options and uses the defaults. To use other settings there, edit `.mcp.json`.
+
+Without DDS, set `dds_backend` to `mock`, or use the standalone install `uvx topicforge`.
+
+## Privacy
+
+The server reads the local ROS 2 graph and the DDS discovery traffic on the machine and network it runs on, and returns the result to the Claude session. It makes no outbound network calls. Anonymous telemetry exists but is off by default and is not enabled by this plugin. See the main [README](https://github.com/yaniswav/TopicForge#telemetry) for the telemetry contract and [SECURITY.md](https://github.com/yaniswav/TopicForge/blob/main/SECURITY.md).
+
+## Limits
+
+TopicForge sees what DDS discovery announces. It cannot see whether data flows, a writer that is alive but silent, other DDS domains, or secured (DDS Security) endpoints. The skills tell Claude to say so.
+
+## Links
+
+- Project: https://github.com/yaniswav/TopicForge
+- Site: https://topicforge.horizonvista.xyz
+- Issues: https://github.com/yaniswav/TopicForge/issues
+- License: MIT

{topicforge-0.6.0 → topicforge-0.6.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "topicforge"
-version = "0.6.0"
+version = "0.6.2"
 description = "ROS Topic Inspector & Bag Analyzer MCP server for AI agents"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -81,7 +81,7 @@ packages = ["src/topicforge"]
 
 [tool.hatch.build.targets.sdist]
 include = ["src/topicforge", "tests", "docs", "README.md", "CHANGELOG.md", "LICENSE", "pyproject.toml"]
-exclude = [".claude", "docs/projet-file/**", "docs/projet-file", "tests/fixtures/bags/**", "CLAUDE.md", "*.pdf", ".pytest_cache", "pytest-cache-files-*", "pro"]
+exclude = [".claude", "docs/projet-file/**", "docs/projet-file", "tests/fixtures/bags/**", "CLAUDE.md", "*.pdf", ".pytest_cache", "pytest-cache-files-*", "pro", "mcpb"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{topicforge-0.6.0 → topicforge-0.6.2}/src/topicforge/__init__.py

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

{topicforge-0.6.0 → topicforge-0.6.2}/src/topicforge/adapters/common/cdr_decoder.py

@@ -59,8 +59,18 @@ def iter_field_names(sample: Any) -> list[str]:
     """List field names on a dynamic-type sample.
 
     Tries `__dataclass_fields__`, `__fields__`, `__slots__`, then public
-    `__dict__` keys. Returns an empty list when none apply.
+    `__dict__` keys. Returns an empty list when none apply. Dunder names
+    such as the `__msgtype__` marker that `rosbags` messages carry are
+    not data and are left out.
     """
+    return [name for name in _raw_field_names(sample) if not _is_dunder(name)]
+
+
+def _is_dunder(name: str) -> bool:
+    return name.startswith("__") and name.endswith("__")
+
+
+def _raw_field_names(sample: Any) -> list[str]:
     fields = getattr(sample, "__dataclass_fields__", None)
     if fields:
         return list(fields)

{topicforge-0.6.0 → topicforge-0.6.2}/src/topicforge/adapters/composite.py

@@ -81,6 +81,11 @@ class CompositeAdapter:
     def analyze_bag(self, path: str) -> BagAnalysis:
         return self._ros.analyze_bag(path)
 
+    def sim_clock_published(self) -> bool | None:
+        """The ROS 2 half's `/clock` probe, `None` when it has none."""
+        probe = getattr(self._ros, "sim_clock_published", None)
+        return probe() if callable(probe) else None
+
     # ----- DDS surface -> DDS adapter -----
 
     def observer_status(self) -> dict[str, Any] | None: