topicforge 0.6.1__tar.gz → 0.6.2__tar.gz

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

@@ -5,6 +5,28 @@ 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
@@ -1294,7 +1316,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.1...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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: topicforge
-Version: 0.6.1
+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
 
@@ -191,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.1"`       | 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.1 → 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
 
@@ -131,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.1"`       | 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.1 → 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.1
+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.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.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.1 → topicforge-0.6.2}/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.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.
 

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "topicforge"
-version = "0.6.1"
+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.1 → topicforge-0.6.2}/src/topicforge/__init__.py

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

topicforge-0.6.2/tests/test_version_consistency.py

@@ -0,0 +1,150 @@
+"""Fail when the version strings scattered across the repo drift apart.
+
+One release touches the package, the registry manifest, the Claude plugin, the
+Gemini extension, the MCP Bundle and the pins copied into the docs. Forgetting
+one of them ships a client config that installs the wrong version.
+
+Repo-only: the sdist does not carry server.json, the plugin or the bundle, so the
+whole module is skipped there. Nothing reads a file at import time.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import re
+import urllib.parse
+from collections.abc import Callable
+from pathlib import Path
+
+import pytest
+
+import topicforge
+
+ROOT = Path(__file__).resolve().parent.parent
+
+pytestmark = pytest.mark.skipif(
+    not (ROOT / "server.json").exists(), reason="repo-only test (not in the sdist)"
+)
+
+PIN_RE = re.compile(r"topicforge\[dds\]==([0-9][^\s\"'\\)&%]*)")
+BARE_PIN_RE = re.compile(r"==(\d+\.\d+\.\d+)")
+VERSION_LINE_RE = re.compile(r'^version\s*=\s*"([^"]+)"', re.MULTILINE)
+LINK_RES = {
+    "cursor https": re.compile(r"\((https://cursor\.com/install-mcp\?[^)\s]+)\)"),
+    "vscode https": re.compile(r"\((https://vscode\.dev/redirect/mcp/install\?[^)\s]+)\)"),
+}
+
+
+def _text(rel: str) -> str:
+    return (ROOT / rel).read_text(encoding="utf-8")
+
+
+def _json(rel: str) -> dict:
+    return json.loads(_text(rel))
+
+
+def _toml_version(rel: str) -> str:
+    match = VERSION_LINE_RE.search(_text(rel))
+    assert match, f"no version line in {rel}"
+    return match.group(1)
+
+
+def _pin_in_args(args: list[str]) -> str:
+    match = PIN_RE.fullmatch(args[args.index("--from") + 1])
+    assert match, f"no topicforge[dds]==X pin in {args}"
+    return match.group(1)
+
+
+def _mcpb_pin() -> str:
+    match = PIN_RE.search(_text("mcpb/pyproject.toml"))
+    assert match, "no topicforge[dds]==X pin in mcpb/pyproject.toml"
+    return match.group(1)
+
+
+def _server_args(rel: str) -> list[str]:
+    return _json(rel)["mcpServers"]["topicforge"]["args"]
+
+
+SOURCES: dict[str, Callable[[], str]] = {
+    "pyproject.toml": lambda: _toml_version("pyproject.toml"),
+    "server.json": lambda: _json("server.json")["version"],
+    "server.json packages[0]": lambda: _json("server.json")["packages"][0]["version"],
+    "plugin.json": lambda: _json("plugin/.claude-plugin/plugin.json")["version"],
+    "plugin .mcp.json pin": lambda: _pin_in_args(_server_args("plugin/.mcp.json")),
+    "gemini-extension.json": lambda: _json("gemini-extension.json")["version"],
+    "gemini-extension.json pin": lambda: _pin_in_args(_server_args("gemini-extension.json")),
+    "mcpb manifest": lambda: _json("mcpb/manifest.json")["version"],
+    "mcpb pyproject version": lambda: _toml_version("mcpb/pyproject.toml"),
+    "mcpb pyproject pin": _mcpb_pin,
+}
+
+
+@pytest.mark.parametrize("name", sorted(SOURCES))
+def test_version_matches_package(name: str) -> None:
+    assert SOURCES[name]() == topicforge.__version__, f"{name} drifted from __version__"
+
+
+def test_pyproject_matches_package_and_bundle() -> None:
+    assert _toml_version("pyproject.toml") == topicforge.__version__
+    assert _toml_version("pyproject.toml") == _toml_version("mcpb/pyproject.toml")
+
+
+@pytest.mark.parametrize("rel", ["docs/CLIENTS.md", "README.md", "docs/TESTING.md"])
+def test_doc_pins_match_package(rel: str) -> None:
+    text = _text(rel)
+    pins = set(PIN_RE.findall(text)) | set(BARE_PIN_RE.findall(text))
+    assert pins <= {topicforge.__version__}, f"{rel} has stale pins: {sorted(pins)}"
+
+
+def _links(text: str) -> dict[str, str]:
+    found = {}
+    for name, regex in LINK_RES.items():
+        match = regex.search(text)
+        assert match, f"{name} install link missing"
+        found[name] = match.group(1)
+    return found
+
+
+def _decode_cursor(url: str) -> dict:
+    query = urllib.parse.parse_qs(urllib.parse.urlsplit(url).query)
+    assert query["name"] == ["topicforge"]
+    return json.loads(base64.b64decode(query["config"][0]))
+
+
+def _decode_vscode_redirect(url: str) -> dict:
+    query = urllib.parse.parse_qs(urllib.parse.urlsplit(url).query)
+    assert query["name"] == ["topicforge"]
+    return json.loads(query["config"][0])
+
+
+def test_install_links_decode_to_pinned_config() -> None:
+    clients = _text("docs/CLIENTS.md")
+    links = _links(clients)
+    cursor_cfg = _decode_cursor(links["cursor https"])
+    vscode_cfg = _decode_vscode_redirect(links["vscode https"])
+    assert _pin_in_args(cursor_cfg["args"]) == topicforge.__version__
+    assert vscode_cfg == cursor_cfg
+
+    # Raw scheme fallbacks kept in CLIENTS.md decode to the same config.
+    raw_cursor = re.search(r"`(cursor://[^`\s]+)`", clients)
+    assert raw_cursor, "raw cursor:// fallback missing"
+    assert _decode_cursor(raw_cursor.group(1)) == cursor_cfg
+    raw_vscode = re.search(r"`vscode:mcp/install\?([^`\s]+)`", clients)
+    assert raw_vscode, "raw vscode: fallback missing"
+    assert json.loads(urllib.parse.unquote(raw_vscode.group(1))) == {
+        "name": "topicforge",
+        **cursor_cfg,
+    }
+
+
+@pytest.mark.parametrize("rel", ["README.md", "docs/TESTING.md"])
+def test_other_docs_links_identical_to_clients_doc(rel: str) -> None:
+    text = _text(rel)
+    expected = _links(_text("docs/CLIENTS.md"))
+    for name, regex in LINK_RES.items():
+        found = {m for m in regex.findall(text)}
+        if rel == "README.md":
+            assert found == {expected[name]}, f"{rel}: {name} link differs from CLIENTS.md"
+        else:
+            assert found <= {expected[name]}, f"{rel}: {name} link differs from CLIENTS.md"