Metadata-Version: 2.4
Name: ros2-image-mcp
Version: 0.1.0
Summary: MCP server (FastMCP) exposing ROS 2 image topics to VLM agents
Author: madz
Keywords: mcp,ros2,robotics,vlm,fastmcp,vision
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastmcp>=2.0
Requires-Dist: numpy>=1.24
Requires-Dist: opencv-python-headless>=4.8
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Provides-Extra: langgraph-demo
Requires-Dist: langgraph>=0.2; extra == "langgraph-demo"
Requires-Dist: langchain-core>=0.3; extra == "langgraph-demo"
Requires-Dist: langchain-google-genai>=2.0; extra == "langgraph-demo"
Requires-Dist: langchain-mcp-adapters>=0.1; extra == "langgraph-demo"
Requires-Dist: python-dotenv>=1.0; extra == "langgraph-demo"

# ros2-image-mcp

[MCP](https://modelcontextprotocol.io/) server ([FastMCP](https://github.com/jlowin/fastmcp)) that exposes ROS 2 [`sensor_msgs/Image`](https://docs.ros2.org/latest/api/sensor_msgs/msg/Image.html) topics to VLMs and agents.

**Tools:** `get_latest_ros_image` · `get_recent_ros_image_frames`

## Requirements

- ROS 2 sourced (`source /opt/ros/<distro>/setup.bash`)
- Python 3.10+

## Install

```bash
source /opt/ros/humble/setup.bash   # or your distro
cd /path/to/ros2_img_mcp
pip install -U pip setuptools
pip install -e .
```

Optional demo extras: `pip install -e ".[langgraph-demo]"`

## Quick start

1. **Publish images** on a topic (synthetic test pattern, or a real camera):

   ```bash
   python3 scripts/publish_test_image.py --topic /test/camera/image
   # webcam example: add --device 4   (for /dev/video4)
   ```

2. **Run the MCP server** (separate terminal, ROS sourced):

   ```bash
   ros2-image-mcp --default-topic /test/camera/image
   ```

3. **Point your MCP client** at the server — **stdio** (default above) or **HTTP**:

   ```bash
   ros2-image-mcp --default-topic /test/camera/image --transport http --port 8012
   ```

   HTTP endpoint: `http://127.0.0.1:8012/mcp` (path `/mcp` by default).

**Cursor (stdio)** — ROS must be sourced inside the command:

```json
{
  "mcpServers": {
    "ros2-camera": {
      "command": "bash",
      "args": [
        "-lc",
        "source /opt/ros/humble/setup.bash && ros2-image-mcp --default-topic /test/camera/image"
      ]
    }
  }
}
```

**LangGraph-style HTTP** — `transport: "http"` and `url: "http://127.0.0.1:8012/mcp"` (or `streamable_http` if your client expects that name; URL unchanged).


## Limitations

- Depth / float formats (e.g. `32FC1`) are **not** converted; use an RGB topic or encode to `png`/`jpeg` on the ROS side.
- Very large images are heavy on MCP payloads; consider downscaling in ROS if needed.

---

More detail : **[DEVELOPERS.md](DEVELOPERS.md)**
