diff --git a/README.md b/README.md index 5266f16..af9ada8 100644 --- a/README.md +++ b/README.md @@ -1,72 +1,204 @@ -# GR-MCP: A gnuradio MCP Server +# GR-MCP: GNU Radio MCP Server -[![Python Version](https://img.shields.io/badge/python-3.13%2B-blue.svg)](https://www.python.org/downloads/release/python-3130/) +[![Python Version](https://img.shields.io/badge/python-3.14%2B-blue.svg)](https://www.python.org/downloads/) -[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/yoelbassin/gnuradioMCP)](https://archestra.ai/mcp-catalog/yoelbassin__gnuradiomcp) +**GR-MCP** is a FastMCP server for [GNU Radio](https://www.gnuradio.org/) that enables programmatic, automated, and AI-driven creation and control of GNU Radio flowgraphs. It exposes 36 MCP tools for building, modifying, validating, running, and monitoring `.grc` files. - -**GNURadio MCP Server** is a modern, extensible Machine Control Protocol (MCP) server for [GNURadio](https://www.gnuradio.org/), enabling programmatic, automated, and AI-driven creation of GNURadio flowgraphs. Designed for seamless integration with Large Language Models (LLMs), automation frameworks, and custom clients, it empowers you to generate `.grc` files and control SDR workflows at scale. - -> **Why GNURadio MCP Server?** -> - Automate SDR workflows and flowgraph generation -> - Integrate with LLMs, bots, and custom tools -> - Build, modify, and validate flowgraphs programmatically -> - Save time and reduce manual errors in SDR prototyping +> **Why GR-MCP?** +> - Build and validate flowgraphs programmatically +> - Run flowgraphs in Docker containers with XML-RPC control +> - Adjust variables in real-time without restarting +> - Collect Python code coverage from containerized flowgraphs +> - Integrate with LLMs, automation frameworks, and custom tools ## Features -- ๐ŸŒ **MCP API**: Exposes a robust MCP interface for GNURadio -- ๐Ÿ› ๏ธ **Programmatic Flowgraph Creation**: Build, edit, and save `.grc` files from code or automation -- ๐Ÿค– **LLM & Automation Ready**: Designed for AI and automation integration -- ๐Ÿงฉ **Extensible**: Modular architecture for easy extension and customization -- ๐Ÿ“ **Example Flowgraphs**: Includes ready-to-use `.grc` examples in the `misc/` directory -- ๐Ÿงช **Tested**: Comprehensive unit tests with `pytest` + +### Flowgraph Building (15 tools) +Build, edit, and validate `.grc` files programmatically: +- `get_blocks` / `make_block` / `remove_block` - Block management +- `get_block_params` / `set_block_params` - Parameter control +- `get_block_sources` / `get_block_sinks` - Port inspection +- `get_connections` / `connect_blocks` / `disconnect_blocks` - Wiring +- `validate_block` / `validate_flowgraph` / `get_all_errors` - Validation +- `save_flowgraph` - Save to `.grc` file +- `get_all_available_blocks` - List available block types + +### Runtime Control (11 tools) +Run flowgraphs in Docker containers with headless QT rendering: +- `launch_flowgraph` - Start a flowgraph in a container (Xvfb + optional VNC) +- `list_containers` / `stop_flowgraph` / `remove_flowgraph` - Container lifecycle +- `connect` / `connect_to_container` / `disconnect` - XML-RPC connection +- `list_variables` / `get_variable` / `set_variable` - Real-time variable control +- `start` / `stop` / `lock` / `unlock` - Flowgraph execution control +- `capture_screenshot` / `get_container_logs` - Visual feedback +- `get_status` - Connection and container status + +### Coverage Collection (4 tools) +Collect Python code coverage from containerized flowgraphs: +- `collect_coverage` - Gather coverage data after flowgraph stops +- `generate_coverage_report` - Generate HTML/XML/JSON reports +- `combine_coverage` - Aggregate coverage across multiple runs +- `delete_coverage` - Clean up coverage data + + +## Requirements + +- Python >= 3.14 +- GNU Radio (tested with GRC v3.10.12.0) +- Docker (optional, for runtime control features) +- UV package manager ## Quickstart -### Requirements -- Python >= 3.13 -- GNURadio (Tested with GNURadio Companion v3.10.12.0) -- UV +### 1. Clone and setup -### Usage -1. **Clone the repository** -```bash -git clone https://github.com/yoelbassin/gr-mcp -``` - -2. [**Install GNURadio**](https://wiki.gnuradio.org/index.php/InstallingGR) - -3. **Set up a UV environment** ```bash +git clone https://github.com/rsp2k/gr-mcp cd gr-mcp -uv venv --system-site-packages -``` - > The `--system-site-packages` flag is required because GNURadio installs the `gnuradio` Python package globally. -4. **Add the MCP server configuration to your client configuration.** For example, for Claude Desktop or Cursor: +# Create venv with system site-packages (required for gnuradio) +uv venv --system-site-packages --python 3.14 +uv sync +``` + +### 2. Configure your MCP client + +Add to Claude Desktop, Cursor, or other MCP client config: + ```json -"mcpServers": { +{ + "mcpServers": { "gr-mcp": { "command": "uv", - "args": [ - "--directory", - "/path/to/gr-mcp", - "run", - "main.py" - ] + "args": ["--directory", "/path/to/gr-mcp", "run", "main.py"] } } +} ``` -## Development -Install development dependencies and run tests with: +### 3. (Optional) Build Docker images for runtime control + ```bash -pip install -e ".[dev]" +# Build the runtime image (Xvfb + VNC + ImageMagick) +docker build -f docker/Dockerfile.gnuradio-runtime -t gnuradio-runtime:latest docker/ + +# Build the coverage image (adds python3-coverage) +docker build -f docker/Dockerfile.gnuradio-coverage -t gnuradio-coverage:latest docker/ +``` + + +## Usage Examples + +### Building a flowgraph + +```python +# Create a signal generator block +make_block(block_type="analog_sig_source_x", name="sig_source") + +# Set parameters +set_block_params(block_name="sig_source", params={ + "freq": "1000", + "amplitude": "0.5", + "waveform": "analog.GR_COS_WAVE" +}) + +# Connect blocks +connect_blocks( + source_block="sig_source", source_port="0", + sink_block="audio_sink", sink_port="0" +) + +# Validate and save +validate_flowgraph() +save_flowgraph(path="/tmp/my_flowgraph.grc") +``` + +### Running a flowgraph with runtime control + +```python +# Launch in Docker container +launch_flowgraph( + flowgraph_path="/path/to/flowgraph.py", + name="my-sdr", + xmlrpc_port=8080, + enable_vnc=True # Optional: VNC on port 5900 +) + +# Connect and control +connect_to_container(name="my-sdr") +list_variables() # See available variables +set_variable(name="freq", value=2.4e9) # Tune in real-time + +# Visual feedback +capture_screenshot(name="my-sdr") # Get QT GUI screenshot +get_container_logs(name="my-sdr") # Check for errors + +# Clean up +stop_flowgraph(name="my-sdr") +remove_flowgraph(name="my-sdr") +``` + +### Collecting code coverage + +```python +# Launch with coverage enabled +launch_flowgraph( + flowgraph_path="/path/to/flowgraph.py", + name="coverage-test", + enable_coverage=True +) + +# Run your test scenario... +# Then stop (graceful shutdown required for coverage data) +stop_flowgraph(name="coverage-test") + +# Collect and report +collect_coverage(name="coverage-test") +generate_coverage_report(name="coverage-test", format="html") +``` + + +## Development + +```bash +# Install dev dependencies +uv sync --all-extras + +# Run tests pytest + +# Run with coverage +pytest --cov=gnuradio_mcp --cov-report=term-missing + +# Pre-commit hooks +pre-commit run --all-files +``` + + +## Architecture + +``` +main.py # FastMCP app entry point +src/gnuradio_mcp/ +โ”œโ”€โ”€ models.py # Pydantic models for all tools +โ”œโ”€โ”€ middlewares/ +โ”‚ โ”œโ”€โ”€ platform.py # GNU Radio Platform wrapper +โ”‚ โ”œโ”€โ”€ flowgraph.py # Flowgraph block/connection management +โ”‚ โ”œโ”€โ”€ block.py # Block parameter/port access +โ”‚ โ”œโ”€โ”€ docker.py # Docker container lifecycle +โ”‚ โ””โ”€โ”€ xmlrpc.py # XML-RPC variable control +โ””โ”€โ”€ providers/ + โ”œโ”€โ”€ base.py # PlatformProvider (flowgraph tools) + โ”œโ”€โ”€ mcp.py # McpPlatformProvider (registers tools) + โ”œโ”€โ”€ runtime.py # RuntimeProvider (Docker/XML-RPC) + โ””โ”€โ”€ mcp_runtime.py # McpRuntimeProvider (registers tools) ``` ## Project Status -**In active development.** Core server functionality is available, but the API and features are evolving. Your feedback and contributions are highly valued! + +**Active development.** Core flowgraph building is stable. Runtime control (Docker + XML-RPC) is Phase 1 complete. Coverage collection is functional. + +Contributions and feedback welcome!