🔶 Coppermind

Copiloto de IA para projeto de PCB no KiCAD — servidor MCP IPC-first, transacional e verificado

🇧🇷 Português (principal) · 🇺🇸 English

Descreva o que você quer projetar. O Coppermind propõe, verifica, explica e só então aplica — e tudo é reversível.

O Coppermind é um servidor MCP que permite a assistentes de IA (como o Claude) projetarem PCBs no KiCAD por linguagem natural. Diferente de um tradutor fino de comandos, ele pré-visualiza e verifica cada alteração antes de gravar (incluindo DRC/ERC nativo do KiCAD), mantém tudo reversível e fundamenta suas sugestões numa base de conhecimento de engenharia elétrica citável.

📑 Sumário

• Por que o Coppermind existe

• O que o torna diferente

• Arquitetura

• Como funciona o modelo transacional

• Instalação

• Configuração no cliente MCP

• Backends

• Catálogo de ferramentas (tools)

• Inteligência de design

• Autorroteamento (Freerouting)

• Fornecedores (JLCPCB/LCSC) e datasheets

• Exemplos de uso

• Qualidade: testes e CI

• Estrutura do projeto

• Roadmap / status das fases

• Limitações honestas

• Contribuindo

• Licença, créditos e aviso

Related MCP server: KiCad MCP Server

🎯 Por que o Coppermind existe

O projeto nasceu do estudo crítico de servidores MCP de KiCAD existentes (em especial o mixelpixx/KiCAD-MCP-Server). Eles provaram a demanda, mas tinham fraquezas recorrentes: documentação contraditória, um "router" de tools anunciado mas inerte, ponte TypeScript↔Python frágil, dependência forte do SWIG (pcbnew) — que o KiCAD 11 remove — e designs gerados por IA sem verificação obrigatória.

O Coppermind corrige cada uma dessas falhas por construção e vai além: transforma um executor de comandos num copiloto de engenharia que raciocina sobre o projeto, valida continuamente e mantém o humano no controle.

📄 A análise completa e as decisões de arquitetura estão em docs/ARQUITETURA.md.

✨ O que o torna diferente

🏗️ Arquitetura

O sistema é organizado em camadas com fronteiras nítidas. A regra de ouro: domain/ e verification/ nunca importam o KiCAD — os backends são a única costura. Isso permite testar inteligência e verificação sem o KiCAD e trocar o backend (IPC hoje, IPC-only amanhã) sem tocar na lógica.

🔁 Como funciona o modelo transacional

Toda alteração segue o ciclo:

begin → (aplica na cópia de trabalho) → preview → verify → commit | rollback

• preview retorna um diff estruturado, um render, as violações (estruturais + DRC nativo) e os conselhos de design (citados).

• commit roda o portão de verificação. Se houver violação de nível erro, o commit é bloqueado e a cópia de trabalho fica intacta para correção.

• Cada commit bem-sucedido entra na linha do tempo e permite undo/redo.

Resultado: é estruturalmente impossível gravar muitos estados inválidos sem aviso.

📦 Instalação

Requisitos: Python 3.11+, e (para uso ao vivo) KiCAD 10+ com a API IPC habilitada. Node não é necessário.

git clone https://github.com/charlesmmorais/coppermind.git
cd coppermind

# ambiente de desenvolvimento (roda a suíte inteira SEM precisar de KiCAD)
pip install -e ".[dev]"
pytest

# uso real (servidor MCP) — adicione o extra [ipc] para KiCAD ao vivo
pip install -e ".[ipc]"
coppermind          # ou: python -m coppermind.server

Seleção de backend por variável de ambiente:

COPPERMIND_BACKEND=auto    # IPC se o KiCAD estiver acessível, senão memória (padrão)
COPPERMIND_BACKEND=ipc     # exige KiCAD ao vivo
COPPERMIND_BACKEND=memory  # sempre em memória (dev/offline)

⚙️ Configuração no cliente MCP

Exemplo para Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "coppermind": {
      "command": "coppermind",
      "env": { "COPPERMIND_BACKEND": "auto", "LOG_LEVEL": "info" }
    }
  }
}

No KiCAD, habilite a API IPC em Preferences → Plugins → Enable IPC API Server.

🧩 Backends

A ordem de auto-detecção é IPC → memória. O BatchBackend é específico para arquivos e usado para DRC/render headless.

🛠️ Catálogo de ferramentas (tools)

41 tools no total: 7 núcleo + 5 de descoberta sempre visíveis, e 29 roteadas descobertas sob demanda (organizadas em 8 categorias).

Sempre visíveis — núcleo

project_create · component_place · net_create · net_route · design_preview · design_commit · design_rollback

Sempre visíveis — descoberta progressiva

list_tool_categories · get_category_tools · search_tools · get_tool_schema · execute_tool

Roteadas (sob demanda), por categoria

💡 Por que isso importa: carregar 41 schemas em todo turno desperdiça contexto e degrada a seleção do modelo. O Coppermind mantém o conjunto visível enxuto e expõe o resto via search_tools/execute_tool — e um teste de CI falha se alguém estourar o orçamento.

🧠 Inteligência de design

O que transforma "executor" em "copiloto" (tudo em intelligence/, sem KiCAD):

• Base de conhecimento de EE versionada e citável (knowledge.py): cada regra tem id estável, citação (ex.: IPC-2221) e racional. Um teste de governança garante ids únicos e que toda regra cita uma fonte.

• Calculador IPC-2221 (trace_width.py): largura mínima de trilha por corrente, validado contra tabelas conhecidas (1 A ≈ 0,30 mm, 1 oz, ΔT 10 °C).

• Crítica proativa (critique.py): largura de trilha de potência, desacoplamento por CI, presença de GND — conselhos que nunca bloqueiam o commit, cada um citando sua regra. Aparecem como advice no design_preview.

• Design blocks parametrizáveis (blocks.py): capacitor de desacoplamento, indicador LED+resistor — cada um retorna um BlockResult justificado.

"Adicione um capacitor de desacoplamento ao U1"
→ design_add_decoupling(U1, C1)  →  a crítica de "U1 sem desacoplamento" some

🔀 Autorroteamento (Freerouting)

Fluxo completo Specctra DSN → SES → placa, com runtime Java direto, Docker ou Podman (auto-detecção nessa ordem).

👉 Passo a passo completo: docs/AUTORROTEAMENTO.md (exportar o DSN do KiCAD, baixar o jar / usar Docker, rodar route_autoroute).

Resumo:

route_check                              # runtime + jar prontos?
# exporte o DSN no KiCAD: File → Export → Specctra DSN
route_autoroute  dsn_path=... ses_path=...   # roteia e importa
design_preview                           # revise (diff + DRC + render)
design_commit                            # grava (ou design_rollback)

O parser de SES (S-expression, ciente de resolução/unidades) e a aplicação ao board são puros e testados sem Java; só a execução do motor é isolada.

🛒 Fornecedores (JLCPCB/LCSC) e datasheets

Dois modos JLCPCB, atrás da mesma interface SupplierProvider:

1. API pública sem credenciais — JLCPCBProvider (via JLCSearch), parser puro testado.

2. Catálogo local — LocalLibraryProvider sobre o SQLite do jlcparts (catálogo de 2,5M+ peças), com busca/preço/estoque/Basic/datasheet — testado ponta a ponta (SQLite é local, sem rede).

Mais otimização de custo ciente da taxa Básico/Estendido do JLCPCB (pick_cheapest): em baixa quantidade, a parte Básica vence (sem taxa de US$3); em alto volume, o volume amortiza a taxa.

Enriquecimento de datasheet via LCSC (integrations/datasheets.py): resolve URLs de datasheet por id LCSC ou para um BOM via o provider ativo, com um cliente LCSC direto (parser de resposta puro e testado) como fallback.

supplier_cheapest  query="10k 0603"  qty=100
datasheet_enrich   bom={ "R1": "C25804", "R2": "C22775" }

💬 Exemplos de uso

Tudo em linguagem natural para o assistente:

Crie um projeto 'LEDBoard' de 50x50mm.
Coloque um LED em 10,10 e um resistor de 330Ω em 20,10.
Crie a net 'LED1' e roteie de R1 até o LED com 0,3mm.
Mostre o preview e os conselhos de design.
Se estiver ok, faça o commit como "primeiro LED".

Procure um resistor 10k 0603 Básico mais barato para 100 unidades.
Aplique a variante de baixo custo: R1 = 22k, R2 = DNP.
Rode o autorouter e me mostre o que mudou antes de gravar.

🔬 Qualidade: testes e CI

• 132 testes passando, todos sem KiCAD nem rede. As chamadas ao vivo (IPC/CLI/rede/motor externo) ficam isoladas e marcadas # pragma: no cover, cobertas pelo job de integração do CI (KiCAD 10 + Java headless).

• Invariantes verificadas por CI, não prometidas:

  • 🧮 orçamento de contexto: falha se o conjunto visível de tools crescer demais;

  • 📚 governança da KB: toda regra precisa de id único, citação e racional;

  • 🚫 SWIG-free (prontidão KiCAD 11): falha se qualquer módulo importar pcbnew.

pytest                 # suíte completa (sem KiCAD)
ruff check src tests   # lint
mypy src               # tipagem

🗂️ Estrutura do projeto

coppermind/
├── README.md                  # este arquivo (pt-BR, principal)
├── README.en.md               # versão em inglês
├── LICENSE                    # MIT
├── pyproject.toml
├── docs/
│   ├── ARQUITETURA.md         # documento de arquitetura/decisões
│   ├── AUTORROTEAMENTO.md     # guia passo a passo do Freerouting
│   ├── architecture.svg       # diagrama de arquitetura
│   └── freerouting-flow.svg   # diagrama do fluxo de autorroteamento
├── src/coppermind/
│   ├── server.py · session.py
│   ├── domain/                # modelo, diff, operações (sem KiCAD)
│   ├── verification/          # checagens estruturais
│   ├── transactions/          # transações + timeline
│   ├── intelligence/          # KB, crítica, blocks, placement, explain
│   ├── schematic/             # hierarquia + flatten de netlist
│   ├── variants.py
│   ├── backends/              # IPC · Batch · Memory · DRC · units · mapping
│   ├── integrations/          # suppliers · datasheets · freerouting
│   └── tools/                 # core · discovery · registry · routed
├── tests/                     # 132 testes (sem KiCAD)
└── .github/workflows/ci.yml   # core (sem KiCAD) + integração (KiCAD+Java)

🧭 Roadmap / status das fases

⚠️ Limitações honestas

• Colocação de footprint de biblioteca ao vivo depende de uma API estável do kipy para buscar a definição do footprint — inexistente no kipy 0.7 / KiCAD 10. O Coppermind já modela isso no plano puro e tenta a colocação, registrando o que não resolver.

• Modificar/remover trilhas ao vivo precisa de um mapa estável de item-id; hoje só adições de trilha são empurradas ao vivo (o plano puro já cobre o resto).

• A API oficial api.jlcpcb.com/Components exige credenciais enterprise — por isso o modo "sem credenciais" usa o JLCSearch, e o catálogo local cobre os 2,5M+ offline.

🤝 Contribuindo

Contribuições são bem-vindas! Sugestão de fluxo:

1. Abra uma issue descrevendo bug/ideia (com passos de reprodução).

2. Fork → branch de feature → mantenha o estilo (ruff/mypy) → adicione testes.

3. Garanta pytest, ruff check e mypy src verdes.

4. Abra o PR com descrição clara.

Princípio inegociável: o núcleo permanece independente de KiCAD e testável.

📜 Licença e créditos

Licenciado sob MIT — veja LICENSE.

Créditos: Model Context Protocol (Anthropic), KiCAD, kicad-python, Freerouting, jlcparts e JLCSearch.