mcp-local-erp

Servidor MCP local de leitura e escrita de arquivos de um projeto, para uso com o Claude Desktop. Cada projeto (ex: erp-distribuidora, erp-consultorio, erp-confeccao...) recebe sua própria cópia desta pasta, com um config.yaml próprio. Isso permite que vários projetos rodem em paralelo, cada um aparecendo com um nome distinto dentro do Claude Desktop.

Toda escrita de arquivo passa por um harness de controle de mudanças: nenhuma alteração acontece sem um plano prévio (feature + arquivos envolvidos) aprovado explicitamente. Veja a seção Harness de controle de mudanças abaixo.

Estrutura

mcp-local-erp/
├── config.yaml         # nome do projeto e raiz de arquivos que o servidor enxerga
├── server.py            # define as ferramentas (read_file, write_file, list_dir, harness)
├── change_control.py    # implementação do harness: planos, aprovação, log de auditoria
├── start.py             # registra este servidor no Claude Desktop
├── pyproject.toml       # dependências (fastmcp, pyyaml, psutil)
├── mcp_audit.jsonl       # log append-only de todo evento do harness (versionado no Git)
├── mcp_state.json        # planos pendentes/aprovados (transitório — não versionado)
└── README.md

mcp_state.json e mcp_audit.jsonl ficam sempre dentro desta pasta (mcp-local-erp/), nunca dentro do projeto que o servidor gerencia — mesmo quando root_path aponta para fora dela. Veja o porquê em Arquivos gerados pelo harness.

---

Instalação (primeira vez na máquina)

1. Python

Verifique se já está instalado:

python --version

Se não retornar nada, instale a versão 3.11 ou superior:

Sistema	Comando
Windows	winget install Python.Python.3.12
macOS	brew install python@3.12
Linux	sudo apt install python3 python3-venv

2. uv (gerenciador de dependências)

Sistema	Comando
Windows (PowerShell)	powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
macOS / Linux	curl -LsSf https://astral.sh/uv/install.sh | sh

Feche e reabra o terminal depois de instalar, para o uv entrar no PATH.

3. Dependências do projeto

Dentro da pasta mcp-local-erp:

cd C:\project-claude\mcp-local
uv sync

Isso cria um .venv local e instala tudo conforme o pyproject.toml.

---

Configuração

Edite o config.yaml antes de registrar:

project_name: mcp-local-erp    # nome único — é o que aparece no Claude Desktop
environment: dev                # dev | prod — identifica o ambiente na auditoria
root_path: ../                  # pasta raiz do projeto que este servidor pode ler/escrever
allowed_extensions:              # extensões que write_file tem permissão de gravar
  - .py
  - .tsx
  - .ts
  - .json
  - .yaml
  - .md
blocked_dirs:                     # diretórios nunca acessíveis, nem para leitura
  - node_modules
  - .git
  - .venv

mcp-local-erp é o nome padrão de fábrica do pacote. Ao colocar esta pasta dentro de um projeto específico (erp-distribuidora, erp-consultorio, erp-confeccao...), troque project_name para um nome único por projeto — é o que diferencia os servidores quando mais de um estiver rodando ao mesmo tempo no Claude Desktop.

root_path define o escopo de read_file / list_dir / write_file — ou seja, o projeto que este servidor enxerga e pode alterar. Isso é propositalmente diferente de onde o harness guarda seu próprio estado (ver seção seguinte).

---

Registro no Claude Desktop

Passo 1 — Feche o Claude Desktop por completo

Isso é obrigatório, não opcional. O Claude Desktop mantém o claude_desktop_config.json em memória enquanto está aberto; se ele continuar rodando durante o registro, pode sobrescrever o arquivo com o estado antigo ao ser fechado depois — apagando a entrada nova sem aviso.

No Windows:

1. Clique com o botão direito no ícone do Claude na bandeja do sistema → Sair / Quit.
2. Confirme que não sobrou processo algum:

   Get-Process Claude -ErrorAction SilentlyContinue
   

   Se não retornar nada, está encerrado.

Passo 2 — Rode o script de registro

uv run start.py

O script:

• detecta automaticamente onde este Windows guarda o claude_desktop_config.json — cobre tanto instalação via Microsoft Store (MSIX) (%LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude\) quanto a instalação tradicional (%APPDATA%\Claude\). Isso importa: editar o arquivo errado é a causa mais comum de "registrei mas não apareceu";
• limpa processos órfãos de server.py deste projeto — instâncias presas de sessões anteriores cujo processo pai (o Claude Desktop) já fechou. Só encerra processo com pai morto; nunca mexe em processo com o Claude Desktop ainda rodando;
• lê o project_name do config.yaml e, se a entrada ainda não existir, adiciona automaticamente (com backup do arquivo original antes de qualquer alteração); se já existir, apenas avisa e não altera nada;
• em qualquer um dos dois casos, relê o arquivo no final e mostra a lista de servidores registrados, como conferência.

Se mcp-local-erp (ou o nome que você definiu) não aparecer nessa lista final, não abra o Claude Desktop ainda — confirme antes se o processo estava mesmo encerrado no Passo 1.

Passo 3 — Abra o Claude Desktop

O novo servidor MCP aparece na lista de ferramentas conectadas com o nome definido em project_name.

---

Harness de controle de mudanças

Nenhuma escrita acontece "direto". Toda alteração de arquivo passa obrigatoriamente por um plano prévio, revisado por você, antes de o conteúdo ser gravado. Isso dá rastreabilidade clara do propósito de cada mudança e impede que várias alterações aconteçam sem revisão.

O processo, passo a passo

 ┌──────────────────────────┐
 │ 1. propose_change         │  Claude declara: feature, descrição do
 │    (Claude chama)         │  propósito, e a lista exata de paths que
 │                           │  serão criados/alterados.
 └────────────┬──────────────┘
              │  grava plano com status "pending"
              │  em mcp_state.json (dentro de mcp-local-erp/)
              ▼
 ┌──────────────────────────┐
 │ 2. revisão humana          │  Você lê o plano exibido na conversa:
 │    (você decide)          │  feature, arquivos, propósito.
 └────────────┬──────────────┘
              │
      ┌───────┴────────┐
      │                │
   aprovado          rejeitado
      │                │
      ▼                ▼
 ┌───────────────┐  ┌───────────────────┐
 │ 3. approve_    │  │ reject_change      │
 │    change      │  │ (Claude chama)      │
 │ (Claude chama) │  │ plano vira          │
 │ plano vira     │  │ "rejected" — fim    │
 │ "approved"     │  └───────────────────┘
 └───────┬────────┘
         ▼
 ┌────────────────────────────────────┐
 │ 4. write_file(rel_path, content,    │
 │    plan_id, feature, description)   │
 │                                     │
 │  Antes de gravar, verifica:         │
 │    - rel_path é um arquivo interno  │
 │      reservado do harness? recusa   │
 │    - plan_id existe?                │
 │    - status == "approved"?          │
 │    - rel_path está na lista de      │
 │      files do plano?                │
 │                                     │
 │  Se qualquer checagem falhar        │
 │  → recusa com erro, nada é gravado. │
 │                                     │
 │  Se tudo OK:                        │
 │    - injeta comentário de           │
 │      rastreabilidade no topo do     │
 │      arquivo (feature, plano, data) │
 │    - grava o arquivo (dentro de     │
 │      ROOT, o projeto gerenciado)    │
 │    - registra o evento em           │
 │      mcp_audit.jsonl (dentro de     │
 │      mcp-local-erp/)                │
 └────────────────────────────────────┘

Ferramentas do harness

Ferramenta MCP	Quando usar	Efeito
propose_change(feature, description, files)	Antes de qualquer alteração	Cria plano pending, devolve plan_id
approve_change(plan_id)	Depois que você aprovar na conversa	Plano vira approved
reject_change(plan_id)	Se você recusar o plano proposto	Plano vira rejected
list_pending_changes(status)	Para conferir o que está pendente/aprovado/rejeitado	Lista os planos filtrados por status
write_file(rel_path, content, plan_id, feature, description)	Só depois do plano aprovado	Grava o arquivo com comentário de rastreabilidade; recusa se o plano não cobrir rel_path
read_file(rel_path)	A qualquer momento	Leitura livre, sem exigir plano (não altera nada)
list_dir(rel_path)	A qualquer momento	Leitura livre da árvore de arquivos

Arquivos gerados pelo harness

• mcp_state.json — os planos e seus status (pending / approved / rejected) e quais escritas cada plano já cobriu. Não é versionado (está no .gitignore): é estado de trabalho, não histórico.
• mcp_audit.jsonl — log append-only, uma linha JSON por evento (propose, approve, reject, write), com timestamp. Este arquivo é versionado — é o seu histórico auditável de quem pediu e aprovou o quê, mesmo depois de o plano ter saído do mcp_state.json.

Os dois arquivos vivem sempre em HARNESS_ROOT (Path(__file__).parent em server.py, ou seja, a própria pasta mcp-local-erp/) — não em ROOT (root_path do config.yaml, que é o projeto gerenciado, ex: erp-distribuidora/). Essa separação é intencional: ROOT muda de projeto para projeto e pode até apontar para fora desta pasta, mas o bookkeeping do harness precisa ficar contido e previsível, sempre no mesmo lugar, independente de onde root_path aponte. Por isso também write_file recusa qualquer tentativa de gravar em um arquivo chamado mcp_state.json ou mcp_audit.jsonl — mesmo com plano aprovado — para que o próprio fluxo de aprovação não possa corromper seu próprio estado.

Exemplo de recusa (proteção funcionando)

Se o Claude tentar escrever em um arquivo fora do escopo aprovado:

ValueError: Arquivo 'app/models/pagamento.py' não está no escopo
declarado do plano 'a1b2c3d4' (['server.py', 'change_control.py']).
Proponha um novo plano cobrindo este arquivo.

Isso é o comportamento esperado: qualquer expansão de escopo exige um novo plano — e uma nova aprovação sua.

---

Reaproveitando em projetos futuros

Esta pasta é autocontida — nada nela depende de algo externo. Para usar em um novo projeto:

1. Copie a pasta mcp-local-erp inteira para dentro do repositório.
2. Ajuste project_name e root_path no config.yaml.
3. Repita os passos de Registro no Claude Desktop acima.

Não é um pacote instalável (não vai pro PyPI, não é importado por outro código) — é um servidor autônomo, então não precisa de nenhum ajuste de packaging além do que já está pronto aqui.

---

Troubleshooting

Erro Failed to build mcp-local mencionando hatchling ou only-include: o pyproject.toml já vem corrigido com [tool.uv] package = false, que avisa o uv para instalar dependências e rodar os scripts sem tentar empacotar nada. Se aparecer de novo, confirme que seu pyproject.toml tem esse bloco e não tem uma seção [build-system].

A entrada some do claude_desktop_config.json depois de reiniciar o Claude Desktop: o app estava aberto durante o registro. Siga o Passo 1 da seção de Registro à risca antes de rodar start.py de novo.

A entrada nunca aparece na tela "Servidores MCP locais", mesmo o terminal confirmando o registro: o script pode ter escrito no arquivo tradicional (%APPDATA%\Claude\) enquanto sua instalação do Claude Desktop é via Microsoft Store (MSIX), que lê de %LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude\. A versão atual do start.py já detecta isso automaticamente e imprime qual caminho encontrou — confira a linha "Config detectado" no início da saída para confirmar qual arquivo está sendo usado.

spawn uv ENOENT nos logs do Claude Desktop: o app não achou o executável do uv no seu próprio PATH (que pode ser mais restrito que o do terminal). O start.py já resolve o caminho absoluto do uv automaticamente; se o aviso aparecer na tela, rode where uv e confirme o caminho manualmente no claude_desktop_config.json.

write_file recusa com "Plano não encontrado" ou "não aprovado": o harness está funcionando como esperado — chame propose_change (e, depois da sua aprovação, approve_change) antes de tentar escrever.

write_file recusa dizendo que o arquivo é "interno do harness": também esperado — mcp_state.json e mcp_audit.jsonl nunca podem ser alvo de write_file, mesmo com plano aprovado; são gerenciados só pelas funções internas de change_control.py.

---

Observação importante

Rodar python server.py diretamente no terminal não faz nada visível — o servidor fica esperando mensagens no stdin. Quem inicia o processo de fato é o Claude Desktop, usando o comando registrado pelo start.py. Use o start.py apenas para garantir o registro; o "start" do servidor em si acontece automaticamente quando o Claude Desktop abre.