ikmcp

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 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

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:

{ "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.