topicforge 0.1.0__tar.gz

topicforge-0.1.0/.gitignore

@@ -0,0 +1,194 @@
+# =========================================================================
+# TopicForge — .gitignore
+#
+# Anything matched here is local-only: it must never appear in a clone,
+# a sdist, a wheel, or a screen share with a client. Add new patterns
+# above the matching section header so the rationale stays close.
+# =========================================================================
+
+
+# -------------------------------------------------------------------------
+# Python: bytecode, caches, packaging
+# -------------------------------------------------------------------------
+__pycache__/
+*.py[cod]
+*$py.class
+*.pyo
+*.pyd
+
+
+# -------------------------------------------------------------------------
+# Virtual environments
+# -------------------------------------------------------------------------
+.venv/
+venv/
+env/
+ENV/
+
+
+# -------------------------------------------------------------------------
+# Build artifacts and packaging tooling
+# -------------------------------------------------------------------------
+build/
+dist/
+*.egg
+*.egg-info/
+pip-wheel-metadata/
+pip-log.txt
+pip-delete-this-directory.txt
+.Python
+
+
+# -------------------------------------------------------------------------
+# Testing, coverage, profiling
+# -------------------------------------------------------------------------
+.pytest_cache/
+pytest-cache-files-*/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.cover
+.hypothesis/
+.tox/
+.nox/
+*.prof
+flamegraph.svg
+
+
+# -------------------------------------------------------------------------
+# Linters and type checkers
+# -------------------------------------------------------------------------
+.mypy_cache/
+.ruff_cache/
+.pyright/
+.pytype/
+
+
+# -------------------------------------------------------------------------
+# Editors and IDEs (per-developer; never shared)
+# -------------------------------------------------------------------------
+.idea/
+.vscode/
+.vs/
+*.iml
+*.swp
+*.swo
+*~
+.history/
+.spyderproject
+.spyproject
+*.sublime-workspace
+*.sublime-project
+.project
+.classpath
+.settings/
+
+
+# -------------------------------------------------------------------------
+# OS metadata
+# -------------------------------------------------------------------------
+.DS_Store
+._*
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+$RECYCLE.BIN/
+*.lnk
+
+
+# -------------------------------------------------------------------------
+# Secrets — NEVER commit
+# Use `.env.example` for documentation; real `.env` files stay local.
+# -------------------------------------------------------------------------
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+*.crt
+*.cer
+*.pfx
+*.p12
+id_rsa*
+id_ed25519*
+*.token
+secrets/
+secrets.yaml
+secrets.yml
+secrets.json
+credentials.json
+credentials.yaml
+.netrc
+.npmrc
+.pypirc
+
+# Cloud provider configs (often carry usable credentials)
+.aws/
+.gcp/
+.azure/
+
+
+# -------------------------------------------------------------------------
+# Logs, runtime state, dumps
+# -------------------------------------------------------------------------
+*.log
+logs/
+*.pid
+*.dump
+*.dmp
+dump.rdb
+*.sql
+*.sql.gz
+
+
+# -------------------------------------------------------------------------
+# Backup / scratch / editor-locks
+# -------------------------------------------------------------------------
+*.bak
+*.orig
+*.rej
+*.tmp
+*.temp
+.~lock.*
+
+
+# -------------------------------------------------------------------------
+# ROS / robotics recordings — often huge and frequently confidential
+# -------------------------------------------------------------------------
+*.bag
+*.db3
+*.mcap
+rosbag2_*/
+
+
+# -------------------------------------------------------------------------
+# Local notes and per-developer overrides
+# These are private to the contributor and must not ship with the repo.
+# -------------------------------------------------------------------------
+NOTES.md
+TODO.local.md
+SCRATCH.md
+notes/
+private/
+personal/
+
+
+# -------------------------------------------------------------------------
+# Claude Code internals
+# Operating manual, sub-agents, project skills, prompts, scripts, and
+# settings live entirely on the contributor's machine. They reveal
+# internal process and AI-assisted workflows that have no business
+# being in a client-facing repo. The sdist already excludes them via
+# `[tool.hatch.build.targets.sdist] exclude` in pyproject.toml; this
+# rule additionally hides them from the GitHub clone.
+# -------------------------------------------------------------------------
+.claude/
+CLAUDE*.md
+
+
+# -------------------------------------------------------------------------
+# Project-local docs and drafts kept out of the package / out of clients
+# -------------------------------------------------------------------------
+docs/projet-file/
+docs/assets/screencast-raw/

topicforge-0.1.0/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+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.1.0] - 2026-05-12
+
+Initial MVP release of TopicForge — ROS Topic Inspector & Bag Analyzer MCP server.
+
+### Added
+
+- Five read-only MCP tools exposed over FastMCP: `health_check`, `list_topics`, `get_topic_info`, `sample_messages`, and `analyze_bag`.
+- `RosAdapter` protocol in `adapters/base.py` defining the contract every backend implements.
+- Mock adapter (`adapters/ros2_mock/`) with deterministic fixtures modeling a small differential mobile robot equipped with a LIDAR and an RGB camera.
+- Live adapter (`adapters/ros2_live/`) built on subprocess wrappers around the `ros2` CLI, with pure module-level parsers tested independently of any ROS2 install.
+- Three runtime modes selectable via `TOPICFORGE_MODE`: `mock`, `live`, and `auto`. The `auto` resolution lives in `Settings.effective_mode`; the live-to-mock fallback when the adapter cannot start lives in `services/factory.py`.
+- Windows-first cross-platform support: executable resolution via `shutil.which` (handles `ros2.cmd` / `ros2.bat` shims), `subprocess.run` called with absolute paths and never `shell=True`, all filesystem paths via `pathlib.Path`.
+- Pydantic v2 schemas in `models/` configured with `extra="forbid"` and `frozen=True`, returned as the structured payload of every tool.
+- Pytest suite that runs entirely without a ROS2 environment, covering services, mock adapter, and live-adapter parsers.
+- Build, lint, and tooling configuration: Python 3.11+, `mcp >= 1.0.0` (FastMCP), `pydantic >= 2.6`, pytest, ruff, hatchling.
+- Licensed under the MIT License.
+
+### Notes
+
+- 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.1.0...HEAD
+[0.1.0]: https://github.com/yaniswav/TopicForge/releases/tag/v0.1.0

topicforge-0.1.0/LICENSE

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

topicforge-0.1.0/PKG-INFO

@@ -0,0 +1,292 @@
+Metadata-Version: 2.4
+Name: topicforge
+Version: 0.1.0
+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
+Project-URL: Issues, https://github.com/yaniswav/TopicForge/issues
+Project-URL: Changelog, https://github.com/yaniswav/TopicForge/blob/main/CHANGELOG.md
+Author-email: Yanis ETHVIGNOT <ethvignot.yanis@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Yanis ETHVIGNOT
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: ai,claude,mcp,model-context-protocol,robotics,ros2
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2.6
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# TopicForge
+
+> Stop asking Claude to invent topic names. TopicForge is the MCP server that grounds AI agents in your real ROS2 stack - or a faithful mock when you have no robot at hand.
+
+TopicForge is a production-minded MCP (Model Context Protocol) server that lets AI agents - such as Claude - inspect ROS2 topics and analyze ROS bag files through a clean, structured tool interface. It is designed for robotics developers, ML/CV engineers working with robot data, and teams that want their AI tooling to *understand* their robotics stack instead of guessing at it.
+
+## Why it exists
+
+LLM agents are good at reasoning over text, but ROS2 introspection lives in a CLI + DDS world they cannot directly reach. Without grounding, an LLM will hallucinate topic names, message types, and bag contents. TopicForge bridges that gap with a small, well-typed set of MCP tools:
+
+| Tool              | Purpose                                                |
+| ----------------- | ------------------------------------------------------ |
+| `health_check`    | Environment & mode introspection                       |
+| `list_topics`     | Discover the ROS graph                                 |
+| `get_topic_info`  | Structured info for a single topic                     |
+| `sample_messages` | Peek recent messages on a topic                        |
+| `analyze_bag`     | Summarize a `.mcap` / `.db3` / `.bag` recording        |
+
+Outputs are structured, JSON-serializable, and stable across runtime modes - they look the same whether the server is talking to a real robot or to its built-in mock fixtures.
+
+## 30-second demo without ROS2
+
+The mock adapter ships deterministic fixtures for a small differential robot (LIDAR + RGB camera). You do not need ROS2 installed to try the full tool surface - a clean Python 3.11 venv is enough.
+
+```bash
+pip install topicforge
+TOPICFORGE_MODE=mock python -m topicforge
+# Windows PowerShell: $env:TOPICFORGE_MODE="mock"; python -m topicforge
+```
+
+Point any MCP client (Claude Desktop, see below) at this server and ask it to *list the topics* or *analyze `/tmp/demo.mcap`* - every tool returns realistic, typed payloads.
+
+## Quickstart
+
+```bash
+pip install topicforge
+python -m topicforge --help
+TOPICFORGE_MODE=mock python -m topicforge
+```
+
+## Architecture
+
+```
++----------------------+
+|   MCP client (LLM)   |
++----------+-----------+
+           |  (stdio, MCP protocol)
+           v
++----------+-----------+
+|  topicforge.server   |   FastMCP entrypoint, lifecycle, tool registration
++----------+-----------+
+           |
+           v
++----------+-----------+
+|  topicforge.tools    |   Thin handlers - validate, delegate, serialize
++----------+-----------+
+           |
+           v
++----------+-----------+
+| topicforge.services  |   Inspector / Health - orchestration & validation
++----------+-----------+
+           |
+           v
++----------+-----------+
+| topicforge.adapters  |   ros2_live  - subprocess wrappers over `ros2` CLI
+|                      |   ros2_mock  - deterministic fixtures
++----------------------+
+```
+
+Layers are strictly separated:
+
+- **`server/`** wires the whole graph and exposes `build_app(settings)`.
+- **`tools/`** registers MCP tools on FastMCP. Handlers never call ROS directly.
+- **`services/`** validate inputs and orchestrate calls.
+- **`adapters/`** are the *only* code that knows how to talk to a specific backend. New backends (e.g. an `rclpy`-based adapter) plug in by implementing the `RosAdapter` protocol.
+- **`models/`** holds Pydantic schemas - the contract with MCP clients.
+- **`config/`** resolves runtime settings from the environment.
+
+## Runtime modes
+
+| Mode    | When to use                                         | Backend                       |
+| ------- | --------------------------------------------------- | ----------------------------- |
+| `mock`  | Local development, demos, CI, screencasts           | Deterministic fixtures        |
+| `live`  | A machine with ROS2 installed and sourced           | `ros2` CLI wrappers           |
+| `auto`  | Detect ROS2; fall back to mock if not present       | Best available (default)      |
+
+Mode is selected via the `TOPICFORGE_MODE` environment variable.
+
+## Install from source
+
+Requires Python 3.11+.
+
+```bash
+git clone https://github.com/yaniswav/TopicForge.git
+cd TopicForge
+python -m venv .venv
+source .venv/bin/activate          # Linux / macOS
+# .venv\Scripts\Activate.ps1       # Windows PowerShell
+pip install -e ".[dev]"
+```
+
+Or, if you have `make`:
+
+```bash
+make dev
+```
+
+## Run
+
+### Mock mode (no ROS2 required)
+
+```bash
+TOPICFORGE_MODE=mock python -m topicforge
+```
+
+Or:
+
+```bash
+make run-mock
+```
+
+### Live mode (requires ROS2)
+
+Source your ROS2 distribution first, then:
+
+```bash
+source /opt/ros/humble/setup.bash
+TOPICFORGE_MODE=live python -m topicforge
+```
+
+TopicForge invokes the `ros2` CLI under the hood, so it does **not** require `rclpy` to be importable. This keeps the live adapter portable across ROS2 distros.
+
+### Configure with Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "topicforge": {
+      "command": "python",
+      "args": ["-m", "topicforge"],
+      "env": { "TOPICFORGE_MODE": "auto" }
+    }
+  }
+}
+```
+
+## Test
+
+```bash
+pytest
+# or
+make test
+```
+
+Tests run entirely against the mock adapter and the live adapter's pure parsers - they never require a running ROS graph. The full suite completes in well under a second.
+
+## Lint & format
+
+```bash
+make lint     # ruff check
+make fmt      # ruff format
+make check    # both, plus tests (CI bundle)
+```
+
+> **Windows note.** The `Makefile` uses POSIX shell syntax (`VAR=value cmd`,
+> `find … -exec`). Run it from Git Bash, WSL, or MSYS2. From a plain
+> PowerShell session, invoke the underlying commands directly:
+>
+> ```powershell
+> python -m ruff check src tests
+> python -m ruff format src tests
+> python -m pytest
+> $env:TOPICFORGE_MODE = "mock"; python -m topicforge   # equivalent of `make run-mock`
+> ```
+
+## Configuration reference
+
+| Variable                 | Default | Description                                                       |
+| ------------------------ | ------- | ----------------------------------------------------------------- |
+| `TOPICFORGE_MODE`        | `auto`  | `mock`, `live`, or `auto`                                         |
+| `TOPICFORGE_LOG_LEVEL`   | `INFO`  | `DEBUG`, `INFO`, `WARNING`, `ERROR`                               |
+| `TOPICFORGE_ROS2_BIN`    | `ros2`  | Name (or path) of the ROS2 CLI binary                             |
+
+See [`.env.example`](.env.example).
+
+## Security model
+
+TopicForge is designed for **local trust**: it runs as a subprocess of your MCP client (Claude Desktop, Claude Code) on a machine you control, and inspects your own ROS2 graph or your own bag files. It is not hardened for adversarial inputs.
+
+- `TOPICFORGE_ROS2_BIN` accepts an arbitrary path - if you point it at a malicious binary, TopicForge will execute it. Treat the variable the way you treat `PATH`.
+- `analyze_bag` opens whatever path the MCP client passes (no workspace isolation, no symlink restriction). The threat model assumes the client is your trusted agent acting on your behalf.
+- All `ros2` CLI invocations use `subprocess.run` with an argument list - never `shell=True`. Topic names are validated against a strict allowlist (`^/[A-Za-z0-9_/]+$`) before being passed to the CLI.
+- No outbound network calls. No telemetry in v0.1.0 (opt-in usage metrics are on the Phase 1 roadmap).
+
+Before exposing TopicForge to *untrusted* MCP clients (hosted endpoints, shared environments), add path isolation and revisit the `TOPICFORGE_ROS2_BIN` policy.
+
+## MVP limitations
+
+- `sample_messages` in live mode uses `ros2 topic echo --once` with a short timeout; topics with no current publisher will return an empty sample.
+- `sample_messages` silently clamps `count` to 50 to keep tool output bounded; requests for more than 50 messages return at most 50 (the `SampleResult.count` field reflects what was actually returned).
+- `analyze_bag` in live mode shells out to `ros2 bag info` and parses its text output. Deep anomaly detection is mock-only for now.
+- No streaming / push subscriptions in the MVP. Tools are strictly request/response.
+- Live adapter is CLI-based, not `rclpy`-based - by design, for portability.
+
+## Roadmap
+
+See [`docs/product-plan.md`](docs/product-plan.md) for the full product trajectory.
+
+Near-term additions on the bench:
+
+- `rclpy`-backed live adapter for faster & richer sampling
+- URDF inspector / validator MCP tools
+- Bag anomaly detection (clock jumps, gaps, dropped frames, TF tree health)
+- Dataset export helpers (rosbag → COCO / HF Datasets)
+- Synthetic data pipeline controller (Blender, Gazebo, Isaac Sim)
+- Hosted MCP endpoint with auth
+
+## Project layout
+
+```
+topicforge-mcp/
+├── README.md                  # You are here
+├── Makefile                   # Common developer tasks
+├── pyproject.toml             # Build & tooling config
+├── .env.example               # Example runtime configuration
+├── docs/
+│   └── product-plan.md        # Product strategy & roadmap
+├── src/topicforge/
+│   ├── __main__.py            # `python -m topicforge`
+│   ├── server/                # MCP bootstrap & lifecycle
+│   ├── tools/                 # MCP tool definitions
+│   ├── services/              # Domain orchestration
+│   ├── adapters/
+│   │   ├── ros2_live/         # `ros2` CLI wrappers
+│   │   └── ros2_mock/         # Deterministic fixtures
+│   ├── models/                # Pydantic schemas
+│   └── config/                # Settings & mode resolution
+└── tests/                     # Pytest suite (mock-only, no ROS2 required)
+```
+
+## License
+
+MIT - see [LICENSE](LICENSE).