Radicle MCP

🚀 Radicle + GitHub MCP 服务器

本项目搭建了一个模型上下文协议（MCP）服务器，提供了通过统一接口与 Radicle（点对点代码协作平台）和 GitHub 进行交互的工具。它解决了在不同代码协作平台间操作不便的问题，让开发者能更高效地管理和同步代码仓库。

🚀 快速开始

前提条件

1. Radicle CLI：确保 rad 命令已安装并添加到系统环境变量中。

   # 安装 Radicle（安装说明请参考 https://radicle.xyz ）
   curl -sSf https://install.radicle.xyz | sh
   

2. Deno：用于运行 GitHub MCP 服务器。

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

3. Python 环境：Python 3.8 及以上版本，并安装 MCP 库。

   pip install mcp
   

4. GitHub 个人访问令牌：用于集成 GitHub。
   • 访问 https://github.com/settings/tokens 。
   • 创建一个具有仓库、问题和拉取请求权限的新令牌。
   • 将其设置为环境变量：GITHUB_PERSONAL_ACCESS_TOKEN。

安装步骤

1. 克隆本仓库。
2. 安装依赖：

   pip install -e .
   

3. 安装官方 GitHub MCP 服务器：

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

4. 运行设置脚本：

   python setup_mcp.py
   

使用示例

快速设置

# 设置你的 GitHub 令牌
export GITHUB_PERSONAL_ACCESS_TOKEN=your_token_here

# 运行设置脚本
python setup_mcp.py

GitHub 与 Radicle 同步

# 测试同步连接性
python demo_sync.py

# 创建一个测试问题（可选）
python create_test_issue.py

# 运行全量同步
python github_radicle_sync.py

# 或者使用 CLI 接口
python sync_cli.py --repo owner/repo --dry-run
python sync_cli.py --repo owner/repo --issues-only

MCP 集成

同步功能可作为 MCP 工具使用：

• github_sync_test：测试连接性
• github_sync_issues：仅同步问题
• github_sync_full：全量双向同步

详细的同步文档请参考 SYNC_README.md。

作为独立服务器运行

# Radicle MCP 服务器
python -m radicle_mcp.server

# GitHub MCP 服务器
github-mcp

与 Claude Desktop 集成

设置脚本会自动创建配置文件。你的 claude_desktop_config.json 文件将包含以下内容：

{
  "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 集成

本项目包含用于调试 MCP 服务器的 VS Code 配置。使用提供的 mcp.json 文件连接兼容的 MCP 客户端。

✨ 主要特性

本设置包含两个 MCP 服务器：

🌟 Radicle MCP 服务器（Python）

• 仓库管理：初始化、克隆和检查 Radicle 仓库。
• 同步功能：与 Radicle 网络同步仓库。
• 补丁与问题管理：列出和管理补丁与问题。
• 节点信息：获取节点 ID 和远程信息。
• 帮助系统：访问 Radicle 命令文档。
• 🔄 GitHub 集成：在 GitHub 和 Radicle 之间双向同步问题和拉取请求。

🐙 GitHub MCP 服务器（官方）

• 仓库操作：创建、复刻和克隆 GitHub 仓库。
• 问题管理：创建、更新和管理 GitHub 问题。
• 拉取请求管理：管理拉取请求和评审。
• 文件操作：读取、写入和管理仓库文件。
• 搜索功能：搜索仓库、问题和代码。
• 用户管理：管理用户和组织信息。

🔗 GitHub ↔ Radicle 同步

• 双向问题同步：自动在平台之间同步问题。
• 幂等操作：多次运行安全，不会产生重复数据。
• 元数据保留：保留原始作者、链接和时间戳。
• 映射数据库：跟踪 GitHub 和 Radicle 项目之间的关系。
• MCP 集成：可作为 AI 助手工具使用。

💻 使用示例

可用工具

仓库操作

• rad_init：初始化一个新的 Radicle 仓库。
• rad_clone：通过 RID 克隆现有仓库。
• rad_status：获取仓库状态和信息。
• rad_sync：与网络同步仓库。
• rad_push：将更改推送到网络。

协作功能

• rad_patch_list：列出仓库中的补丁（拉取请求）。
• rad_issue_list：列出仓库中的问题。
• rad_remote_list：列出仓库的远程节点。

节点与身份

• rad_id：获取你的 Radicle 节点 ID。
• rad_help：获取 Radicle 命令的帮助信息。

示例命令

连接到 MCP 客户端后，你可以使用自然语言与两个平台进行交互：

Radicle 操作

• "初始化一个名为 'my-project' 的新 Radicle 仓库"
• "克隆 RID 为 rad:z2... 的仓库"
• "显示此仓库中的当前补丁"
• "将此仓库与网络同步"
• "我的 Radicle 节点 ID 是什么？"

GitHub 操作

• "创建一个名为 'awesome-project' 的新 GitHub 仓库"
• "列出我最近的 GitHub 仓库"
• "创建一个标题为 'Bug fix needed' 的问题"
• "显示我仓库中的开放拉取请求"
• "搜索与 '机器学习' 相关的仓库"

跨平台工作流

• "将此 Radicle 仓库发布到 GitHub"
• "同步 Radicle 和 GitHub 之间的问题"
• "比较此仓库在两个平台上的情况"

🔧 技术细节

运行测试

python -m pytest tests/

代码风格

black src/
flake8 src/

📚 详细文档

项目结构

radicle-mcp/
├── src/radicle_mcp/
│   ├── __init__.py
│   └── server.py          # 主 MCP 服务器实现
├── .vscode/
│   └── mcp.json          # VS Code MCP 配置
├── .github/
│   └── copilot-instructions.md
├── pyproject.toml        # 项目配置
└── README.md

贡献指南

1. 复刻仓库。
2. 创建功能分支。
3. 进行更改。
4. 如有必要，添加测试。
5. 提交拉取请求。

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

相关链接

• Radicle 文档
• 模型上下文协议
• MCP Python SDK