SVN MCP Server

Um servidor MCP para integrar e gerenciar repositórios Subversion (SVN), permitindo que agentes de IA realizem tarefas de controle de versão.

GitHub

Documentação

SVN MCP Server

Um servidor MCP (Model Context Protocol) completo para integração com Subversion (SVN), projetado para permitir que agentes de IA gerenciem repositórios SVN de forma eficiente.

🎯 Recursos

✅ Operações básicas de repositório: info, status, log, diff, checkout, update
✅ Gerenciamento de arquivos: add, commit, delete, revert
✅ Ferramentas de manutenção: cleanup
🔄 Gerenciamento de branches: (Em desenvolvimento)
🔄 Operações avançadas: merge, switch, propriedades (Em desenvolvimento)
🔄 Ferramentas de análise: blame, detecção de conflitos (Em desenvolvimento)
🔄 Operações em lote: (Em desenvolvimento)

📋 Requisitos

Node.js >= 18.0.0
Subversion (SVN) instalado e disponível no PATH
TypeScript (para desenvolvimento)

🔍 Detectando a instalação do SVN

Verifique se o SVN está instalado

# 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

Saída esperada se o SVN estiver instalado corretamente:

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/

❌ Erros comuns se o SVN NÃO estiver instalado:

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

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

🛠️ Diagnóstico avançado

# 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

💾 Instalando SVN no Windows

Opção 1: Gerenciadores de pacotes

# Using Chocolatey (Recommended)
choco install subversion

# Using winget
winget install CollabNet.Subversion

# Using Scoop
scoop install subversion

Opção 2: Instaladores oficiais

TortoiseSVN (inclui o cliente de linha de comando):

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

SlikSVN (somente linha de comando):

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

CollabNet Subversion:

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

Opção 3: Visual Studio ou 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

🐧 Instalando SVN no 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

🍎 Instalando SVN no macOS

# Homebrew (Recommended)
brew install subversion

# MacPorts
sudo port install subversion

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

🔧 Configurando SVN após a instalação

Verifique a configuração global

# 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

Verifique o acesso ao repositório

# 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

🚀 Instalação

Via NPM

npm install -g @grec0/mcp-svn

Desenvolvimento Local

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

⚙️ Configuração

Variáveis de Ambiente

Variável	Descrição	Padrão
`SVN_PATH`	Caminho para o executável do SVN	`svn`
`SVN_WORKING_DIRECTORY`	Diretório local da cópia de trabalho	`process.cwd()`
`SVN_URL` (alias: `SVN_REPOSITORY_URL`)	URL do repositório. Habilita fluxos de trabalho somente com URL e resolução de destino `/trunk/...`	-
`SVN_USERNAME`	Usuário de autenticação	-
`SVN_PASSWORD`	Senha de autenticação	-
`SVN_TIMEOUT`	Tempo limite em milissegundos	`30000`

SVN_WORKING_DIRECTORY e SVN_URL são independentes — configure um ou ambos. Com ambos configurados, operações locais (svn_status, svn_commit, ...) são executadas na cópia de trabalho, e ferramentas com suporte a URL (svn_cat, svn_list, svn_info, svn_log, svn_diff) podem ser chamadas com:

uma URL completa (https://svn.example.com/repo/trunk/file.sql)
um caminho relativo ao repositório começando com / (/trunk/file.sql) — combinado com SVN_URL
um caminho local — resolvido em relação à cópia de trabalho

Exemplo de Configuração 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"
      }
    }
  }
}

🛠️ Ferramentas Disponíveis

Operações Básicas

`svn_health_check`

Verifica o status de saúde do sistema SVN e da cópia de trabalho.

svn_health_check()

`svn_info`

Obtém informações detalhadas sobre a cópia de trabalho ou um arquivo específico.

svn_info(path?: string)

`svn_status`

Mostra o status dos arquivos na cópia de trabalho.

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

`svn_log`

Mostra o histórico de commits do repositório.

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

`svn_diff`

Mostra diferenças entre revisões de arquivos.

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

Operações de Repositório

`svn_checkout`

Faz checkout de um repositório SVN.

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

`svn_update`

Atualiza a cópia de trabalho a partir do repositório.

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

Gerenciamento de Arquivos

`svn_add`

Adiciona arquivos ao controle de versão.

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

`svn_commit`

Envia alterações para o repositório.

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

`svn_delete`

Remove arquivos do controle de versão.

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

`svn_revert`

Reverte alterações locais em arquivos.

svn_revert(paths: string | string[])

Ferramentas de Manutenção

`svn_cleanup`

Limpa a cópia de trabalho de operações interrompidas.

svn_cleanup(path?: string)

📖 Exemplos de Uso

Verificar o status do sistema

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

Obter informações do repositório

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

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

Mostrar status dos arquivos

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

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

Fazer checkout de um repositório

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

Enviar alterações

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

🧪 Testes

# Run tests
npm test

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

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

🏗️ Desenvolvimento

Scripts disponíveis

# 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

Estrutura do projeto

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

📊 Status do Desenvolvimento

Consulte o arquivo SVN_MCP_IMPLEMENTATION.md para a lista completa de implementação.

Progresso atual: Estágio 1 concluído (Operações Básicas) ✅

Próximos estágios:

Gerenciamento de branches (branching)
Operações avançadas (merge, switch)
Ferramentas de análise
Operações em lote

🐛 Solução de Problemas

SVN não encontrado

Error: SVN is not available in the system PATH

Solução: Instale o SVN e certifique-se de que ele esteja no PATH do sistema.

Não é uma cópia de trabalho

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

Solução: Navegue para um diretório que seja uma cópia de trabalho SVN ou execute o checkout primeiro.

Problemas de autenticação

Error: svn: E170001: Authentication failed

Solução: Defina as variáveis de ambiente SVN_USERNAME e SVN_PASSWORD.

Tempo limite em operações longas

Error: Command timeout after 30000ms

Solução: Aumente o valor de SVN_TIMEOUT.

📄 Licença

Licença MIT - consulte LICENSE para mais detalhes.

🤝 Contribuindo

Faça um fork do projeto
Crie um branch de funcionalidade (git checkout -b feature/new-feature)
Envie suas alterações (git commit -am 'Add new feature')
Envie para o branch (git push origin feature/new-feature)
Abra um Pull Request

📞 Suporte

Issues: GitHub Issues
Documentação: Project Wiki
E-mail: soporte@grec0.dev