docs: update README with runtime and coverage features
- Document all 36 MCP tools (was 15) - Add Runtime Control section (11 tools for Docker/XML-RPC) - Add Coverage Collection section (4 tools) - Update Python version to 3.14+ - Add Docker image build instructions - Reorganize Features section with tool summaries - Update usage examples for all feature areas
This commit is contained in:
parent
bfab802e05
commit
1b57ea8c35
222
README.md
222
README.md
@ -1,72 +1,204 @@
|
||||
# GR-MCP: A gnuradio MCP Server
|
||||
# GR-MCP: GNU Radio MCP Server
|
||||
|
||||
[](https://www.python.org/downloads/release/python-3130/)
|
||||
[](https://www.python.org/downloads/)
|
||||
|
||||
[](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!
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user