convez.ai
MCP ServerAutomaçãoIntermediário
BradCleal

Surgical Filesystem MCP Server

BradCleal/surgical-fs-mcp

Edição precisa de arquivos com matching inteligente e transações ACID

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP em C# que oferece edição de arquivos tolerante a espaços em branco, com cascata de 6 estratégias de correspondência e suporte a transações ACID. Permite operações de busca/substituição, edição por linhas e transações em lote com backup e rollback automático.

Instalação

$npx convez-ai BradCleal/surgical-fs-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 2 semanas
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Automatizar edições em arquivos de configuração com variabilidade de espaçamento
  • Executar múltiplas edições de arquivo como transação atômica com rollback automático
  • Realizar find/replace tolerante a normalizações de quebra de linha e tabulações

Veredito

MCP robusto e battle-tested (port direto de ClipMicro) com suporte real a transações ACID e matching sofisticado. Ideal para cenários de automação de edição de arquivo que exigem confiabilidade e tolerância a variações de formatação.

README

A tradução para o português deste README ainda está na fila.


license: mit tags:

  • mcp
  • claude
  • filesystem
  • windows
  • dotnet language:
  • en

Surgical Filesystem MCP Server (C#)

A C# MCP server providing whitespace-tolerant file editing tools.

Direct port of ClipMicro's battle-tested code, including:

  • 6-strategy matching cascade from UpdateFindReplaceWithResult
  • ACID backup/rollback from BackupManager

Same code. Same behavior. No translation bugs.

Quick Start (Pre-built Binaries)

Download from the release/ folder:

  • surgical-fs-mcp.exe - Standalone executable
  • surgical-fs-mcp.dll - For use with dotnet
  • ModelContextProtocol.dll - Required dependency

No build required - just configure Claude Desktop (see below).

Features

6-Strategy Whitespace-Tolerant Matching

Directly ported from ClipMicro's UpdateFindReplaceWithResult:

StrategyWhat it handles
1. Exact matchPerfect input
2. Line ending normalizationCRLF vs LF vs CR
3. Trim whitespaceLeading/trailing whitespace
4. Tab normalizationTabs → 4 spaces
5. Fuzzy whitespaceCollapse \s+ → single space, line-by-line
6. Partial line matchSingle-line substring matching

ACID Transaction Support

Directly ported from ClipMicro's BackupManager:

  • Pre-operation backup: Files backed up to .surgicalfs_backup_YYYYMMDD_HHMMSS/
  • Automatic rollback: On ANY failure, original files restored
  • New file tracking: Files created during failed transactions are deleted
  • New directory tracking: Empty directories created during failed transactions are removed
  • Batch transactions: Multiple edits as one atomic operation

Tools

ToolDescription
SurgicalEditFind/replace with 6-strategy matching + ACID
EditLinesReplace lines by number + ACID
InsertLinesInsert at line without replacing + ACID
DeleteLinesRemove line range + ACID
PreviewEditShow diff without applying (read-only)
ReadFileLinesRead file with line numbers (read-only)
BatchEditMultiple edits as single ACID transaction

Installation

Prerequisites

  • .NET 8.0 SDK
  • Claude Desktop

Build

cd C:\path\to\surgical-fs-mcp
dotnet restore
dotnet build --configuration Release

Configure Allowed Directories

Edit SurgicalFsMcp.cs and modify AllowedDirectories in the PathValidator class:

private static readonly List<string> AllowedDirectories = new()
{
    Environment.GetFolderPath(Environment.SpecialFolder.MyDocuments),
    Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.UserProfile), "Projects"),
    @"C:\Your\Custom\Path",
};

Rebuild after changing.

Configure Claude Desktop

Edit %APPDATA%\Claude\claude_desktop_config.json:

Option 1: Using dotnet run (easier for development)

{
  "mcpServers": {
    "surgical_fs": {
      "command": "dotnet",
      "args": ["run", "--project", "C:\\path\\to\\surgical-fs-mcp\\SurgicalFsMcp.csproj"]
    }
  }
}

Option 2: Using compiled exe (faster startup)

{
  "mcpServers": {
    "surgical_fs": {
      "command": "C:\\path\\to\\surgical-fs-mcp\\bin\\Release\\net8.0\\surgical-fs-mcp.exe"
    }
  }
}

Restart Claude Desktop after configuring.

Usage Examples

Single Surgical Edit

SurgicalEdit(
    path: "config.json",
    find: '"debug": false',
    replace: '"debug": true'
)

Returns: ✅ Success: Edit applied using 'exact_match' matching

Preview Before Editing

PreviewEdit(
    path: "config.json",
    find: '"debug": false',
    replace: '"debug": true'
)

Returns a diff showing what would change.

Batch Edit (ACID Transaction)

BatchEdit(edits_json: '[
    {"path": "file1.cs", "find": "oldMethod", "replace": "newMethod"},
    {"path": "file2.cs", "find": "oldMethod", "replace": "newMethod"},
    {"path": "file3.cs", "find": "oldMethod", "replace": "newMethod"}
]')

If ANY edit fails, ALL changes roll back automatically.

Line-Based Editing

ReadFileLines(path: "code.cs", start_line: 50, end_line: 60)
EditLines(path: "code.cs", start_line: 52, end_line: 55, new_content: "// new code here")

How ACID Rollback Works

  1. Before any modification: Original file content is copied to backup directory
  2. During operation: Changes are applied to the original file
  3. On success: Backup directory is deleted
  4. On failure:
    • Original content is restored from backup
    • Any newly created files are deleted
    • Any newly created empty directories are removed
    • Error message includes "rolled back" confirmation

Security

  • Path validation against allowed directories
  • Directory traversal (..) blocked
  • UTF-8 encoding enforced
  • Backup directories automatically cleaned up

Credits

  • 6-strategy matching: Direct port from ClipMicro's UpdateFindReplaceWithResult
  • ACID backup system: Direct port from ClipMicro's BackupManager
  • Original ClipMicro: clipmicro.com
Ver o original no GitHub

Bom para

Relacionados