Radicle MCP Server

A Model Context Protocol (MCP) server for Radicle CLI with versioning support.

Features

• Version Detection: Automatically detects Radicle CLI version at startup
• Version Management: Supports semantic versioning with base definitions and incremental updates
• Command Validation: Validates commands against version definitions
• Deprecation Handling: Warns about deprecated/obsolete features
• Hybrid Tool Approach: Dedicated tools for common commands + generic executor
• Error Handling: Structured error responses with JSON output when possible

Supported Commands

Dedicated Tools

The server automatically generates dedicated MCP tools for all Radicle commands and subcommands based on the installed version. For Radicle 1.5.0, this includes 71 dedicated tools:

Main Commands:

• rad_auth, rad_block, rad_checkout, rad_clean, rad_clone
• rad_cob, rad_config, rad_follow, rad_fork, rad_help
• rad_id, rad_inbox, rad_init, rad_inspect, rad_issue
• rad_ls, rad_node, rad_patch, rad_path, rad_remote
• rad_seed, rad_self, rad_stats, rad_sync, rad_unblock
• rad_unfollow, rad_unseed

Subcommand Examples:

• rad_issue_open, rad_issue_list, rad_issue_show, rad_issue_edit
• rad_patch_open, rad_patch_list, rad_patch_show, rad_patch_merge
• rad_node_start, rad_node_stop, rad_node_status, rad_node_logs
• rad_config_get, rad_config_set, rad_config_schema
• rad_cob_create, rad_cob_show, rad_cob_update, rad_cob_log

Generic Tool

• rad_execute: Execute any rad command (fallback for unsupported commands)

Version Support

• Supported Versions: 1.1.0, 1.2.0, 1.3.0, 1.4.0, 1.5.0
• Version Resolution: Falls back to closest available version if exact match not found
• Warning System: One-time warnings for version mismatches and deprecated features
• Dynamic Tool Generation: Tools are generated based on the specific version's capabilities

Installation

PyPI (Recommended)

pip install radicle-mcp-server

Development

# Clone the repository
git clone <repository-url>

# Install dependencies
cd radicle-mcp-server
uv sync

Running the Server

Using Just (Recommended)

just run                    # Stdio transport (default)
just run-http              # HTTP transport on localhost:8000

Using UV Directly

uv run python -m src.server                    # Stdio transport
uv run python -m src.server --transport http   # HTTP transport

MCP Client Configuration

OpenCode

Add to your MCP configuration:

{
  "mcpServers": {
    "radicle": {
      "command": "radicle-mcp-server"
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "radicle": {
      "command": "radicle-mcp-server"
    }
  }
}

Development (from source)

If you're developing from source, use:

{
  "mcpServers": {
    "radicle": {
      "command": "uv",
      "args": ["run", "python", "-m", "src.server"],
      "cwd": "/path/to/radicle-mcp-server"
    }
  }
}

Usage

The server provides MCP tools that can be used with any MCP-compatible client. It automatically detects the installed Radicle CLI version and adapts its behavior accordingly.

Development

This project uses:

• FastMCP: For MCP server implementation
• uv: For dependency management
• Python 3.13+: For modern type annotations

Versioning System

The versioning system uses YAML definitions stored in src/definitions/:

• radicle-1.1.0.yaml through radicle-1.5.0.yaml: Complete command definitions for each version
• schema.py: Validation schema and data structures
• Each version file contains all available commands, subcommands, options, and examples

This design allows for efficient handling of semantic versioning while maintaining backward compatibility.