使用说明

SVN MCP服务器

用于Subversion（SVN）集成的完整MCP（模型上下文协议）服务器，旨在让AI代理高效地管理SVN存储库。

🎯 特性

✅ 基本存储库操作：信息、状态、日志、差异、签出、更新
✅ 文件管理：添加、提交、删除、还原
✅ 维护工具：清理
🔄 分行管理：（开发中）
🔄 高级操作：合并、切换、属性（开发中）
🔄 分析工具：责任、冲突检测（开发中）
🔄 批量操作：（开发中）

📋 需求

Node.js >= 18.0.0
颠覆（SVN） 已安装并可在PATH上使用
TypeScript （用于发展）

🔍 检测SVN安装

检查是否安装了SVN

# Basic command to check SVN
svn --version

# Check the full path of the executable
where svn        # Windows
which svn        # Linux/Mac

# Check the full SVN client
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

🛠️ 高级诊断

# Check the system PATH
echo $PATH                    # Linux/Mac
echo %PATH%                   # Windows CMD
$env:PATH                     # Windows PowerShell

# Search for SVN executables on the system
find / -name "svn" 2>/dev/null           # Linux
Get-ChildItem -Path C:\ -Name "svn.exe" -Recurse -ErrorAction SilentlyContinue  # Windows PowerShell

# Check the specific client version
svn --version | head -1       # Get just the first line with the version

💾 在Windows上安装SVN

选项1：包管理器

# Using Chocolatey (Recommended)
choco install subversion

# Using winget
winget install CollabNet.Subversion

# Using Scoop
scoop install subversion

选项2：官方安装人员

小乌龟SVN （包括命令行客户端）：

https://tortoisesvn.net/downloads.html
✅ Includes GUI and CLI clients
✅ Windows Explorer integration

Svn图像 （仅限命令行）：

https://sliksvn.com/download/
✅ Lightweight (CLI only)
✅ Ideal for automation

CollabNet颠覆:

https://www.collab.net/downloads/subversion
✅ Enterprise version
✅ Commercial support available

选项3:Visual Studio或Git for Windows

# If you have Git for Windows installed, it can include SVN
git svn --version

# Visual Studio can also include SVN
# Go to: Visual Studio Installer > Modify > Individual Components > 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 (Recommended)
brew install subversion

# MacPorts
sudo port install subversion

# From Xcode Command Line Tools (may already be included)
xcode-select --install

🔧 安装后配置SVN

检查全局配置

# Show current configuration
svn config --list

# Configure the global user
svn config --global auth:username your_username

# Configure the default editor
svn config --global editor "code --wait"     # VS Code
svn config --global editor "notepad"         # Windows Notepad
svn config --global editor "nano"            # Linux/Mac nano

检查存储库访问权限

# Test connection to a repository (without checking out)
svn list https://svn.example.com/repo/trunk

# Test with specific credentials
svn list https://svn.example.com/repo/trunk --username user --password password

🚀 安装

来自NPM

npm install -g @grec0/mcp-svn

本地开发

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

⚙️ 配置

环境变量

变量	描述	默认值
`SVN_PATH`	SVN可执行文件的路径	`svn`
`SVN_WORKING_DIRECTORY`	本地工作副本目录	`process.cwd()`
`SVN_URL` （别名： `SVN_REPOSITORY_URL`)	存储库URL。启用仅URL工作流和 `/trunk/...` 目标分辨率	-
`SVN_USERNAME`	身份验证用户	-
`SVN_PASSWORD`	身份验证密码	-
`SVN_TIMEOUT`	超时（毫秒）	`30000`

SVN_WORKING_DIRECTORY 和 SVN_URL 是独立的——要么两者都设置。配置了这两种操作后，本地操作(svn_status, svn_commit, ...）在工作副本中运行，以及支持URL的工具(svn_cat, svn_list, svn_info, svn_log, svn_diff)可以用以下方式调用：

完整URL(https://svn.example.com/repo/trunk/file.sql)
以开头的repo相对路径 / (/trunk/file.sql)--加入 SVN_URL
本地路径--根据工作副本解析

MCP配置示例

{
  "mcpServers": {
    "svn": {
      "command": "npx",
      "args": ["@grec0/mcp-svn"],
      "env": {
        "SVN_PATH": "svn",
        "SVN_WORKING_DIRECTORY": "C:/path/to/working/copy",
        "SVN_URL": "https://svn.example.com/repo",
        "SVN_USERNAME": "your_username",
        "SVN_PASSWORD": "your_password"
      }
    }
  }
}

🛠️ 可用工具

基本操作

`svn_health_check`

检查SVN系统和工作副本的健康状态。

svn_health_check()

`svn_info`

获取有关工作副本或特定文件的详细信息。

svn_info(path?: string)

`svn_status`

显示工作副本中文件的状态。

svn_status(path?: string, showAll?: boolean)

`svn_log`

显示存储库的提交历史记录。

svn_log(path?: string, limit?: number, revision?: string)

`svn_diff`

显示文件修订之间的差异。

svn_diff(path?: string, oldRevision?: string, newRevision?: string)

存储库操作

`svn_checkout`

查看SVN存储库。

svn_checkout(
  url: string,
  path?: string,
  revision?: number | "HEAD",
  depth?: "empty" | "files" | "immediates" | "infinity",
  force?: boolean,
  ignoreExternals?: boolean
)

`svn_update`

从存储库更新工作副本。

svn_update(
  path?: string,
  revision?: number | "HEAD" | "BASE" | "COMMITTED" | "PREV",
  force?: boolean,
  ignoreExternals?: boolean,
  acceptConflicts?: "postpone" | "base" | "mine-conflict" | "theirs-conflict" | "mine-full" | "theirs-full"
)

文件管理

`svn_add`

将文件添加到版本控制中。

svn_add(
  paths: string | string[],
  force?: boolean,
  noIgnore?: boolean,
  parents?: boolean,
  autoProps?: boolean,
  noAutoProps?: boolean
)

`svn_commit`

将更改提交到存储库。

svn_commit(
  message: string,
  paths?: string[],
  file?: string,
  force?: boolean,
  keepLocks?: boolean,
  noUnlock?: boolean
)

`svn_delete`

从版本控制中删除文件。

svn_delete(
  paths: string | string[],
  message?: string,
  force?: boolean,
  keepLocal?: boolean
)

`svn_revert`

还原文件上的本地更改。

svn_revert(paths: string | string[])

维护工具

`svn_cleanup`

清理中断操作的工作副本。

svn_cleanup(path?: string)

📖 使用示例

检查系统状态

// Check that SVN is available and the working copy is valid
const healthCheck = await svn_health_check();

获取存储库信息

// General working copy information
const info = await svn_info();

// Information about a specific file
const fileInfo = await svn_info("src/main.js");

显示文件状态

// Status of all files
const status = await svn_status();

// Status including remote information
const fullStatus = await svn_status(null, true);

查看存储库

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

提交更改

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

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

🧪 测试

# Run tests
npm test

# Tests with coverage
npm run test -- --coverage

# Tests in watch mode
npm run test -- --watch

🏗️ 发展

可用脚本

# Build TypeScript
npm run build

# Development mode
npm run dev

# Watch mode
npm run watch

# MCP Inspector
npm run inspector

# Tests
npm test

# Publish a new version
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 types
│   ├── utils.ts      # SVN utilities
│   └── version.ts    # Package version
├── tools/
│   └── svn-service.ts # Main SVN service
├── tests/
│   └── integration.test.ts # Integration tests
└── README.md

📊 开发状态

看 SVN_MCP_实现.md 完整实施清单的文件。

当前进展： 第一阶段完成（基本操作）✅

下一阶段：

分行管理（分行）
高级操作（合并、切换）
分析工具
批量操作

🐛 故障排除

未找到SVN

Error: SVN is not available in the system PATH

解决方案： 安装SVN并确保它在系统路径上。

不是工作副本

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许可证-请参阅许可证了解更多详情。

🤝 贡献

分叉项目
创建要素分支(git checkout -b feature/new-feature)
提交您的更改(git commit -am 'Add new feature')
推到分支(git push origin feature/new-feature)
打开拉取请求

📞 支持

问题： GitHub问题
文档： 维基工程
电子邮件： soporte@grec0.dev