Radicle MCP

🚀 Radicle + GitHub MCP Server

A Model Context Protocol (MCP) server setup that offers tools for interacting with both Radicle (peer - to - peer code collaboration) and GitHub via a unified interface.

🚀 Quick Start

To get started with the Radicle + GitHub MCP Server, follow the steps in the Installation section. After installation, you can use the available tools and commands to interact with Radicle and GitHub.

✨ Features

This setup comes with two MCP servers:

🌟 Radicle MCP Server (Python)

• Repository Management: Initialize, clone, and inspect Radicle repositories.
• Synchronization: Sync repositories with the Radicle network.
• Patches & Issues: List and manage patches and issues.
• Node Information: Get node ID and remote information.
• Help System: Access Radicle command documentation.
• 🔄 GitHub Integration: Bidirectional sync of issues and PRs between GitHub and Radicle.

🐙 GitHub MCP Server (Official)

• Repository Operations: Create, fork, clone GitHub repositories.
• Issue Management: Create, update, and manage GitHub issues.
• Pull Requests: Manage pull requests and reviews.
• File Operations: Read, write, and manage repository files.
• Search: Search repositories, issues, and code.
• User Management: Manage user and organization information.

🔗 GitHub ↔ Radicle Synchronization

• Bidirectional Issue Sync: Automatically sync issues between platforms.
• Idempotent Operations: Safe to run multiple times without duplicates.
• Metadata Preservation: Maintains original author, links, and timestamps.
• Mapping Database: Tracks relationships between GitHub and Radicle items.
• MCP Integration: Available as AI assistant tools.

💻 Available Tools

Repository Operations

• rad_init: Initialize a new Radicle repository.
• rad_clone: Clone an existing repository by RID.
• rad_status: Get repository status and information.
• rad_sync: Sync repository with the network.
• rad_push: Push changes to the network.

Collaboration Features

• rad_patch_list: List patches (pull requests) in a repository.
• rad_issue_list: List issues in a repository.
• rad_remote_list: List remotes/nodes for a repository.

Node & Identity

• rad_id: Get your Radicle node ID.
• rad_help: Get help for Radicle commands.

📦 Installation

Prerequisites

1. Radicle CLI: Ensure the rad command is installed and available in your PATH.

   # Install Radicle (see https://radicle.xyz for installation instructions)
   curl -sSf https://install.radicle.xyz | sh
   

2. Deno: For running the GitHub MCP server.

   # Install Deno
   curl -fsSL https://deno.land/install.sh | sh
   

3. Python Environment: Python 3.8+ with the MCP library.

   pip install mcp
   

4. GitHub Personal Access Token: For GitHub integration.

   • Go to https://github.com/settings/tokens.
   • Create a new token with repo, issues, and pull request permissions.
   • Set as environment variable: GITHUB_PERSONAL_ACCESS_TOKEN.

Installation Steps

1. Clone this repository.
2. Install dependencies:

   pip install -e .
   

3. Install the official GitHub MCP server:

   deno install -g --name github-mcp npm:@modelcontextprotocol/server-github
   

4. Run the setup script:

   python setup_mcp.py
   

💻 Usage

Quick Setup

# Set your GitHub token
export GITHUB_PERSONAL_ACCESS_TOKEN=your_token_here

# Run the setup script
python setup_mcp.py

GitHub ↔ Radicle Sync

# Test sync connectivity
python demo_sync.py

# Create a test issue (optional)
python create_test_issue.py

# Run full sync
python github_radicle_sync.py

# Or use CLI interface
python sync_cli.py --repo owner/repo --dry-run
python sync_cli.py --repo owner/repo --issues-only

MCP Integration

The sync functionality is available as MCP tools:

• github_sync_test: Test connectivity.
• github_sync_issues: Sync issues only.
• github_sync_full: Full bidirectional sync.

See SYNC_README.md for detailed sync documentation.

As Standalone Servers

# Radicle MCP Server
python -m radicle_mcp.server

# GitHub MCP Server  
github-mcp

With Claude Desktop

The setup script automatically creates the configuration. Your claude_desktop_config.json will include:

{
  "mcpServers": {
    "radicle-mcp": {
      "command": "/path/to/python",
      "args": ["-m", "radicle_mcp.server"]
    },
    "github-mcp": {
      "command": "/path/to/github-mcp",
      "args": [],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
      }
    }
  }
}

VS Code Integration

This project includes VS Code configuration for debugging the MCP server. Use the provided mcp.json file to connect compatible MCP clients.

💻 Example Commands

Once connected to an MCP client, you can use natural language to interact with both platforms:

Radicle Operations

• "Initialize a new Radicle repository called 'my-project'".
• "Clone the repository with RID rad:z2...".
• "Show me the current patches in this repository".
• "Sync this repository with the network".
• "What's my Radicle node ID?".

GitHub Operations

• "Create a new GitHub repository called 'awesome-project'".
• "List my recent GitHub repositories".
• "Create an issue titled 'Bug fix needed'".
• "Show me open pull requests in my repository".
• "Search for repositories related to 'machine learning'".

Cross-Platform Workflows

• "Publish this Radicle repository to GitHub".
• "Sync issues between Radicle and GitHub".
• "Compare this repository on both platforms".

🔧 Technical Details

Running Tests

python -m pytest tests/

Code Style

black src/
flake8 src/

Project Structure

radicle-mcp/
├── src/radicle_mcp/
│   ├── __init__.py
│   └── server.py          # Main MCP server implementation
├── .vscode/
│   └── mcp.json          # VS Code MCP configuration
├── .github/
│   └── copilot-instructions.md
├── pyproject.toml        # Project configuration
└── README.md

🤝 Contributing

1. Fork the repository.
2. Create a feature branch.
3. Make your changes.
4. Add tests if applicable.
5. Submit a pull request.

📄 License

MIT License - see LICENSE file for details

🔗 Related Links

• Radicle Documentation
• Model Context Protocol
• MCP Python SDK