AI FileSystem MCP

ai-filesystem-mcp

La edición de tu agente de IA no es atómica. Este MCP lo hace posible.

Un servidor MCP de una sola herramienta para cambios atómicos en múltiples archivos con reversión automática — diseñado para Claude Code, Codex CLI, agentes de Cursor y otros agentes de codificación modernos.

Esos agentes incluyen excelentes herramientas integradas para leer, escribir, buscar, editar y shell. No incluyen una primitiva para "aplicar estas N operaciones de archivos como una sola transacción; si alguna falla, revertir todo." Esa es la única y exclusiva función que proporciona este MCP.

La herramienta

transaction — aplica un lote de operaciones de archivos de forma atómica.

{
  "name": "transaction",
  "arguments": {
    "operations": [
      { "type": "create", "path": "src/feature.ts",  "content": "..." },
      { "type": "write",  "path": "src/index.ts",    "content": "..." },
      { "type": "update", "path": "src/lib/util.ts",
        "updates": [{ "oldText": "foo()", "newText": "foo(arg)" }] },
      { "type": "move",   "path": "src/old.ts", "destination": "src/legacy/old.ts" },
      { "type": "delete", "path": "src/dead.ts" }
    ],
    "rollbackOnError": true
  }
}

Si la operación 4 falla, las operaciones 1-3 se restauran desde la copia de seguridad antes de que la llamada retorne. Si todo tiene éxito, las copias de seguridad se eliminan.

Tipos de operación

type	Campos requeridos	Qué hace
create	path, content	Crea un archivo nuevo (crea los directorios padre).
write	path, content	Sobrescribe un archivo existente.
update	path, updates[]	Aplicación en el lugar de String.replace(oldText, newText) para cada actualización, en orden.
move	path, destination	Renombra path → destination.
delete	path	Elimina un archivo o directorio (recursivo).

Por qué una sola herramienta

Las versiones anteriores 2.x incluían 39 comandos: E/S de archivos, búsqueda, git, análisis de código, shell, archivos comprimidos, diffs, metadatos, cifrado, vigilancia de archivos. Los agentes de codificación modernos ya hacen todo eso mejor con sus propias herramientas Read / Edit / Write / Grep / Glob / Bash — envolverlas en MCP solo añade latencia y una nueva superficie de fallos.

Lo que el Edit de un agente no puede hacer es tratar varios cambios de archivos como una sola unidad de trabajo. Si la op 4 de 5 falla, las ops 1-3 ya están en el disco. Hasta que el agente adquiera una primitiva de transacción real, esa brecha se cubre externamente — que es exactamente el trabajo de este servidor.

Cuándo realmente lo necesitas

Probablemente no lo necesites para un turno típico de "arregla este error". Sí lo necesitas cuando un único cambio lógico debe tocar varios archivos a la vez:

• Migración de base de datos: el archivo de esquema + el modelo ORM correspondiente + los fixtures de prueba correspondientes deben aplicarse todos o revertirse todos.
• Renombrado / refactorización transversal que abarca muchos archivos y se aplicaría a medias si el agente se bloquea o se queda sin contexto a mitad de camino.
• Actualizaciones de código generado donde la salida del generador y el código de unión editado a mano deben permanecer sincronizados.
• Cambio de configuración + código correspondiente (p. ej., entrada de tabla de enrutamiento + handler), donde el estado a medias está roto.

Si tu edición cabe en un solo archivo, simplemente usa el Edit del agente. Si cabe en un solo comando de shell, simplemente usa Bash. Recurre a transaction solo cuando "todo o nada" realmente importa.

Instalación

Requiere Node.js ≥ 18.

npm install -g ai-filesystem-mcp

O desde el código fuente:

git clone https://github.com/proofmath-owner/ai-filesystem-mcp.git
cd ai-filesystem-mcp
npm install
npm run build
node dist/index.js

Configuración (Claude Code / Codex CLI / cualquier cliente MCP)

{
  "mcpServers": {
    "ai-filesystem": {
      "command": "node",
      "args": ["/absolute/path/to/ai-filesystem-mcp/dist/index.js"]
    }
  }
}

Habla stdio JSON-RPC. Sin puertos de red.

Modelo de confianza

Se ejecuta localmente junto a un agente de IA de confianza como el usuario que lo inició. No hay sandbox de rutas; el límite de confianza es tu máquina. No lo expongas a clientes no confiables.

Desarrollo

npm install
npm run dev      # tsx watch on src/index.ts
npm run build    # tsc -> dist/
npm run lint
npm run format

Los errores de tsc hacen fallar la compilación. Sin tsc || true.

Licencia

MIT