Radicle Mcp

开发 Python

🚀 Radicle + GitHub MCP 服务器

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

🚀 快速开始

前提条件

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

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

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

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

Python 环境：Python 3.8 及以上版本，并安装 MCP 库。
```
pip install mcp
```
GitHub 个人访问令牌：用于集成 GitHub。
- 访问 https://github.com/settings/tokens 。
- 创建一个具有仓库、问题和拉取请求权限的新令牌。
- 将其设置为环境变量：GITHUB_PERSONAL_ACCESS_TOKEN。

安装步骤

克隆本仓库。
安装依赖：
```
pip install -e .
```

安装官方 GitHub MCP 服务器：

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

运行设置脚本：
```
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

贡献指南

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

📄 许可证

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