# robo-mcp

A local, offline [MCP](https://modelcontextprotocol.io) server that helps you plan
Arduino/ESP32/Raspberry Pi robotics builds: correct pinouts, wiring diagrams, board
pinout references, and code skeletons — all checked against real component specs
instead of generated from memory.

## Why this exists

LLMs are good at *reasoning about* a build and bad at *remembering exact pinout
facts*. This server doesn't try to fix that with more prompting — it hands the
calling model a small, verified knowledge base (board/component JSON, cross-checked
against Fritzing, KiCad, and PlatformIO data) plus deterministic renderers and
checkers. **The server itself never calls an AI model.** Every tool either looks
up grounded data, runs a deterministic rule/graph check, or shells out to an
external verifier (arduino-cli, cppcheck, mypy). All the actual reasoning about
what to build happens in your own Claude/LLM session, on your own credits.

## Status

Under active development. See the build phases below for what's implemented.

- [x] Phase 1 — data modeling: JSON Schema, 3 boards (Arduino Uno, ESP32 DevKit,
      Raspberry Pi), 12 components, domain compatibility rules
- [x] Phase 2 — renderers: `generate_wiring_diagram` (schemdraw) and
      `generate_pinout_reference` (schemdraw, see note below)
- [ ] Phase 3 — MCP server wiring
- [ ] Phase 4 — end-to-end acceptance test against Claude Desktop
- [ ] Phase 5 — grow to ~15-20 components
- [ ] Phase 6 — packaging + docs (PyPI, supported-hardware table, CONTRIBUTING.md)
- [ ] Phase 7 — SKiDL structural ERC, layout preview, verify_code, generate_mount

### Note: boardgen was dropped

The original design called for `boardgen` (ltchiptool's pinout diagram tool) to
power `generate_pinout_reference`. In practice it's built specifically for bare
chip-*package* pinouts using LibreTiny's own hand-authored SVG shape templates,
and has no template for a full Arduino Uno/ESP32 DevKit/Raspberry Pi board
outline — building one would mean recreating a chunk of that project's own art
assets just to use the library. `generate_pinout_reference` is implemented with
`schemdraw` instead (the same rendering stack `generate_wiring_diagram` already
uses), rendering the same contract: a full physical pinout diagram of one
board, independent of any project, cached per board.

## Installation

Not yet published to PyPI. For local development:

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

## License and dependency discipline

This project is MIT licensed. Everything **imported** into the package is
MIT/Apache/BSD/CC0/PSF licensed (see `pyproject.toml`). Some verification tools
used by `verify_code` are GPL-licensed (`arduino-cli`'s toolchain, `cppcheck`,
`clang-tidy`) — these are **never vendored or imported**. They are invoked as
separately-installed external binaries via `subprocess`, auto-detected on
`PATH`, and skipped gracefully with a note if not installed. You must install
them yourself if you want that verification path:

- [arduino-cli](https://arduino.github.io/arduino-cli/) — required for the
  Arduino `verify_code` path
- [cppcheck](https://cppcheck.sourceforge.io/) — optional static analysis
- [clang-tidy](https://clang.llvm.org/extra/clang-tidy/) — optional static analysis

No hosted/remote server, no required network access, no API keys. Works fully
offline after `pip install`.

## Data sources

Board and component specs are cross-checked against:

- [Fritzing parts library](https://github.com/fritzing/fritzing-parts) (CC BY-SA)
- [KiCad symbol/footprint libraries](https://gitlab.com/kicad/libraries) (CC-BY-SA-4.0)
- [PlatformIO board definitions](https://github.com/platformio/platformio-core) (Apache-2.0)
- manufacturer datasheets (linked in each component's `sources` field)

## Contributing

Adding a new board or component is a one-JSON-file contribution — see
`src/robomcp/schema/` for the JSON Schemas and `src/robomcp/data/` for examples.
(Full CONTRIBUTING.md coming in the packaging phase.)

## License

MIT — see [LICENSE](LICENSE).