topicforge 0.6.1__tar.gz → 0.6.3__tar.gz

{topicforge-0.6.1 → topicforge-0.6.3}/CHANGELOG.md

@@ -5,6 +5,66 @@ 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.3] - 2026-10-07
+
+### Added
+
+- Platform-aware DDS message: when the Cyclone backend is requested but the binding is
+  missing, `dds_inactive_reason` (and the server log) now says why in plain words, for
+  example "`cyclonedds` has no prebuilt wheel for linux-aarch64 / Python 3.14", and what
+  to do (build it against the Cyclone C library, or use mock). A server that falls back
+  to the mock fixtures because of this reports the reason in `health_check` too. Field
+  names are unchanged.
+- CI: a `ubuntu-24.04-arm` job that installs the package without a Cyclone wheel and
+  checks that the server starts and `health_check` explains, and Python 3.14 in the test
+  matrix (the suite runs there with the binding absent).
+
+- MCP `ToolAnnotations` on all twelve tools (`title`, `readOnlyHint=true`,
+  `destructiveHint=false`, `idempotentHint=true`, per-tool `openWorldHint`),
+  built by one shared helper in `tools/annotations.py`, and
+  `tests/test_tool_annotations.py`, which fails if any tool lacks them.
+
+### Changed
+
+- `cyclonedds` is now a core dependency, restricted by an environment marker to the
+  platforms where it ships prebuilt wheels (Python 3.10-3.13 on Linux x86_64, Windows
+  AMD64 and macOS), so `uvx topicforge` and `pip install topicforge` bring the DDS
+  binding with no extra. Other platforms (Linux aarch64, Python 3.14, Windows ARM64)
+  install cleanly without it. `topicforge[dds]` and `topicforge[dds-cyclone]` stay as
+  aliases. The default `TOPICFORGE_DDS_BACKEND` is still `mock`.
+- The Claude plugin launches `uvx --python 3.12 --from topicforge==0.6.3 topicforge`
+  without an extra; its dependencies are declared in the new `plugin/pyproject.toml`
+  (a lock, `plugin/uv.lock`, is generated once the release is on PyPI). The version
+  consistency test covers both files.
+- Documented launch commands, the Cursor and VS Code install links and the MCP Bundle
+  now use `topicforge==X` instead of `topicforge[dds]==X`.
+- `SECURITY.md`: new section "Read-only guarantee: architecture, declaration,
+  proof" (including the limits of passivity on a DDS domain and the ros2 CLI),
+  Popen streaming with process-tree kill documented, any MCP client named, and
+  a remote-access paragraph.
+
+## [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
@@ -1294,7 +1354,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.1...HEAD
+[Unreleased]: https://github.com/yaniswav/TopicForge/compare/v0.6.3...HEAD
+[0.6.3]: https://github.com/yaniswav/TopicForge/compare/v0.6.2...v0.6.3
+[0.6.2]: https://github.com/yaniswav/TopicForge/compare/v0.6.1...v0.6.2
 [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

{topicforge-0.6.1 → topicforge-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: topicforge
-Version: 0.6.1
+Version: 0.6.3
 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
@@ -40,6 +40,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
+Requires-Dist: cyclonedds>=0.10; python_version < '3.14' and ((platform_system == 'Linux' and platform_machine == 'x86_64') or (platform_system == 'Windows' and platform_machine == 'AMD64') or platform_system == 'Darwin')
 Requires-Dist: mcp<2,>=1.0.0
 Requires-Dist: pydantic>=2.6
 Requires-Dist: pyyaml>=6
@@ -70,6 +71,8 @@ Description-Content-Type: text/markdown
 
 A read-only MCP (Model Context Protocol) server that lets an AI agent inspect a ROS2 graph, recorded bag files and the DDS layer underneath ROS. The code has no write path: it cannot publish to the bus or command a robot, and there is no permission system to configure.
 
+Every tool also declares itself read-only in the MCP protocol (`readOnlyHint`, `destructiveHint=false`, `idempotentHint`, with an honest `openWorldHint`), and a test fails if any tool lacks it. See [`SECURITY.md`](SECURITY.md#read-only-guarantee-architecture-declaration-proof) for the guarantee and its limits.
+
 It gives the agent twelve typed tools that return frozen Pydantic schemas, identical whether the server talks to a real robot or to its built-in mock fixtures. Ask why `nav_planner` gets no scan, and the agent reads the bus, finds the BEST_EFFORT writer facing a RELIABLE reader and names the incompatible policy (see [`examples/02-debug-qos-mismatch.md`](examples/02-debug-qos-mismatch.md)). It is meant for ROS2 developers, robotics ML/CV engineers and teams that cannot accept a write path into a production stack.
 
 For DDS, TopicForge joins a domain as a read-only participant through one open-source binding (Eclipse CycloneDDS from PyPI) and reads the builtin discovery topics that the OMG DDS-RTPS protocol standardizes. So far the author has observed Cyclone DDS and Dust DDS participants on a live bus. RTI Connext, OpenDDS, CoreDX and Fast DDS announce themselves through the same standard discovery, but none of them has been observed yet. This covers discovery only: participants, readers, writers and their QoS. See [`docs/dds-interop-matrix.md`](docs/dds-interop-matrix.md).
@@ -98,7 +101,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=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJ0b3BpY2ZvcmdlPT0wLjYuMyIsInRvcGljZm9yZ2UiXSwiZW52Ijp7IlRPUElDRk9SR0VfTU9ERSI6ImF1dG8iLCJUT1BJQ0ZPUkdFX0REU19CQUNLRU5EIjoiY3ljbG9uZSIsIlRPUElDRk9SR0VfRERTX0RPTUFJTl9JRCI6IjAifX0%3D) | [Install in VS Code](https://vscode.dev/redirect/mcp/install?name=topicforge&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22--from%22%2C%22topicforge%3D%3D0.6.3%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
 
@@ -134,7 +141,8 @@ Walkthroughs against the mock, each with the exact tool calls and payloads, are
 ## DDS backends
 
 ```bash
-pip install topicforge[dds]                      # Eclipse CycloneDDS ([dds-cyclone] is the same thing)
+pip install topicforge                           # includes Eclipse CycloneDDS where wheels exist (Python 3.10-3.13; Linux x86_64, Windows x64, macOS)
+pip install "topicforge[dds]"                    # alias, kept so older commands work; forces a source build elsewhere (needs the Cyclone C library)
 TOPICFORGE_DDS_BACKEND=cyclone python -m topicforge
 ```
 
@@ -191,7 +199,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.1"`       | TopicForge server version                                   |
+| `version`    | `"0.6.3"`       | TopicForge server version                                   |
 | `session_id` | `"a1b2c3..."`   | Random UUID per process, never persisted                    |
 | `success`    | `true`          | Whether the handler returned or raised                      |
 

{topicforge-0.6.1 → topicforge-0.6.3}/README.md

@@ -10,6 +10,8 @@
 
 A read-only MCP (Model Context Protocol) server that lets an AI agent inspect a ROS2 graph, recorded bag files and the DDS layer underneath ROS. The code has no write path: it cannot publish to the bus or command a robot, and there is no permission system to configure.
 
+Every tool also declares itself read-only in the MCP protocol (`readOnlyHint`, `destructiveHint=false`, `idempotentHint`, with an honest `openWorldHint`), and a test fails if any tool lacks it. See [`SECURITY.md`](SECURITY.md#read-only-guarantee-architecture-declaration-proof) for the guarantee and its limits.
+
 It gives the agent twelve typed tools that return frozen Pydantic schemas, identical whether the server talks to a real robot or to its built-in mock fixtures. Ask why `nav_planner` gets no scan, and the agent reads the bus, finds the BEST_EFFORT writer facing a RELIABLE reader and names the incompatible policy (see [`examples/02-debug-qos-mismatch.md`](examples/02-debug-qos-mismatch.md)). It is meant for ROS2 developers, robotics ML/CV engineers and teams that cannot accept a write path into a production stack.
 
 For DDS, TopicForge joins a domain as a read-only participant through one open-source binding (Eclipse CycloneDDS from PyPI) and reads the builtin discovery topics that the OMG DDS-RTPS protocol standardizes. So far the author has observed Cyclone DDS and Dust DDS participants on a live bus. RTI Connext, OpenDDS, CoreDX and Fast DDS announce themselves through the same standard discovery, but none of them has been observed yet. This covers discovery only: participants, readers, writers and their QoS. See [`docs/dds-interop-matrix.md`](docs/dds-interop-matrix.md).
@@ -38,7 +40,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=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJ0b3BpY2ZvcmdlPT0wLjYuMyIsInRvcGljZm9yZ2UiXSwiZW52Ijp7IlRPUElDRk9SR0VfTU9ERSI6ImF1dG8iLCJUT1BJQ0ZPUkdFX0REU19CQUNLRU5EIjoiY3ljbG9uZSIsIlRPUElDRk9SR0VfRERTX0RPTUFJTl9JRCI6IjAifX0%3D) | [Install in VS Code](https://vscode.dev/redirect/mcp/install?name=topicforge&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22--from%22%2C%22topicforge%3D%3D0.6.3%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
 
@@ -74,7 +80,8 @@ Walkthroughs against the mock, each with the exact tool calls and payloads, are
 ## DDS backends
 
 ```bash
-pip install topicforge[dds]                      # Eclipse CycloneDDS ([dds-cyclone] is the same thing)
+pip install topicforge                           # includes Eclipse CycloneDDS where wheels exist (Python 3.10-3.13; Linux x86_64, Windows x64, macOS)
+pip install "topicforge[dds]"                    # alias, kept so older commands work; forces a source build elsewhere (needs the Cyclone C library)
 TOPICFORGE_DDS_BACKEND=cyclone python -m topicforge
 ```
 
@@ -131,7 +138,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.1"`       | TopicForge server version                                   |
+| `version`    | `"0.6.3"`       | TopicForge server version                                   |
 | `session_id` | `"a1b2c3..."`   | Random UUID per process, never persisted                    |
 | `success`    | `true`          | Whether the handler returned or raised                      |
 

topicforge-0.6.3/docs/CLIENTS.md

@@ -0,0 +1,286 @@
+# Using TopicForge from your MCP client
+
+Last checked 2026-10-07.
+
+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.6.3" 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 `cyclonedds` binding is installed with TopicForge on supported platforms). 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.3`) 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).
+- **Platforms without a Cyclone wheel.** Since 0.6.3 `cyclonedds` is a normal dependency
+  of `topicforge`, installed only where it ships prebuilt wheels: Python 3.10 to 3.13 on
+  Linux x86_64, Windows x64 and macOS. On Linux ARM (Jetson, Raspberry Pi), Windows ARM64
+  or Python 3.14 the server still starts and `health_check` says why the DDS backend is
+  off (`dds_inactive_reason`); with a pinned Python, add `"--python", "3.12"` before
+  `"--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.6.3"`, 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==0.6.3", "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==0.6.3" topicforge
+```
+
+## Claude Desktop
+
+From 0.6.3: 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=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJ0b3BpY2ZvcmdlPT0wLjYuMyIsInRvcGljZm9yZ2UiXSwiZW52Ijp7IlRPUElDRk9SR0VfTU9ERSI6ImF1dG8iLCJUT1BJQ0ZPUkdFX0REU19CQUNLRU5EIjoiY3ljbG9uZSIsIlRPUElDRk9SR0VfRERTX0RPTUFJTl9JRCI6IjAifX0%3D)
+
+If that page does not open Cursor, use the raw deeplink: `cursor://anysphere.cursor-deeplink/mcp/install?name=topicforge&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJ0b3BpY2ZvcmdlPT0wLjYuMyIsInRvcGljZm9yZ2UiXSwiZW52Ijp7IlRPUElDRk9SR0VfTU9ERSI6ImF1dG8iLCJUT1BJQ0ZPUkdFX0REU19CQUNLRU5EIjoiY3ljbG9uZSIsIlRPUElDRk9SR0VfRERTX0RPTUFJTl9JRCI6IjAifX0=`
+
+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%3D%3D0.6.3%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.6.3%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==0.6.3", "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==0.6.3",
+"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==0.6.3"
+      - "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==0.6.3", "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==0.6.3", "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==0.6.3", 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==0.6.3" 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.1 → topicforge-0.6.3}/docs/DDS_QUICKSTART.md

@@ -30,7 +30,7 @@ pip install topicforge[dds]             # same as [dds-cyclone]
 TOPICFORGE_DDS_BACKEND=cyclone python -m topicforge
 ```
 
-`cyclonedds` publishes wheels for CPython 3.10 to 3.13 on Windows, Linux and macOS (as of 11.0.1). A background thread reads the builtin DCPS topics through `BuiltinDataReader`. On a real bus `list_participants` reports each participant's `name` (EntityName QoS) and `hostname` (the `__Hostname` discovery property) when the remote participant sets them, and the vendor from the first two bytes of the GUID prefix; implementations that do not follow that convention (Dust DDS, RTI by default) show vendor `unknown`.
+`cyclonedds` publishes wheels for CPython 3.10 to 3.13 on Windows, Linux and macOS (as of 11.0.1), and `topicforge` depends on it only there. Elsewhere (Linux aarch64, Python 3.14, Windows ARM64) `health_check` reports why in `dds_inactive_reason`. A background thread reads the builtin DCPS topics through `BuiltinDataReader`. On a real bus `list_participants` reports each participant's `name` (EntityName QoS) and `hostname` (the `__Hostname` discovery property) when the remote participant sets them, and the vendor from the first two bytes of the GUID prefix; implementations that do not follow that convention (Dust DDS, RTI by default) show vendor `unknown`.
 
 Fast DDS has no PyPI install path. The `fastdds` binding is not published, so TopicForge declares no extra for it. Build eProsima's [Fast-DDS-python](https://github.com/eProsima/Fast-DDS-python) from source (it needs the Fast DDS C++ libraries and SWIG), install it into the same environment, then `TOPICFORGE_DDS_BACKEND=fast`. The adapter was written against the 2.6.x API and has never run against a bus.
 

{topicforge-0.6.1 → topicforge-0.6.3}/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.1
+python -m topicforge --version                      # -> topicforge 0.6.3
 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.1 ready (mode=live, requested_mode=live, adapter=ros2_cli, telemetry=off)`; `mode=mock` means `ros2` was not found and the server fell back to fixtures.
+Then run live mode with three terminals. In the first, `ros2 run demo_nodes_cpp talker` publishes `/chatter` at about 1 Hz. In the second, `ros2 topic list` should show `/chatter`. In the third, source ROS2, activate the venv and run `TOPICFORGE_MODE=live python -m topicforge`. The startup line reads `topicforge 0.6.3 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.1 → topicforge-0.6.3}/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.6.1). 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`.
+- MCP server `topicforge`, started with `uvx` from the `topicforge` package on PyPI (version pinned to 0.6.3). 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.
 

topicforge-0.6.3/plugin/pyproject.toml

@@ -0,0 +1,16 @@
+# Dependency manifest for the Claude plugin directory. It is not a package: it only declares
+# what `plugin/.mcp.json` launches, so that `uv.lock` next to it pins every dependency with
+# hashes. Keep the topicforge pin equal to the version in `.mcp.json`; a test checks it.
+# After a release reaches PyPI, regenerate the lock: `cd plugin && uv lock`.
+[project]
+name = "topicforge-claude-plugin"
+version = "0.6.3"
+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.6.3",
+]
+
+[tool.uv]
+package = false

{topicforge-0.6.1 → topicforge-0.6.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "topicforge"
-version = "0.6.1"
+version = "0.6.3"
 description = "ROS Topic Inspector & Bag Analyzer MCP server for AI agents"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -26,6 +26,13 @@ dependencies = [
     "mcp>=1.0.0,<2",
     "pydantic>=2.6",
     "pyyaml>=6",
+    # Cyclone DDS binding, core since 0.6.3 so that `uvx topicforge` (no extra) can join a
+    # DDS bus. The marker lists exactly the platforms where cyclonedds 11.0.1 ships wheels
+    # (checked on PyPI 2026-10-07): CPython 3.10-3.13 on Linux x86_64, Windows AMD64 and
+    # macOS (x86_64 and arm64). Anywhere else (Linux aarch64, Python 3.14, Windows ARM64)
+    # pip would try to build the sdist, which needs the Cyclone C library and fails, so the
+    # dependency is skipped there and the server reports why in `dds_inactive_reason`.
+    'cyclonedds>=0.10; python_version < "3.14" and ((platform_system == "Linux" and platform_machine == "x86_64") or (platform_system == "Windows" and platform_machine == "AMD64") or platform_system == "Darwin")',
 ]
 
 [project.optional-dependencies]
@@ -50,6 +57,12 @@ dev = [
 # Fast DDS still works if its Python binding is built from eProsima's sources;
 # see docs/DDS_QUICKSTART.md. Do not add a name here without checking it
 # resolves on PyPI and belongs to the upstream project.
+#
+# `[dds]` and `[dds-cyclone]` are kept as aliases since 0.6.3 (cyclonedds became a core
+# dependency on supported platforms) so existing `topicforge[dds]` commands keep working.
+# They deliberately list cyclonedds WITHOUT the platform marker: a user on an unsupported
+# platform (Linux aarch64, Python 3.14) who has the Cyclone C library installed can still opt
+# in with `pip install "topicforge[dds]"` and build the binding from source.
 dds-cyclone = [
     "cyclonedds>=0.10",
 ]
@@ -81,7 +94,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.1 → topicforge-0.6.3}/src/topicforge/__init__.py

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

{topicforge-0.6.1 → topicforge-0.6.3}/src/topicforge/adapters/ros2_mock/adapter.py

@@ -29,6 +29,9 @@ _BAG_EXTENSIONS: frozenset[str] = frozenset({".mcap", ".db3", ".bag"})
 
 class MockAdapter:
     name: AdapterName = "mock"
+    # Set by the factory when a DDS backend was requested but the server fell back to
+    # these fixtures, so `health_check` can say why. `None` for a deliberate mock.
+    dds_inactive_reason: str | None = None
 
     @property
     def effective_mode(self) -> EffectiveMode: