Skip to main content
Glama
ltp3-mcp

ltp3-mcp

by RomeoCoding
README.md
# ltp3-mcp

The first open-source MCP server and Python library for Analog Devices' LTpowerPlanner power-tree files (`.ltp3`, `.ltp3t`): read them losslessly, solve their power budget, edit them safely, and let an AI assistant do the same.

> **Disclaimer.** Not affiliated with, endorsed by or supported by Analog Devices, Inc.
> LTpowerPlanner, LTpowerCAD and LTspice are trademarks of Analog Devices. This project ships no ADI
> software or files, reads and writes only files you create with your own licensed copy, and was built
> from data files alone, without decompiling any ADI software.

## What you can do

Ask your assistant, with a power tree open:

- *"Where does this design lose the most power, and which rail is worth optimising first?"* (explain losses)
- *"Add a 1.8 V LDO off the 3.3 V rail for a new sensor drawing 150 mA, wire it up, and save a copy."* (add a rail)
- *"Compare the buck-LDO version of this tree against the all-buck version: total input power and efficiency."* (compare architectures)

Without an assistant, the same engine is a library and a command line: `ltp3 solve my_tree.ltp3`.

## Quickstart

Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/). The package is not on PyPI yet; install from the repository.

```
git clone https://github.com/RomeoCoding/ltp3-mcp
cd ltp3-mcp
uv sync
```

Register the server with Claude Code (replace the placeholder paths):

```
claude mcp add ltp3 --scope user -e LTP3_ALLOWED_DIRS=C:\work\power-trees -- uv run --directory C:\path\to\ltp3-mcp ltp3-mcp
```

Claude Desktop, other stdio clients and the environment variables are in [docs/CLIENTS.md](docs/CLIENTS.md).
`LTP3_ALLOWED_DIRS` lists the folders the server may write to (default: its working directory).
`LTP3_TEMPLATE_DIR` points at the factory templates (default: the standard LTpowerPlanner III install).

Command line:

```
uv run ltp3 solve my_tree.ltp3 [--tab N] [--json]
uv run ltp3 validate my_tree.ltp3         # exit 1 on errors; --strict also fails on warnings
uv run ltp3 diff before.ltp3 after.ltp3   # exit 1 if they differ
uv run ltp3 export my_tree.ltp3 [-o tree.json]
uv run ltp3 templates --vendor Xilinx --search artix
uv run ltp3 roundtrip my_tree.ltp3        # parse + serialise reproduces the bytes?
```

Exit codes: `0` success, `1` the check found something, `2` usage or I/O error.

## Tools

22 MCP tools, grouped by purpose.

| Purpose | Tools |
|---|---|
| Find and open | `list_templates`, `open_tree`, `new_tree`, `close_tree` |
| Inspect | `describe_tree`, `list_parts`, `get_part`, `list_nets` |
| Analyse | `solve`, `validate`, `compare_trees`, `export_json` |
| Edit (in memory) | `set_property`, `rename_part`, `add_part`, `remove_part`, `connect`, `disconnect`, `move_part`, `undo`, `preview_changes` |
| Write to disk | `save_tree` |

Nothing reaches disk until `save_tree`.

## Accuracy

The solver is checked against the application itself. I ran **Calculate** in LTpowerPlanner III 3.6.8 on trees I built and compared its summary with this project's output. Every row matches exactly at the 2-decimal display precision ([docs/ORACLES.md](docs/ORACLES.md)).

| Tree | Pin (W) | Pout (W) | Ploss (W) | Eff (%) |
|---|---|---|---|---|
| Artix-7 Basys 3 template (two bucks, three loads) | 16.67 | 14.70 | 1.97 | 88.16 |
| 5 V, LDO 3.3 V, 1 A load | 5 | 3.3 | 1.7 | 66 |
| 12 V, buck 5 V, buck 1 V, 2 A load (cascade) | 2.78 | 2 | 0.78 | 72 |
| 5 V, 0.5 ohm resistor, 2 A load | 10 | 8 | 2 | 80 |
| Editor output: dual converter | 18.94 | 16.66 | 2.28 | 87.96 |
| Editor output: converter plus LDO | 18.17 | 15.24 | 2.93 | 83.85 |
| Editor output: split output | 17.19 | 15.15 | 2.04 | 88.15 |

The last three files were generated by this project's editor from the Artix-7 tree, opened in the GUI without errors, and Calculate ran on them. N is 7 trees (28 values), so this is a small oracle set: treat it as evidence for the rules it covers, not a proof for every construct.

**Corpus** (run against the factory templates installed with the application, read in place):

- 261 of 261 templates round-trip byte-exact through the parser and serialiser.
- 382 of 444 tabs solve completely. The other 62 are blocked, not guessed, for three reasons: 42 use non-manual efficiency models (`MatrixA` efficiency curves, `pLossSet`), 20 have several drivers on one net, and 1 has a non-zero LDO ground current.
- The `<ORal>` output-rail headers stored in templates agree character-for-character with the solver on 177 of 261 templates. This is a cross-check, not a pass rate: the headers were written by older application versions. Every disagreement on a fully solved template was classified by hand, and none came from a solver error. They were unit-string quirks in the header (e.g. `5.5AmA`), headers cut off at 98 characters (ours matches the prefix), headers that ignore the milliamp unit, and one resistor default that has since been fixed ([docs/SOLVER.md](docs/SOLVER.md)).

**Confirmed versus assumed.** Rules confirmed by an oracle: converter efficiency, totals and rounding, ideal sources, LDO and cascade current, resistor drop, and the load-current radio. Rules that are plausible but unconfirmed (unit exponents on `IpeakU`, net-label merging, the peak-efficiency radio) are computed and reported as assumptions in every result, never silently. The full table with the test behind each rule is in [docs/SOLVER.md](docs/SOLVER.md).

Omitted keys mean "the application's default", not "unknown": LTpowerPlanner leaves out values equal to their defaults, and the solver reads them the same way (details in [docs/ORACLES.md](docs/ORACLES.md)).

## Safety

- **Validation before save.** `save_tree` runs the validator; errors block the write.
- **Atomic write plus backup.** The file is written to a temporary name and swapped in. Overwriting first copies the old file to `name.ltp3.bak-<timestamp>`, and a file changed by the GUI since you opened it gives `STALE_FILE`.
- **Never overwrites by default.** An existing target fails with `FILE_EXISTS`; overwrite is an explicit choice.
- **Refuses the install folder.** Nothing is written inside Program Files or the LTpowerPlanner install tree, only `.ltp3` files are writable (templates are read-only), and writes stay inside `LTP3_ALLOWED_DIRS`.
- **Round-trip guard.** Before saving, the output is re-parsed and compared with the edited tree.

## Limitations

- No `MatrixA` efficiency curves or `pLossSet` models: tabs using them report `B-EFFICIENCY-MODEL` and an incomplete solve.
- No nets with several drivers (`B-MULTI-DRIVER`), and no LDO ground current (`Ignd`).
- Layout is cosmetic-quality: new parts and wires may overlap the Summary box, and moving a part does not move its free-standing labels. See [docs/BACKLOG.md](docs/BACKLOG.md).
- `new_tree` is experimental; prefer editing a file the application wrote.
- Windows-first. Tested against LTpowerPlanner III 3.6.8; the corpus covers file versions 3.0.3 to 3.5.4. Other versions may use keys or defaults this project has not seen.

## How it works

`.ltp3` is plain text (UTF-8, or Windows-1252 in some older files, sometimes with a BOM) with two line shapes: `<Tag> args` lines and tab-indented `Key : value` lines. The parser keeps every line, separator and line ending as found, so unedited files serialise byte-for-byte and an edit changes only the lines it touches. A typed model, a net graph, the solver, validator, differ and JSON exporter sit on top of that layer. Format notes, with every statement tagged confirmed or hypothesis, are in [docs/FORMAT.md](docs/FORMAT.md). The design is in [docs/PLAN.md](docs/PLAN.md).

## Development

```
uv sync
uv run pytest -q
uv run ruff check . && uv run ruff format --check . && uv run mypy --strict src
```

Corpus tests read the factory templates in place through `LTP3_TEMPLATE_DIR` and skip cleanly when the folder is absent, which is the case in CI. The templates are never copied into the repository, and a hygiene test fails if one is tracked. See [CONTRIBUTING.md](CONTRIBUTING.md).

## Licence

MIT, see [LICENSE](LICENSE).