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

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

Prerequisites

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

   Copy & paste — that's itCopy

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

2. Deno: For running the GitHub MCP server

   Copy & paste — that's itCopy

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

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

   Copy & paste — that's itCopy

   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:
   Copy & paste — that's itCopy

   pip install -e .

3. Install the official GitHub MCP server:
   Copy & paste — that's itCopy

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

4. Run the setup script:
   Copy & paste — that's itCopy

   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.