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.