Heimdall MCP Adiciona Bloqueios de Recursos

A corrida que ninguém avisa sobre

Execute duas sessões do Claude Code contra o mesmo repositório — uma refatorando um módulo, outra corrigindo um erro de digitação em três arquivos de distância que também toca um arquivo de configuração compartilhado — e eventualmente ambas as sessões decidem gravar o mesmo arquivo dentro de algumas centenas de milissegundos uma da outra. Nada impede isso. A segunda gravação vence, silenciosamente. As alterações do primeiro agente desaparecem, e nenhuma das sessões tem ideia de que isso aconteceu.

A mesma coisa acontece um nível abaixo, com servidores MCP em vez de ferramentas de editor nativas: um servidor de sistema de arquivos MCP invocado por dois processos de agente, ou uma ferramenta run_migration exposta por um servidor de banco de dados, chamada duas vezes em rápida sucessão por duas sessões não relacionadas. O Heimdall MCP já tinha políticas de nome de ferramenta (v1.2) e políticas de nível de argumento (v1.4) — você poderia dizer "nunca chame write_file em /etc/passwd" — mas nenhuma dessas responde a uma pergunta diferente: o que acontece quando duas chamadas para o mesmo recurso chegam ao mesmo tempo?

Esse é o modo de falha que a versão 1.5.0 foi construída para fechar.

Repositório: https://github.com/enmanuelmag/heimdall-mcp
Site: https://stack.cardor.dev/heimdall

O que foi lançado

A versão 1.5.0 adiciona bloqueios de recurso, aplicados em dois níveis que compartilham o mesmo mecanismo subjacente: chamadas de ferramentas MCP roteadas através do proxy do Heimdall, e ferramentas nativas do host (Write/Edit/MultiEdit/NotebookEdit do Claude Code, e equivalentes do OpenCode) que nunca tocam o proxy.

Camada 1: bloqueios em servidores MCP

Um bloco locks, chaveado pelo nome da ferramenta, fica ao lado das configurações existentes de tools e toolPolicies de um servidor:

// heimdall.config.ts
export default {
  servers: {
    filesystem: {
      tools: { allow: ['read_file', 'write_file'] },
      locks: {
        write_file: { resource: 'path', ttl: 30_000 },
        run_migration: { resource: 'db-migration', onConflict: 'warn' },
      },
    },
  },
} satisfies HeimdallConfig;

Cada entrada é uma LockRule:

write_file bloqueando em path significa que duas chamadas para write_file com o mesmo caminho se serializam; duas chamadas com caminhos diferentes nunca competem. O bloqueio de run_migration na chave literal db-migration significa que cada chamada para essa ferramenta se serializa contra cada outra chamada, independentemente dos argumentos — útil quando o recurso sendo protegido não é nenhum argumento único, mas "o banco de dados".

Camada 2: bloqueios em ferramentas nativas do host

Os servidores MCP cobrem apenas parte da área de superfície de um agente. As próprias ferramentas de edição de arquivos do Claude Code — Write, Edit, MultiEdit, NotebookEdit — estão integradas ao agente de codificação. Elas nunca são servidores MCP, portanto nunca passam pelo proxy JSON-RPC do Heimdall, e nenhuma camada de política que se conecta a tools/call pode vê-las.

A versão 1.5.0 adiciona um campo hosts, um irmão de servers/default, que aplica a mesma forma de LockRule a essas ferramentas nativas:

// heimdall.config.ts
export default {
  hosts: {
    'claude-code': {
      locks: {
        Write: { resource: 'file_path', ttl: 30_000 },
        Edit: { resource: 'file_path', ttl: 30_000 },
        MultiEdit: { resource: 'file_path', ttl: 30_000 },
        NotebookEdit: { resource: 'file_path', ttl: 30_000 },
      },
    },
  },
} satisfies HeimdallConfig;