Skip to main content
Glama
Kairo

Kairo

by JoshChomps
README.md
# Kairo

An MCP server that turns a described circuit into a checked KiCad project.
Every voltage and current is worked out twice, by formulas with cited
sources and by simulation (ngspice and Xyce), and anything that could not
be checked is marked unverified instead of guessed.

Kairo gives a model in any MCP client the tools to design and check
electronics without making numbers up:

- **Designs from a description.** Pins come only from the KiCad libraries,
  never from memory; each build is checked by KiCad's own netlist and
  electrical rules check before anything is written.
- **Numbers with sources.** Every value comes from a formula with a cited
  source and its worst case over the parts' tolerances; each requirement is
  pass, fail or unverified, with what would settle it.
- **Simulation in two engines.** ngspice and Xyce, judged at the worst case;
  Monte Carlo is a report and never decides.
- **Schematics you drew.** Read any KiCad project, check it against the
  facts you state, simulate parts of it, and change values or parts with
  KiCad confirming nothing else moved.
- **Real parts.** Resistors, capacitors, inductors, LEDs and regulators
  from a parts catalogue; datasheets fetched and their limit tables read.
- **Boards.** Placement by block and edge, pours, Kairo's own router, and
  KiCad's DRC against net classes and voltage spacing, with fab files.
- **A review.** Faults and suggestions, each with its source: rails with no
  decoupling, switches bypassed by a body diode, floating inputs, crossed
  UARTs, and on a prototype, rails with no test point, light or link to
  open, and spare I/O left unreachable.

## Install

You need [uv](https://docs.astral.sh/uv/) and
[KiCad](https://www.kicad.org/download/) 10. No release is published
yet, so install from a clone of this repository, which also needs
[Rust](https://rustup.rs/). Releases will carry a desktop extension
(`kairo.mcpb`) and a wheel for Windows, macOS and Linux. See
[docs/getting-started.md](docs/getting-started.md) for each client.

Then ask for a circuit in your own words:

> A 3.3 V rail from 5 V USB for a sensor that draws 120 mA

## Documentation

- [Getting started](docs/getting-started.md): install, connect, the tools
  and their tiers.
- [Board layout](docs/board-layout.md) and
  [router design](docs/router-design.md): how boards are made.
- [Reference](docs/reference/index.md): designs as JSON and as text,
  the command line, simulation, KiCad and the libraries.
- [Design decisions](docs/assumptions.md): each choice made, and why.
- [Research](docs/research.md): what was studied, and what Kairo took from
  it, credited.
- [Writing code and docs](docs/development.md), for contributors.

## Development

```bash
uv sync                                       # builds the compiled loops; needs Rust
uv run pytest -m "not kicad and not spice"    # drop -m when KiCad and ngspice are installed
uv run ruff check && uv run ruff format --check && uv run pyright
uv run sphinx-build -W docs docs/_build/html  # the documentation site
```

## Licence

GNU Affero General Public License v3.0 only (AGPL-3.0-only); see
[LICENSE](LICENSE). Kairo is free to use, share and change. Anyone who
shares a changed Kairo, or runs one as a service for others, must offer
its source under the same licence, so it stays free.

The circuits are yours. The licence covers Kairo's own code, not the
schematics, boards and other files it writes for you; those carry no
terms from Kairo.

Versions published before 6 November 2026 were released under the
Apache License 2.0. Third-party licences, and the licences of the
open-hardware boards used as test data, are listed in [NOTICE](NOTICE).