Coppermind
README.md
<div align="center">
# 🔶 Coppermind
### Copiloto de engenharia eletrônica para KiCad — MCP semântico, transacional e verificado
[](https://github.com/charlesmmorais/coppermind/actions/workflows/ci.yml)
[](LICENSE)
[](https://www.python.org/)
[](https://www.kicad.org/)
[](https://modelcontextprotocol.io/)
**🇧🇷 Português** · [🇺🇸 English](README.en.md)
</div>
---
> **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.
---
## Estado atual
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:
```text
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
```
---
## Instalação
### Requisitos
- Python **3.11+**;
- KiCad **10+** para uso real;
- `kicad-cli` disponível no `PATH` para ERC/render headless;
- para IPC ao vivo: extra Python `kicad-python` e 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.
### Linux/macOS
```bash
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]"
```
### Windows / PowerShell
```powershell
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:
```bash
pip install -e ".[dev,ipc]"
pytest
```
No KiCad, habilite a API IPC quando quiser operar uma instância aberta:
**Preferences → Plugins → Enable IPC API Server**
---
## Executando o servidor MCP
### Opção A — stdio
É o padrão e o melhor caminho para clientes MCP locais:
```bash
coppermind
```
ou explicitamente:
```bash
coppermind --transport stdio
```
### Opção B — Streamable HTTP
```bash
coppermind \
--transport streamable-http \
--host 127.0.0.1 \
--port 8765 \
--path /mcp
```
Endpoint:
```text
http://127.0.0.1:8765/mcp
```
Também pode ser configurado por variáveis de ambiente:
```bash
COPPERMIND_TRANSPORT=streamable-http
COPPERMIND_HTTP_HOST=127.0.0.1
COPPERMIND_HTTP_PORT=8765
COPPERMIND_HTTP_PATH=/mcp
COPPERMIND_BACKEND=auto
coppermind
```
No PowerShell:
```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"
coppermind
```
> **Seguranç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 em
> `127.0.0.1` e coloque um **túnel/gateway MCP autenticado** na frente. Veja
> [`docs/TRANSPORTES.md`](docs/TRANSPORTES.md).
---
## Conectando clientes MCP
### Claude Desktop / clientes locais
Exemplo `claude_desktop_config.json`:
```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.
### ChatGPT / cliente MCP remoto
O Coppermind agora fornece Streamable HTTP, mas `127.0.0.1` só existe na sua máquina.
Para um cliente em nuvem:
```text
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.
---
## Seleção do backend KiCad
```bash
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.
---
## Fluxo recomendado do agente
As **9 tools de núcleo** são orientadas à intenção elétrica:
```text
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:
```text
list_tool_categories
get_category_tools
search_tools
get_tool_schema
execute_tool
```
Exemplo de autoria semântica:
```text
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.
---
## Composer, ERC e revisão visual
`design_preview` e `design_commit` executam automaticamente o pipeline seguro de
esquemático:
```text
Circuit IR
→ compose
→ visual review/reflow
→ serialização .kicad_sch
→ KiCad ERC
→ gate
```
Tools adicionais são descobertas sob demanda:
```text
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:
- [`docs/MULTIMODAL_VISUAL_REVIEW.md`](docs/MULTIMODAL_VISUAL_REVIEW.md)
- [`docs/VISUAL_AUTOFIX.md`](docs/VISUAL_AUTOFIX.md)
---
## Reviewer multimodal opcional
A revisão determinística funciona sem serviço externo. Para acrescentar um crítico
multimodal, configure um provider compatível:
```bash
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.
---
## PCB, autorroteamento e integrações
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:
[`docs/AUTORROTEAMENTO.md`](docs/AUTORROTEAMENTO.md)
Fluxo resumido:
```text
KiCad → Specctra DSN → Freerouting → SES → Coppermind
↓
preview / DRC
↓
commit / rollback
```
---
## Garantias de segurança da arquitetura
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.
---
## Testes e CI
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.
---
## Limitações atuais
- 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.
---
## Documentação
Veja o índice em [`docs/README.md`](docs/README.md):
- [`docs/ARQUITETURA.md`](docs/ARQUITETURA.md) — arquitetura atual e decisões;
- [`docs/TRANSPORTES.md`](docs/TRANSPORTES.md) — stdio, Streamable HTTP e túnel;
- [`docs/TRANSPORTS.md`](docs/TRANSPORTS.md) — transport guide in English;
- [`docs/MULTIMODAL_VISUAL_REVIEW.md`](docs/MULTIMODAL_VISUAL_REVIEW.md);
- [`docs/VISUAL_AUTOFIX.md`](docs/VISUAL_AUTOFIX.md);
- [`docs/AUTORROTEAMENTO.md`](docs/AUTORROTEAMENTO.md).
---
## Contribuindo
Antes de abrir um PR:
```bash
pip install -e ".[dev,ipc]"
ruff check src tests
pytest
mypy src
```
Mantenha 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.
## Licença
MIT. Consulte [`LICENSE`](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.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo issues