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

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

Deno: For running the GitHub MCP server

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

Python Environment: Python 3.8+ with the MCP library
```
pip install mcp
```
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

Clone this repository
Install dependencies:
```
pip install -e .
```

Install the official GitHub MCP server:

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

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

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

License

MIT License - see LICENSE file for details

Radicle + GitHub