MCP Svn

🚀 SVN MCP 服務器

SVN MCP 服務器是一個完整的 MCP（模型上下文協議）服務器，用於與 Subversion (SVN) 集成。它旨在讓人工智能代理能夠高效地管理 SVN 倉庫。

✨ 主要特性

• ✅ 倉庫基本操作：info、status、log、diff、checkout、update
• ✅ 文件管理：add、commit、delete、revert
• ✅ 維護工具：cleanup
• 🔄 分支管理：（開發中）
• 🔄 高級操作：merge、switch、properties（開發中）
• 🔄 分析工具：blame、conflict detection（開發中）
• 🔄 批量操作：（開發中）

📦 安裝指南

安裝要求

• Node.js >= 18.0.0
• Subversion (SVN) 已安裝並添加到系統環境變量 PATH 中
• TypeScript（用於開發）

🔍 檢測 SVN 安裝情況

驗證 SVN 是否安裝

# 驗證 SVN 的基本命令
svn --version

# 驗證可執行文件的完整路徑
where svn        # Windows
which svn        # Linux/Mac

# 驗證完整的 SVN 客戶端
svn --version --verbose

如果 SVN 正確安裝，預期輸出如下：

svn, version 1.14.x (r1876290)
   compiled Apr 13 2023, 17:22:07 on x86_64-pc-mingw32

Copyright (C) 2023 The Apache Software Foundation.
This software consists of contributions made by many people;
see the NOTICE file for more information.
Subversion is open source software, see http://subversion.apache.org/

❌ 如果 SVN 未安裝，常見錯誤如下：

# Windows
'svn' is not recognized as an internal or external command

# Linux/Mac  
svn: command not found
bash: svn: command not found

🛠️ 高級診斷

# 驗證系統的 PATH
echo $PATH                    # Linux/Mac
echo %PATH%                   # Windows CMD
$env:PATH                     # Windows PowerShell

# 在系統中查找 SVN 可執行文件
find / -name "svn" 2>/dev/null           # Linux
Get-ChildItem -Path C:\ -Name "svn.exe" -Recurse -ErrorAction SilentlyContinue  # Windows PowerShell

# 驗證客戶端的特定版本
svn --version | head -1       # 僅獲取包含版本的第一行

💾 在 Windows 上安裝 SVN

選項 1：使用包管理器

# 使用 Chocolatey（推薦）
choco install subversion

# 使用 winget
winget install CollabNet.Subversion

# 使用 Scoop
scoop install subversion

選項 2：使用官方安裝程序

1. TortoiseSVN（包含命令行客戶端）：

   https://tortoisesvn.net/downloads.html
   ✅ 包含 GUI 和 CLI 客戶端
   ✅ 與 Windows 資源管理器集成
   

2. SlikSVN（僅命令行）：

   https://sliksvn.com/download/
   ✅ 輕量級（僅 CLI）
   ✅ 適合自動化操作
   

3. CollabNet Subversion：

   https://www.collab.net/downloads/subversion
   ✅ 企業版
   ✅ 提供商業支持
   

選項 3：使用 Visual Studio 或 Git for Windows

# 如果你安裝了 Git for Windows，它可能包含 SVN
git svn --version

# Visual Studio 也可能包含 SVN
# 轉到：Visual Studio 安裝程序 > 修改 > 單個組件 > Subversion

🐧 在 Linux 上安裝 SVN

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install subversion

# CentOS/RHEL/Fedora
sudo yum install subversion        # CentOS 7
sudo dnf install subversion        # CentOS 8/Fedora

# Arch Linux
sudo pacman -S subversion

# Alpine Linux
sudo apk add subversion

🍎 在 macOS 上安裝 SVN

# Homebrew（推薦）
brew install subversion

# MacPorts
sudo port install subversion

# 從 Xcode 命令行工具（可能已包含）
xcode-select --install

🔧 安裝後配置 SVN

驗證全局配置

# 查看當前配置
svn config --list

# 配置全局用戶
svn config --global auth:username tu_usuario

# 配置默認編輯器
svn config --global editor "code --wait"     # VS Code
svn config --global editor "notepad"         # Windows 記事本
svn config --global editor "nano"            # Linux/Mac nano

驗證對倉庫的訪問

# 測試與倉庫的連接（不進行檢出）
svn list https://svn.ejemplo.com/repo/trunk

# 使用特定憑據進行測試
svn list https://svn.ejemplo.com/repo/trunk --username usuario --password contraseña

從 NPM 安裝

npm install -g @grec0/mcp-svn

本地開發安裝

git clone https://github.com/gcorroto/mcp-svn.git
cd mcp-svn
npm install
npm run build

⚙️ 配置

環境變量

MCP 配置示例

{
  "mcpServers": {
    "svn": {
      "command": "npx",
      "args": ["@grec0/mcp-svn"],
      "env": {
        "SVN_PATH": "svn",
        "SVN_WORKING_DIRECTORY": "/path/to/working/copy",
        "SVN_USERNAME": "tu_usuario",
        "SVN_PASSWORD": "tu_contraseña"
      }
    }
  }
}

💻 使用示例

基礎用法

驗證系統狀態

// 驗證 SVN 是否可用以及工作副本是否有效
const healthCheck = await svn_health_check();

獲取倉庫信息

// 工作副本的一般信息
const info = await svn_info();

// 特定文件的信息
const fileInfo = await svn_info("src/main.js");

查看文件狀態

// 所有文件的狀態
const status = await svn_status();

// 包含遠程信息的狀態
const fullStatus = await svn_status(null, true);

檢出倉庫

const checkout = await svn_checkout(
  "https://svn.example.com/repo/trunk",
  "local-copy",
  "HEAD",
  "infinity",
  false,
  false
);

提交更改

// 添加文件
await svn_add(["src/new-file.js", "docs/readme.md"], { parents: true });

// 提交
await svn_commit(
  "Add new feature and documentation",
  ["src/new-file.js", "docs/readme.md"]
);

高級用法

# 運行測試
npm test

# 帶覆蓋率的測試
npm run test -- --coverage

# 監聽模式下的測試
npm run test -- --watch

🧪 測試

# 運行測試
npm test

# 帶覆蓋率的測試
npm run test -- --coverage

# 監聽模式下的測試
npm run test -- --watch

🏗️ 開發

可用腳本

# 編譯 TypeScript
npm run build

# 開發模式
npm run dev

# 監聽模式
npm run watch

# MCP 檢查器
npm run inspector

# 測試
npm test

# 發佈新版本
npm run release:patch
npm run release:minor
npm run release:major

項目結構

svn-mcp/
├── package.json
├── tsconfig.json
├── jest.config.js
├── index.ts
├── common/
│   ├── types.ts      # TypeScript 類型
│   ├── utils.ts      # SVN 實用工具
│   └── version.ts    # 包版本
├── tools/
│   └── svn-service.ts # 主要的 SVN 服務
├── tests/
│   └── integration.test.ts # 集成測試
└── README.md

📊 開發狀態

查看 SVN_MCP_IMPLEMENTATION.md 文件以獲取完整的實現清單。

當前進度：第一階段完成（基本操作）✅

後續階段：

• 分支管理（branching）
• 高級操作（merge、switch）
• 分析工具
• 批量操作

🐛 故障排除

未找到 SVN

Error: SVN is not available in the system PATH

解決方案：安裝 SVN 並確保其在系統的 PATH 中。

不是工作副本

Error: Failed to get SVN info: svn: warning: W155007: '.' is not a working copy

解決方案：導航到一個 SVN 工作副本目錄或先進行檢出操作。

身份驗證問題

Error: svn: E170001: Authentication failed

解決方案：配置環境變量 SVN_USERNAME 和 SVN_PASSWORD。

長時間操作超時

Error: Command timeout after 30000ms

解決方案：增加 SVN_TIMEOUT 的值。

📄 許可證

本項目採用 MIT 許可證，詳情請查看 LICENSE 文件。

🤝 貢獻

1. Fork 本項目
2. 創建功能分支 (git checkout -b feature/nueva-caracteristica)
3. 提交更改 (git commit -am 'Add nueva caracteristica')
4. 將分支推送到遠程 (git push origin feature/nueva-caracteristica)
5. 創建 Pull Request

📞 支持

• 問題反饋：GitHub Issues
• 文檔：項目 Wiki
• 郵箱：soporte@grec0.dev