# ikmcp

**A Model Context Protocol (MCP) server that makes an agent an expert at building
complete `ik` projects** — the firmware, its tests, and the virtual peripherals it
talks to. It pairs deep, always-accurate knowledge with a **live build / simulate /
test loop** backed by the real `ik8b` compiler, the `ik8bvm` AVR simulator, and the
`ikide` headless test runner. An agent can write `ik`, compile it, read genuine
diagnostics, run it on a simulated AVR core, model a missing peripheral, and get a
real PASS/FAIL test verdict — without hardware.

`ik` is a small, strongly typed, bare-metal language for 8-bit AVR microcontrollers
(no heap, no runtime; compiles straight to Intel HEX).

## One dependency, the whole stack

ikmcp is a standalone, decoupled project. Its single vendored dependency is the
**ikide** IDE (git submodule at `tools/ikide`), which itself carries `ik8b` and
`ik8bvm` as nested submodules. So one submodule gives language + compiler + VM +
the IDE's test/device runtime — and ikmcp resolves all of it relative to its own
root, never by coincidence of where it is checked out.

It is meant to be vendored back into the [ikide](https://github.com/isakruas/ikide)
IDE as a submodule under `tools/`, but it runs perfectly on its own.

## Two domains, kept separate

| Domain | Concerns | Tools | Resources | Code |
| :-- | :-- | :-- | :-- | :-- |
| **Language** | the ik language, ik8b compiler, ik8bvm VM | `ik_*` | `ik://` | `ikmcp/lang/` |
| **IDE** | the ikide test framework + virtual devices | `ide_*` | `ikide://` | `ikmcp/ide/` |

The IDE domain degrades gracefully: without the ikide checkout, the language tools
keep working and IDE tools say so.

## Highlights

- **Zero runtime dependencies.** The MCP protocol layer is pure Python stdlib;
  `python3 server.py` is the whole story. Nothing to `pip install`.
- **Knowledge that can't drift.** Reference, stdlib API, the grammar, the test/device
  APIs, the shipped device models, and example projects are read live from the pinned
  ikide checkout (plus a generated index for speed).
- **Ground truth, not guesses.** `ik_compile` / `ik_simulate` / `ide_run_tests` run the
  real tools so generated code is verified, not hallucinated.

## Quick start

```bash
git submodule update --init --recursive   # or: make deps  (clones ikide + ik8b + ik8bvm)
make build                                # build ik8b CLI + ikide binary (Docker)
make test                                 # end-to-end smoke test
python3 server.py                         # start the server on stdio
```

A fresh checkout builds the binaries once (`make build`, via Docker like the upstream
toolchain). Already have built binaries? Skip the build and point the server at them
with `IK8B_BIN` / `IKIDE_BIN`.

## Wiring it into an MCP client

The server speaks MCP over stdio; a host spawns it as a subprocess. See
[`examples/mcp.json`](examples/mcp.json):

```json
{ "mcpServers": { "ikmcp": { "command": "python3", "args": ["server.py"], "cwd": "/path/to/ikmcp" } } }
```

## Tools

### Language (`ik_*`)

| Tool | What it does |
| :--- | :--- |
| `ik_overview` | Curated cheat-sheet — sigils, the `value -> target` assignment, types, memory, interrupts. **Start here.** |
| `ik_grammar` | The full EBNF grammar. |
| `ik_reference` | A language-reference chapter (types, memory, statements, expressions, functions, interrupts, intrinsics, conditional-compilation, lexical, …). |
| `ik_intrinsics` | The compiler intrinsics (`@burn`, `@sei`, `@swtch`, …) with signatures. |
| `ik_vm_reference` | Deep ik8bvm reference: cores, SREG, memory map, instruction set, peripherals/IRQs, limits. |
| `ik_compiler_reference` | Deep ik8b internals: pipeline, SSA IR, register allocation, ABI/calling convention, ISR codegen, fixed-point. |
| `ik_tutorial` | Tutorial pages (installing, first program, tour, stdlib, interrupts). |
| `ik_stdlib_list` / `ik_stdlib_module` | The standard library: modules + full per-module API. |
| `ik_project_analyze` | Structural analysis of a multi-file project: import graph, effective `target` + where declared, `@main` entry, per-file symbols, cross-file problems. Exact parser, optional real-compile. |
| `ik_examples` | List / fetch bundled ik example programs. |
| `ik_search` | Full-text search across language docs, std sources, examples. |
| `ik_devices` / `ik_device_info` | Supported AVR targets (350) with memory specs. |
| `ik_compile` | **Compile** ik source with `ik8b`; HEX/IR + diagnostics. |
| `ik_check` | Fast compile-only check: `ok` + diagnostics (tight loop). |
| `ik_simulate` | **Run** on `ik8bvm`; register/SP/SREG dump, memory peeks, trace, IRQ injection. |
| `ik_status` | Resolved toolchain root + binary paths. |

### IDE (`ide_*`)

| Tool | What it does |
| :--- | :--- |
| `ide_overview` | How program + tests + virtual devices fit together. **Start here for the IDE side.** |
| `ide_test_api` | The full `tests/*.rhai` Bench API (drive/observe every peripheral + assertions). |
| `ide_test_template` | A starter test bench. |
| `ide_run_tests` | **Run** the headless `ikide test` runner; real PASS/FAIL (workspace or inline program+test). |
| `ide_device_api` | The full `devices/*.rhai` authoring contract (meta, pins, view, handlers, framebuffer). |
| `ide_device_template` | A starter virtual-device script. |
| `ide_devices` / `ide_device_script` | The 19 shipped device models; read any one's source. |
| `ide_examples` / `ide_example` | The bundled breadboard example projects (program + wiring + tests/devices). |
| `ide_search` | Full-text search across device scripts, the device guide, and example projects. |
| `ide_status` | Resolved ikide root + binary path. |

## Prompts (skills)

ikmcp also serves MCP **prompts** — reusable, parameterized workflows a host
surfaces as user-invokable slash-commands. Each expands into a directive playbook
that orchestrates the tools above and bakes in the gotchas an agent gets wrong
unaided (assignment direction, target inheritance, the SRAM-init stepping rule,
the ABI).

| Prompt | Guides the agent to… |
| :--- | :--- |
| `ik_new_project` | scaffold a new program from a plain-language goal, pick the target, write idiomatic ik, verify it. |
| `ik_write_tests` | write a `tests/*.rhai` bench for a program and run it headless for a real verdict. |
| `ik_model_device` | author a `devices/*.rhai` virtual peripheral and validate it against a program. |
| `ik_port_target` | port a program to another AVR target with `? target ==` guards. |
| `ik_debug` | diagnose a compile/sim failure using the real compiler and the reference. |
| `ik_review` | review a program/project for correctness, idiom, and SRAM fit. |

Knowledge is also exposed as MCP **resources**: language under `ik://`
(`ik://overview`, `ik://grammar`, `ik://reference/<topic>`, `ik://library/<module>`,
`ik://example/<name>`) and IDE under `ikide://` (`ikide://test-api`,
`ikide://device-api`, `ikide://device/<name>`, `ikide://example/<name>`).

## Layout

```
ikmcp/
  server.py              # launcher: python3 server.py
  ikmcp/
    protocol.py          # tiny MCP stdio JSON-RPC server (stdlib only)
    paths.py             # toolchain + IDE resolution (submodule / env / PATH)
    app.py               # assembles both domains + prompts onto one server
    prompts.py           # MCP prompts ("skills"): guided cross-domain workflows
    lang/                # LANGUAGE domain
      knowledge.py       # cheat-sheet + on-disk docs/std + VM/compiler refs + search
      toolchain.py       # drives ik8b / ik8bvm (compile, check, simulate, devices)
      project.py         # multi-file project intelligence (import graph, symbols)
      tools.py           # ik_* tool + ik:// resource registration
    ide/                 # IDE domain
      knowledge.py       # test/device APIs, shipped models, examples, templates
      runner.py          # drives `ikide test`
      tools.py           # ide_* tool + ikide:// resource registration
  data/
    lang/                # stdlib_index.json, vm_reference.md, compiler_internals.md
    ide/                 # test_api.json, device_api.json, device_catalog.json
  tests/smoke.py         # end-to-end test (both domains + live runner)
  tools/ikide/           # vendored submodule (ikide -> ik8b -> ik8bvm)
```

## Environment overrides

| Variable | Effect |
| :--- | :--- |
| `IKIDE_ROOT` | Use this ikide checkout instead of the vendored submodule. |
| `IK8B_ROOT` | Use this ik8b checkout (default `<ikide>/tools/ik8b`). |
| `IK8B_BIN` / `IKIDE_BIN` | Paths to prebuilt `ik8b` / `ikide` binaries. |

## License

Apache-2.0. The vendored `ikide` / `ik8b` / `ik8bvm` are under their own licenses.