AI FileSystem MCP

ai-filesystem-mcp

A edição do seu agente de IA não é atômica. Este MCP faz com que seja.

Um servidor MCP de ferramenta única para alterações atômicas em múltiplos arquivos com rollback automático — criado para Claude Code, Codex CLI, agentes Cursor e outros agentes de codificação modernos.

Esses agentes vêm com ferramentas integradas excelentes para leitura, escrita, busca, edição e shell. Eles não vêm com uma primitiva para "aplicar estas N operações de arquivo como uma única transação; se qualquer uma delas falhar, reverta tudo." Essa é a única coisa que este MCP oferece.

A ferramenta

transaction — aplica um lote de operações de arquivo atomicamente.

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

Se a operação 4 falhar, as operações 1-3 são restauradas a partir do backup antes que a chamada retorne. Se tudo for bem-sucedido, os backups são limpos.

Tipos de operação

type	Campos obrigatórios	O que faz
create	path, content	Cria um novo arquivo (cria diretórios pais).
write	path, content	Sobrescreve um arquivo existente.
update	path, updates[]	String.replace(oldText, newText) no local para cada atualização, em ordem.
move	path, destination	Renomeia path → destination.
delete	path	Remove um arquivo ou diretório (recursivo).

Por que uma única ferramenta

As versões 2.x anteriores traziam 39 comandos: I/O de arquivos, busca, git, análise de código, shell, arquivos compactados, diffs, metadados, criptografia, monitor de arquivos. Agentes de codificação modernos já fazem tudo isso melhor com suas próprias ferramentas Read / Edit / Write / Grep / Glob / Bash — envolver essas em MCP apenas adiciona latência e uma nova superfície de falha.

O que o Edit de um agente não consegue fazer é tratar várias alterações de arquivo como uma única unidade de trabalho. Se a operação 4 de 5 falhar, as operações 1-3 já estão no disco. Até que o agente adquira uma primitiva de transação real, essa lacuna é preenchida externamente — que é exatamente o trabalho deste servidor.

Quando você realmente precisa disso

Você provavelmente não precisa disso para uma rodada típica de "corrigir este bug". Você precisa quando uma única alteração lógica deve envolver vários arquivos ao mesmo tempo:

• Migração de banco de dados: arquivo de schema + modelo ORM correspondente + fixtures de teste correspondentes devem todos ser aplicados ou todos revertidos.
• Renomeação/refatoração transversal que abrange muitos arquivos e seria aplicada pela metade se o agente travar ou ficar sem contexto no meio do processo.
• Atualizações de código gerado onde a saída do gerador e a cola editada manualmente devem permanecer em sincronia.
• Config + alteração de código correspondente (ex.: entrada de tabela de roteamento + handler), onde o estado parcial fica quebrado.

Se a sua edição cabe em um arquivo, basta usar o Edit do agente. Se cabe em um comando de shell, basta usar Bash. Recorra ao transaction somente quando "tudo ou nada" realmente importar.

Instalação

Requer Node.js ≥ 18.

npm install -g ai-filesystem-mcp

Ou a partir do código-fonte:

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

Configuração (Claude Code / Codex CLI / qualquer cliente MCP)

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

Comunica-se via stdio JSON-RPC. Sem portas de rede.

Modelo de confiança

Executa localmente ao lado de um agente de IA confiável como o usuário que o iniciou. Não há sandbox de caminho; o limite de confiança é a sua máquina. Não exponha a clientes não confiáveis.

Desenvolvimento

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

Erros de tsc fazem o build falhar. Sem tsc || true.

Licença

MIT