Radicle + GitHub MCP Server

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

Features

This setup includes 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

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

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"

Development

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