🇧🇷 Português · 🇺🇸 English
Descreva o circuito, não as coordenadas. O Coppermind resolve símbolos reais, cria o Circuit IR, compõe o esquemático, roda ERC, revisa a organização visual e só confirma mudanças depois dos gates de segurança.
O Coppermind é um servidor MCP em Python para trabalhar com projetos eletrônicos
no KiCad. O caminho principal de esquemático é semântico: o agente opera com
Component / Pin / Net / Constraint, enquanto o Coppermind transforma essa intenção
em .kicad_sch real, usando símbolos das bibliotecas instaladas do KiCad.
Ele pode ser executado com dois transports MCP:
- stdio — cliente local inicia o Coppermind como subprocesso;
- Streamable HTTP — endpoint local em
/mcp, adequado para um túnel/gateway MCP confiável quando o cliente está fora da máquina.
O HTTP é loopback-only por projeto. O Coppermind não deve ser publicado diretamente na Internet: ele ainda mantém uma sessão de design por processo e não implementa autenticação multiusuário.
O fluxo de esquemático implementa as cinco fases da arquitetura semântica:
| Fase | Entrega |
|---|---|
| 1 — Circuit IR + símbolos reais | Component, Pin, Net, Constraint; resolução de .kicad_sym/.kicad_symdir; sem fallback genérico de dois pinos. |
| 2 — Tools semânticas | find_symbol, component_add, create_net, connect_pins, inspect_component; o LLM não desenha wires por coordenadas. |
| 3 — Semantic Composer | Circuit IR → placement → net graph → wires/labels/junctions → .kicad_sch → ERC real via kicad-cli. |
| 4 — Visual Reviewer | score visual, SVG/PDF real do KiCad, reflow determinístico e reviewer multimodal opcional. |
| 5 — Visual Auto-Fix | Layout Action IR tipado, copy-on-write, safety gates, ERC antes/depois e rollback quando o candidato piora. |
O resultado é um ciclo como este:
ChatGPT / Claude / outro cliente MCP
│
stdio ou Streamable HTTP
│
▼
Coppermind
│
▼
Circuit IR
│
▼
Semantic Composer
│
▼
.kicad_sch real
│
┌───────┴────────┐
▼ ▼
KiCad ERC SVG / PDF
│ │
└───────┬────────┘
▼
Visual Reviewer
│
Layout Action IR
│
accept / rollback
- Python 3.11+;
- KiCad 10+ para uso real;
kicad-clidisponível noPATHpara ERC/render headless;- para IPC ao vivo: extra Python
kicad-pythone API IPC habilitada no KiCad.
O projeto permanece na linha MCP Python SDK 1.x enquanto usa a API FastMCP:
mcp>=1.30,<2. Isso evita uma migração implícita para a API v2.
git clone https://github.com/charlesmmorais/coppermind.git
cd coppermind
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -e ".[ipc]"git clone https://github.com/charlesmmorais/coppermind.git
cd coppermind
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -e ".[ipc]"Para desenvolvimento:
pip install -e ".[dev,ipc]"
pytestNo KiCad, habilite a API IPC quando quiser operar uma instância aberta:
Preferences → Plugins → Enable IPC API Server
É o padrão e o melhor caminho para clientes MCP locais:
coppermindou explicitamente:
coppermind --transport stdiocoppermind \
--transport streamable-http \
--host 127.0.0.1 \
--port 8765 \
--path /mcpEndpoint:
http://127.0.0.1:8765/mcp
Também pode ser configurado por variáveis de ambiente:
COPPERMIND_TRANSPORT=streamable-http
COPPERMIND_HTTP_HOST=127.0.0.1
COPPERMIND_HTTP_PORT=8765
COPPERMIND_HTTP_PATH=/mcp
COPPERMIND_BACKEND=auto
coppermindNo PowerShell:
$env:COPPERMIND_TRANSPORT="streamable-http"
$env:COPPERMIND_HTTP_HOST="127.0.0.1"
$env:COPPERMIND_HTTP_PORT="8765"
$env:COPPERMIND_HTTP_PATH="/mcp"
$env:COPPERMIND_BACKEND="auto"
coppermindSegurança: o processo recusa bind em
0.0.0.0, IP de LAN ou hostname não loopback. Para ChatGPT ou outro cliente remoto, mantenha o Coppermind em127.0.0.1e coloque um túnel/gateway MCP autenticado na frente. Vejadocs/TRANSPORTES.md.
Exemplo claude_desktop_config.json:
{
"mcpServers": {
"coppermind": {
"command": "coppermind",
"args": ["--transport", "stdio"],
"env": {
"COPPERMIND_BACKEND": "auto",
"LOG_LEVEL": "INFO"
}
}
}
}Se coppermind não estiver no PATH, use o caminho absoluto do executável da
virtualenv.
O Coppermind agora fornece Streamable HTTP, mas 127.0.0.1 só existe na sua máquina.
Para um cliente em nuvem:
ChatGPT
│
│ MCP Streamable HTTP
▼
túnel/gateway MCP autenticado
│
▼
127.0.0.1:8765/mcp
│
▼
Coppermind → KiCad
O cliente/workspace precisa aceitar servidores MCP personalizados e tools de escrita para poder criar/modificar o esquemático. O transporte HTTP, sozinho, não concede essas permissões.
COPPERMIND_BACKEND=auto # IPC se estiver acessível; senão MemoryBackend
COPPERMIND_BACKEND=ipc # exige uma sessão KiCad IPC acessível
COPPERMIND_BACKEND=memory # desenvolvimento/offline| Backend | Uso principal |
|---|---|
MemoryBackend |
domínio/testes e trabalho offline |
IPCBackend |
interação com uma instância KiCad via kicad-python/kipy |
BatchBackend |
DRC/render/export headless com kicad-cli |
No KiCad 10, o caminho de esquemático é deliberadamente híbrido: o Circuit IR e o
composer geram o arquivo .kicad_sch; kicad-cli executa ERC e renderizações reais.
A evolução do IPC de esquemático no KiCad 11 poderá substituir partes dessa camada
sem mudar as tools semânticas.
As 9 tools de núcleo são orientadas à intenção elétrica:
project_create
find_symbol
component_add
create_net
connect_pins
inspect_component
design_preview
design_commit
design_rollback
Há ainda 5 tools de descoberta progressiva para acessar a cauda longa sem poluir o contexto do modelo:
list_tool_categories
get_category_tools
search_tools
get_tool_schema
execute_tool
Exemplo de autoria semântica:
find_symbol("resistor")
component_add(reference="R1", symbol="Device:R", value="10k")
component_add(reference="C1", symbol="Device:C", value="100nF")
create_net(name="SENSE")
connect_pins(net="SENSE", pins=["R1.2", "C1.1"])
design_preview()
design_commit()
As primitivas cruas de esquemático como symbol_add e wire_add ficam internas e
não são oferecidas ao agente. As operações PCB por coordenadas permanecem como
compatibilidade roteada, não como caminho principal.
design_preview e design_commit executam automaticamente o pipeline seguro de
esquemático:
Circuit IR
→ compose
→ visual review/reflow
→ serialização .kicad_sch
→ KiCad ERC
→ gate
Tools adicionais são descobertas sob demanda:
schematic_compose
schematic_erc
schematic_export_composed
schematic_visual_review
schematic_visual_optimize
schematic_visual_plan
schematic_visual_apply
schematic_visual_autofix
O auto-fix visual não altera a intenção elétrica. Só executa ações geométricas
tipadas e limitadas (move_near, align, compact_block etc.) sobre uma cópia do
esquemático. Se o score piorar, surgir nova violação ERC ou o Circuit IR mudar, o
candidato é descartado.
Documentação detalhada:
A revisão determinística funciona sem serviço externo. Para acrescentar um crítico multimodal, configure um provider compatível:
COPPERMIND_VISUAL_PROVIDER=openai
OPENAI_API_KEY=...
COPPERMIND_VISUAL_MODEL=<modelo-multimodal>Quando habilitado, o PDF real exportado pelo KiCad e um contexto limitado do Circuit IR são enviados ao provider. Não habilite essa opção para designs sensíveis sem avaliar a política de dados aplicável.
O núcleo histórico de PCB continua disponível: modelo transacional, DRC, undo/redo,
variantes, fornecedores, datasheets, exportação .kicad_pcb e Freerouting.
Para autorroteamento:
Fluxo resumido:
KiCad → Specctra DSN → Freerouting → SES → Coppermind
↓
preview / DRC
↓
commit / rollback
O Coppermind foi desenhado para impedir que o LLM vire um executor irrestrito:
- não executa Python arbitrário gerado pelo modelo;
- símbolos são resolvidos em bibliotecas reais do KiCad;
- símbolo inexistente falha explicitamente;
- Circuit IR é a fonte de verdade elétrica;
- alterações passam por preview/commit/rollback;
- ERC/DRC entram no gate;
- visual auto-fix opera copy-on-write e só em geometria;
- paths de arquivos usados por tools são validados;
- Streamable HTTP fica restrito a loopback;
- provider multimodal é opcional e possui fronteira de dados documentada.
O workflow de CI executa:
- Python 3.11 e 3.12;
- Ruff;
- pytest + cobertura;
- mypy;
- job de integração bloqueante com KiCad 10 real;
- serialização de esquemático, ERC, SVG/PDF e Visual Auto-Fix contra KiCad.
O objetivo é que afirmações críticas da arquitetura sejam verificadas pelo CI, não apenas descritas no README.
- Streamable HTTP é single-user por processo; não é um servidor multi-tenant.
- Não há autenticação embutida no endpoint HTTP; use túnel/gateway confiável.
- A criação de esquemático no KiCad 10 usa arquivo
.kicad_sch+kicad-cli; live schematic IPC será adotado quando a API adequada estiver estável. - O Visual Reviewer multimodal é probabilístico e opcional; os gates determinísticos continuam sendo a autoridade de segurança.
- O caminho de PCB ainda possui mais operações legadas baseadas em geometria do que o caminho de esquemático semântico.
- Revisão de engenharia continua necessária antes da fabricação de hardware.
Veja o índice em docs/README.md:
docs/ARQUITETURA.md— arquitetura atual e decisões;docs/TRANSPORTES.md— stdio, Streamable HTTP e túnel;docs/TRANSPORTS.md— transport guide in English;docs/MULTIMODAL_VISUAL_REVIEW.md;docs/VISUAL_AUTOFIX.md;docs/AUTORROTEAMENTO.md.
Antes de abrir um PR:
pip install -e ".[dev,ipc]"
ruff check src tests
pytest
mypy srcMantenha as invariantes centrais: intenção elétrica no Circuit IR, geometria derivada, progressive discovery, mudanças reversíveis e nenhuma execução arbitrária de código produzido por modelo.
MIT. Consulte LICENSE.
O Coppermind é uma ferramenta de assistência. ERC/DRC, regras e IA reduzem risco, mas não substituem validação elétrica, térmica, mecânica, regulatória e de segurança antes da fabricação.