SVN MCP Server

Một máy chủ MCP để tích hợp và quản lý các kho lưu trữ Subversion (SVN), cho phép các tác nhân AI thực hiện các tác vụ kiểm soát phiên bản.

GitHub

Tài liệu

SVN MCP Server

A complete MCP (Model Context Protocol) server for Subversion (SVN) integration, designed to let AI agents manage SVN repositories efficiently.

🎯 Features

✅ Basic repository operations: info, status, log, diff, checkout, update
✅ File management: add, commit, delete, revert
✅ Maintenance tools: cleanup
🔄 Branch management: (In development)
🔄 Advanced operations: merge, switch, properties (In development)
🔄 Analysis tools: blame, conflict detection (In development)
🔄 Batch operations: (In development)

📋 Requirements

Node.js >= 18.0.0
Subversion (SVN) installed and available on PATH
TypeScript (for development)

🔍 Detecting the SVN installation

Check whether SVN is installed

# 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

Expected output if SVN is correctly installed:

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/

❌ Common errors if SVN is NOT installed:

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

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

🛠️ Advanced diagnostics

# 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

💾 Installing SVN on Windows

Option 1: Package managers

# Using Chocolatey (Recommended)
choco install subversion

# Using winget
winget install CollabNet.Subversion

# Using Scoop
scoop install subversion

Option 2: Official installers

TortoiseSVN (includes the command-line client):

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

SlikSVN (command line only):

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

CollabNet Subversion:

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

Option 3: Visual Studio or 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

🐧 Installing SVN on Linux

# 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

🍎 Installing SVN on macOS

# Homebrew (Recommended)
brew install subversion

# MacPorts
sudo port install subversion

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

🔧 Configuring SVN after installation

Check the global configuration

# 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

Check repository access

# 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

🚀 Installation

From NPM

npm install -g @grec0/mcp-svn

Local Development

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

⚙️ Configuration

Environment Variables

Variable	Description	Default
`SVN_PATH`	Path to the SVN executable	`svn`
`SVN_WORKING_DIRECTORY`	Local working copy directory	`process.cwd()`
`SVN_URL` (alias: `SVN_REPOSITORY_URL`)	Repository URL. Enables URL-only workflows and `/trunk/...` target resolution	-
`SVN_USERNAME`	Authentication user	-
`SVN_PASSWORD`	Authentication password	-
`SVN_TIMEOUT`	Timeout in milliseconds	`30000`

SVN_WORKING_DIRECTORY and SVN_URL are independent — set either or both. With both configured, local operations (svn_status, svn_commit, ...) run in the working copy, and URL-capable tools (svn_cat, svn_list, svn_info, svn_log, svn_diff) can be called with:

a full URL (https://svn.example.com/repo/trunk/file.sql)
a repo-relative path starting with / (/trunk/file.sql) — joined with SVN_URL
a local path — resolved against the working copy

Example MCP Configuration

{
  "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"
      }
    }
  }
}

🛠️ Available Tools

Basic Operations

`svn_health_check`

Check the health status of the SVN system and working copy.

svn_health_check()

`svn_info`

Get detailed information about the working copy or a specific file.

svn_info(path?: string)

`svn_status`

Show the status of files in the working copy.

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

`svn_log`

Show the commit history of the repository.

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

`svn_diff`

Show differences between file revisions.

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

Repository Operations

`svn_checkout`

Check out an SVN repository.

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

`svn_update`

Update the working copy from the repository.

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"
)

File Management

`svn_add`

Add files to version control.

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

`svn_commit`

Commit changes to the repository.

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

`svn_delete`

Remove files from version control.

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

`svn_revert`

Revert local changes on files.

svn_revert(paths: string | string[])

Maintenance Tools

`svn_cleanup`

Clean up the working copy from interrupted operations.

svn_cleanup(path?: string)

📖 Usage Examples

Check the system status

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

Get repository information

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

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

Show file status

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

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

Check out a repository

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

Commit changes

// 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"]
);

🧪 Testing

# Run tests
npm test

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

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

🏗️ Development

Available scripts

# 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

Project structure

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

📊 Development Status

See the SVN_MCP_IMPLEMENTATION.md file for the full implementation checklist.

Current progress: Stage 1 complete (Basic Operations) ✅

Next stages:

Branch management (branching)
Advanced operations (merge, switch)
Analysis tools
Batch operations

🐛 Troubleshooting

SVN not found

Error: SVN is not available in the system PATH

Solution: Install SVN and make sure it is on the system PATH.

Not a working copy

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

Solution: Navigate to a directory that is an SVN working copy or run checkout first.

Authentication issues

Error: svn: E170001: Authentication failed

Solution: Set the SVN_USERNAME and SVN_PASSWORD environment variables.

Timeouts on long operations

Error: Command timeout after 30000ms

Solution: Increase the value of SVN_TIMEOUT.

📄 License

MIT License - see LICENSE for more details.

🤝 Contributing

Fork the project
Create a feature branch (git checkout -b feature/new-feature)
Commit your changes (git commit -am 'Add new feature')
Push to the branch (git push origin feature/new-feature)
Open a Pull Request

📞 Support

Issues: GitHub Issues
Documentation: Project Wiki
Email: soporte@grec0.dev