topicforge 0.6.2__tar.gz → 0.6.3__tar.gz

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

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning 2.0.0](https://semver.org/spec/
 
 ## [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
@@ -1316,7 +1354,8 @@ 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.2...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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: topicforge
-Version: 0.6.2
+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).
@@ -100,7 +103,7 @@ 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`.
 
-**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).
+**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).
 
@@ -138,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
 ```
 
@@ -195,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.2"`       | 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.2 → 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).
@@ -40,7 +42,7 @@ 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`.
 
-**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).
+**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).
 
@@ -78,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
 ```
 
@@ -135,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.2"`       | 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.2 → topicforge-0.6.3}/docs/CLIENTS.md

@@ -1,12 +1,12 @@
 # Using TopicForge from your MCP client
 
-Last checked 2026-10-06.
+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[dds]==0.6.2" topicforge
+uvx --from "topicforge==0.6.3" topicforge
 ```
 
 and the same three environment variables:
@@ -14,14 +14,14 @@ 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_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.2`) is moved on every release together with the other
+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
@@ -36,9 +36,15 @@ version strings; a test keeps them in sync.
 - **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
+- **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.
@@ -66,7 +72,7 @@ say where the file lives and what differs.
   "mcpServers": {
     "topicforge": {
       "command": "uvx",
-      "args": ["--from", "topicforge[dds]==0.6.2", "topicforge"],
+      "args": ["--from", "topicforge==0.6.3", "topicforge"],
       "env": {
         "TOPICFORGE_MODE": "auto",
         "TOPICFORGE_DDS_BACKEND": "cyclone",
@@ -89,12 +95,12 @@ 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 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.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.
+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,
@@ -106,18 +112,18 @@ 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=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJ0b3BpY2ZvcmdlW2Rkc109PTAuNi4yIiwidG9waWNmb3JnZSJdLCJlbnYiOnsiVE9QSUNGT1JHRV9NT0RFIjoiYXV0byIsIlRPUElDRk9SR0VfRERTX0JBQ0tFTkQiOiJjeWNsb25lIiwiVE9QSUNGT1JHRV9ERFNfRE9NQUlOX0lEIjoiMCJ9fQ%3D%3D)
+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=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJ0b3BpY2ZvcmdlW2Rkc109PTAuNi4yIiwidG9waWNmb3JnZSJdLCJlbnYiOnsiVE9QSUNGT1JHRV9NT0RFIjoiYXV0byIsIlRPUElDRk9SR0VfRERTX0JBQ0tFTkQiOiJjeWNsb25lIiwiVE9QSUNGT1JHRV9ERFNfRE9NQUlOX0lEIjoiMCJ9fQ==`
+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%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)
+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%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%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:
@@ -128,7 +134,7 @@ Or put this in `.vscode/mcp.json` (the key is `servers`, not `mcpServers`), or r
     "topicforge": {
       "type": "stdio",
       "command": "uvx",
-      "args": ["--from", "topicforge[dds]==0.6.2", "topicforge"],
+      "args": ["--from", "topicforge==0.6.3", "topicforge"],
       "env": {
         "TOPICFORGE_MODE": "auto",
         "TOPICFORGE_DDS_BACKEND": "cyclone",
@@ -157,7 +163,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[dds]==0.6.2",
+to `"command": "cmd", "args": ["/c", "uvx", "--from", "topicforge==0.6.3",
 "topicforge"]` if it fails to start.
 
 ## Continue
@@ -174,7 +180,7 @@ mcpServers:
     command: uvx
     args:
       - "--from"
-      - "topicforge[dds]==0.6.2"
+      - "topicforge==0.6.3"
       - "topicforge"
     env:
       TOPICFORGE_MODE: auto
@@ -191,7 +197,7 @@ In `settings.json`, under `context_servers`:
   "context_servers": {
     "topicforge": {
       "command": "uvx",
-      "args": ["--from", "topicforge[dds]==0.6.2", "topicforge"],
+      "args": ["--from", "topicforge==0.6.3", "topicforge"],
       "env": {
         "TOPICFORGE_MODE": "auto",
         "TOPICFORGE_DDS_BACKEND": "cyclone",
@@ -217,7 +223,7 @@ 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"]
+args = ["--from", "topicforge==0.6.3", "topicforge"]
 startup_timeout_sec = 60
 
 [mcp_servers.topicforge.env]
@@ -248,7 +254,7 @@ extensions:
     name: TopicForge (ROS 2 / DDS)
     type: stdio
     cmd: uvx
-    args: [--from, "topicforge[dds]==0.6.2", topicforge]
+    args: [--from, "topicforge==0.6.3", topicforge]
     enabled: true
     envs: { "TOPICFORGE_MODE": "auto", "TOPICFORGE_DDS_BACKEND": "cyclone", "TOPICFORGE_DDS_DOMAIN_ID": "0" }
     timeout: 300
@@ -273,7 +279,7 @@ Settings > MCP > "+ Add", then paste the common JSON shape (unverified, last che
 
 ## Troubleshooting
 
-- Run the command by hand first: `uvx --from "topicforge[dds]==0.6.2" topicforge --version`.
+- 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`.

{topicforge-0.6.2 → 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.2 → 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.2
+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.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.
+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
 

{topicforge-0.6.2 → 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.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`.
+- 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.2 → topicforge-0.6.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "topicforge"
-version = "0.6.2"
+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",
 ]

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

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

{topicforge-0.6.2 → 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:

{topicforge-0.6.2 → topicforge-0.6.3}/src/topicforge/services/factory.py

@@ -10,6 +10,8 @@ and the DDS adapter are each built best-effort. Both up gives a
 from __future__ import annotations
 
 import logging
+import platform
+import sys
 from collections.abc import Callable
 
 from topicforge.adapters.base import AdapterError, MiddlewareAdapter
@@ -59,7 +61,10 @@ def build_adapter(settings: Settings) -> MiddlewareAdapter:
         settings.ros2_executable,
         settings.effective_dds_backend,
     )
-    return MockAdapter()
+    fallback = MockAdapter()
+    if settings.dds_backend != "mock":
+        fallback.dds_inactive_reason = _dds_inactive_reason(settings)
+    return fallback
 
 
 def _try_build_ros2_cli(
@@ -80,11 +85,50 @@ def _try_build_ros2_cli(
     return cli_adapter
 
 
-_CYCLONE_HINT = (
+_CYCLONE_INSTALL_HINT = (
     'Install it with `pip install "topicforge[dds-cyclone]"` and set '
     "`TOPICFORGE_DDS_BACKEND=cyclone`."
 )
 
+# Platforms where the `cyclonedds` project publishes prebuilt wheels (CPython 3.10-3.13).
+# Keep in sync with the environment marker on the `cyclonedds` dependency in pyproject.toml.
+_CYCLONE_WHEEL_SYSTEMS: dict[str, frozenset[str] | None] = {
+    "linux": frozenset({"x86_64"}),
+    "windows": frozenset({"amd64"}),
+    "darwin": None,  # any machine: x86_64 and arm64 both ship wheels
+}
+_CYCLONE_MAX_PYTHON = (3, 13)
+
+
+def cyclone_wheel_gap() -> str | None:
+    """Describe why `cyclonedds` has no prebuilt wheel here, or `None` when it has one.
+
+    The answer is a short platform label such as `linux-aarch64` or
+    `linux-aarch64 / Python 3.14`, naming only the parts that are unsupported.
+    """
+    system = platform.system().lower()
+    machine = platform.machine().lower()
+    machines = _CYCLONE_WHEEL_SYSTEMS.get(system, frozenset())
+    parts = []
+    if machines is not None and machine not in machines:
+        parts.append(f"{system or 'unknown'}-{machine or 'unknown'}")
+    if sys.version_info[:2] > _CYCLONE_MAX_PYTHON:
+        parts.append(f"Python {sys.version_info[0]}.{sys.version_info[1]}")
+    return " / ".join(parts) or None
+
+
+def _cyclone_hint() -> str:
+    """What to do to get the Cyclone binding, adapted to the platform."""
+    gap = cyclone_wheel_gap()
+    if gap is None:
+        return _CYCLONE_INSTALL_HINT
+    return (
+        f"`cyclonedds` has no prebuilt wheel for {gap}, so it was not installed with "
+        "TopicForge. Install the Cyclone C library, then build the binding with "
+        '`pip install "topicforge[dds-cyclone]"` and set `TOPICFORGE_DDS_BACKEND=cyclone`; '
+        "or use `TOPICFORGE_DDS_BACKEND=mock`."
+    )
+
 
 def _dds_inactive_reason(settings: Settings) -> str:
     """Why no DDS backend is serving, for the three distinct causes.
@@ -98,7 +142,7 @@ def _dds_inactive_reason(settings: Settings) -> str:
         if settings.dds_backend == "auto":
             return (
                 "`TOPICFORGE_DDS_BACKEND=auto` found no DDS binding (`fastdds` or "
-                f"`cyclonedds`) installed. {_CYCLONE_HINT}"
+                f"`cyclonedds`) installed. {_cyclone_hint()}"
             )
         if module_is_importable(DDS_BACKEND_MODULES["cyclone"]):
             return (
@@ -106,14 +150,14 @@ def _dds_inactive_reason(settings: Settings) -> str:
                 "The `cyclonedds` binding is installed; set `TOPICFORGE_DDS_BACKEND=cyclone` "
                 "and restart to enable the DDS tools."
             )
-        return f"no DDS backend is selected and no DDS binding is installed. {_CYCLONE_HINT}"
+        return f"no DDS backend is selected and no DDS binding is installed. {_cyclone_hint()}"
     module = DDS_BACKEND_MODULES.get(backend)
     if backend in ("opendds", "dust"):
         return f"`TOPICFORGE_DDS_BACKEND={backend}` is a stub that never serves; use `cyclone`."
     if module is not None and not module_is_importable(module):
         return (
             f"`TOPICFORGE_DDS_BACKEND={backend}` is set but its `{module}` Python binding is "
-            f"not installed. {_CYCLONE_HINT if backend == 'cyclone' else ''}".rstrip()
+            f"not installed. {_cyclone_hint() if backend == 'cyclone' else ''}".rstrip()
         )
     return (
         f"`TOPICFORGE_DDS_BACKEND={backend}` is set and its binding is installed, but the "
@@ -150,9 +194,8 @@ def _try_build_cyclone(settings: Settings) -> MiddlewareAdapter | None:
     except ImportError:
         log.warning(
             "TOPICFORGE_DDS_BACKEND=cyclone but the `cyclonedds` Python "
-            "bindings are not installed. Install with "
-            '`pip install "topicforge[dds-cyclone]"`. The DDS module is '
-            "unavailable."
+            "bindings are not installed. %s The DDS module is unavailable.",
+            _cyclone_hint(),
         )
         return None
     except Exception as exc:  # a native library can fail to load (OSError)

{topicforge-0.6.2 → topicforge-0.6.3}/src/topicforge/services/health.py

@@ -53,7 +53,7 @@ class HealthService:
             dds_backend=dds_backend,
             dds_inactive_reason=(
                 getattr(self._adapter, "dds_inactive_reason", None)
-                if dds_backend == "none"
+                if dds_backend in ("none", "mock")
                 else None
             ),
             dds_domain_id=self._settings.dds_domain_id,

topicforge-0.6.3/src/topicforge/tools/annotations.py

@@ -0,0 +1,32 @@
+"""MCP `ToolAnnotations` shared by every TopicForge tool.
+
+TopicForge has no write path. The protocol-level declaration of that fact is
+built here, in one place, so a tool cannot be registered with a weaker
+read-only base by accident. `tests/test_tool_annotations.py` fails closed when
+a tool lacks these annotations.
+"""
+
+from __future__ import annotations
+
+from mcp.types import ToolAnnotations
+
+
+def read_only_annotations(title: str, *, open_world: bool) -> ToolAnnotations:
+    """Build the annotations for one read-only tool.
+
+    Args:
+        title: Short human-readable tool name.
+        open_world: True when the tool observes a live ROS 2 graph or DDS bus
+            (state outside this process); False when it only reads the local
+            environment or local files.
+    """
+    return ToolAnnotations(
+        title=title,
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=open_world,
+    )
+
+
+__all__ = ["read_only_annotations"]