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