tokymaker-mcp 0.2.1

Model Context Protocol server for Tokymaker — author Blockly programs, compile them, and flash the ESP32 maker board, from any AI assistant.

tokymaker-mcp

A Model Context Protocol (MCP) server that gives Claude — and other MCP-aware LLMs — access to the Tokymaker knowledge base, authoring tools, and (soon) BLE upload/control for the Tokymaker ESP32 maker board.

Status: Phase 6a alpha. This release ships read-only knowledge tools and resources plus per-session conversation memory. Authoring, compile, BLE upload, and hardware tools land in Phase 6b–6d.

📓 Debugging a stuck flow? Read LEARNINGS.md first. It collects the operational gotchas — the canonical flash recipe, case-sensitive block ids, the backend's two error sentinels, and the macOS Bluetooth/codesigning traps — that otherwise cost an hour each to rediscover.

What this is

The Tokymaker is a BLE-attached ESP32 maker board (5 inputs, 5 outputs, OLED, NeoPixel, optional motor shield, optional Pixy2 camera, optional Ottoky walker kit). Programs are authored in Google Blockly XML, compiled to Arduino C++ by Toky Labs' backend, and flashed over BLE.

This MCP server lets an LLM:

• Search an 82-family corpus of validated example programs.
• Look up any block in the dictionary (and its generated C++).
• Browse 14 sections of canonical idioms (the patterns cookbook).
• Answer hardware questions (pin map, mutex matrix, Adafruit feeds).
• Remember programs the user authored earlier in the session.

Prerequisites

• Python ≥ 3.11.
• (Optional, Phase 6b onwards) Node ≥ 20 for the local Blockly generator.

Install (development)

From the package directory:

pip install -e .

This installs the tokymaker-mcp console script and registers the MCP entry point.

The KB markdown and JSON live at ../ relative to this package — the "Tokymaker Knowledge base/" folder. The Phase 6a resource loader reads from there directly. Phase 6e will bundle the KB inside the wheel and install it to ~/.tokymaker-mcp/kb/.

macOS first-run setup (one click, no Terminal)

After installing the package, ask Claude:

"Set me up to use my Tokymaker."

Claude will call install_tokymaker_first_run. macOS will show: "Tokymaker MCP wants to use Bluetooth" — click Allow.

That's it. The bridge will auto-start on every login from then on.

Behind the scenes:

• Signed .app installed to /Applications/Tokymaker MCP.app
• LaunchAgent at ~/Library/LaunchAgents/com.tokylabs.tokymaker-bridge.plist
• Logs at ~/Library/Logs/tokymaker-bridge.log

To undo: ask "Uninstall the Tokymaker setup" → calls uninstall_tokymaker_first_run.

macOS BLE setup (sidecar approach, Phase 6f)

On macOS 14+ the Bluetooth permission (TCC) attaches to the process that launches a binary, not the binary itself. Claude Code cannot grant itself Bluetooth access, so a child it spawns will be denied. The fix is to invert the relationship: run a tiny bridge process from your Terminal (where Bluetooth permission is granted to Terminal.app), and the MCP server talks to it over localhost HTTP.

One-time setup:

1. Open Terminal.
2. cd into this package and activate the venv: source .venv/bin/activate.
3. Run: tokymaker-bridge.
4. The first time, macOS shows "Terminal wants to use Bluetooth" — click Allow.
5. Leave the bridge window open while you use Claude.

Daily use:

# Terminal window A — leave this running
tokymaker-bridge

# Then use Claude Code as normal in another window. The MCP server
# transparently routes BLE ops to the bridge.

Stop with Ctrl-C in the bridge window. Optional flags:

• tokymaker-bridge --port 8765 — custom TCP port (default 8765).
• tokymaker-bridge --demo — emulate a board for testing without hardware.

Validation: curl -H "Authorization: Bearer $(cat ~/.tokymaker-mcp/bridge.token)" http://127.0.0.1:8765/state should return {"ok": true, ...}.

If a hardware tool ever returns code: bridge_unavailable, the bridge isn't running — open Terminal and run tokymaker-bridge.

Legacy: the dist/tokymaker-mcp.app bundle is no longer the primary path. It still builds (make app) but is optional.

Configure Claude Desktop

Edit your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Add:

{
  "mcpServers": {
    "tokymaker": {
      "command": "tokymaker-mcp",
      "args": ["serve"]
    }
  }
}

Restart Claude Desktop. You should now see "tokymaker" in the MCP servers list, with 10 tools exposed.

First-run test

Open Claude Desktop and ask:

What Tokymaker blocks are available?

Claude should call list_blocks and summarize the categories.

What works in Phase 6a

• All 7 Tier-1a knowledge tools:
  • search_families, get_family, get_block, list_blocks, list_patterns, get_pattern, get_hardware.
• All 3 Tier-1b conversation-memory tools:
  • list_my_programs, get_my_program, delete_my_program.
• 16 read-only resources (see tokymaker:// URIs).
• The orientation text wired into the MCP instructions field, so Claude reads the cardinal rules on session start.
• CLI: serve, version, config show, config reset, memory list, memory clear.

What doesn't work yet

• validate_xml, compile_xml, xml_to_arduino_preview — Phase 6b.
• synthesize_agent_folder, auto_scaffold_live_control — Phase 6b.
• All BLE tools (connect_board, upload_program, slider_write, …) — Phase 6c.
• doctor, setup, migrate — Phase 6d.
• Demo mode (virtual board) — Phase 6c.

Logs

JSON-lines logs are written to:

• macOS / Linux: ~/.tokymaker-mcp/logs/<YYYY-MM-DD>.log
• Windows: %APPDATA%\tokymaker-mcp\logs\<YYYY-MM-DD>.log

Run tokymaker-mcp config show to see the active config.

Uninstall

pip uninstall tokymaker-mcp
rm -rf ~/.tokymaker-mcp

Smoke check (manual)

Open Claude Desktop with the MCP wired up and try each of these:

1. "What Tokymaker projects do you know about?" → Claude should call search_families and list categories.
2. "Tell me about the snake game." → Claude should call get_family("tokysnake") (or similar) and summarize.
3. "What does the setserialrgb block do?" → Claude should call get_block("setserialrgb").
4. "Show me the LLM-controllable pattern." → Claude should call get_pattern for the relevant section.
5. "What pins are free if I'm using a NeoPixel strip?" → Claude should call get_hardware.
6. "Save what we talked about as 'tokymaker exploration session'." → Claude should call the memory tools.

Phase 6c: Hardware

Phase 6c ships the BLE stack, the demo-mode virtual board, and 14 new tools:

• Tier 3 (hardware, 12): list_boards, connect_board, disconnect_board, get_state, upload_program, stop_program, tail_console, read_logs, slider_write, sensor_subscribe, inject_button, emergency_stop.
• Tier 4 (lifecycle, 4): flash_firmware (gated), reset_board, clear_upload_lock (gated), doctor (surface stub — full check in Phase 6d).
• Tier 5 (onboarding, 1): name_board.

Two ways to try it

With a real board:

tokymaker-mcp serve

Then in Claude Desktop / Claude Code:

Find my Tokymaker.

The LLM should call list_boards, then connect_board.

Without a board (demo mode):

tokymaker-mcp serve --demo

A synthetic Tokymaker_virtual-DEMO board is injected as the active client. All hardware tools succeed end-to-end with simulated: true in their responses. You can also set the env var TOKYMAKER_DEMO=1 to opt in.

No BLE at all:

tokymaker-mcp serve --no-ble

Hardware tools return ble_disabled; knowledge/authoring tools work as normal. Useful for kiosks and CI.

CLI additions

tokymaker-mcp boards list             # show saved boards
tokymaker-mcp boards forget <name>    # remove one

Smoke checks for the user

1. Demo — "Find my Tokymaker" → list_boards + connect_board succeed with simulated: true.
2. Demo — "Upload a snake game" → if Phase 6b's compile pipeline is wired in, the full path runs; otherwise the response is compile_unavailable with a clear "use patch_bin_b64 or wait for 6b" hint.
3. Demo — "Read the sensors for 5 seconds" → sensor_subscribe returns samples for slider0..2 and uptime_s.
4. Demo — "Set slider 0 to 200" → slider_write succeeds; subsequent sensor_subscribe shows slider0 = 200.
5. Real board — same first four prompts.
6. Real board — "Stop the program" → uploads the 8-byte empty-stop patch (stop_program).
7. Any time — "Emergency stop." → emergency_stop always succeeds when at all possible; preempts any in-flight upload.

Logs

Phase 6c logs every BLE op acquire/release at INFO and every watchdog force-release at WARN under ~/.tokymaker-mcp/logs/<YYYY-MM-DD>.log.

Phase 6b: Authoring

Phase 6b adds the authoring layer — XML validator, headless Blockly Arduino generator bridge, Tokymaker compile-backend client, and six Tier-2 tools:

• validate_xml — runs the 42-check catalog (mcp-tool-spec-v2 §4) plus quality lints. Returns errors / warnings / infos plus stats.
• xml_to_arduino_preview — local-only: XML → C++ via the headless Blockly generator. No backend call.
• compile_xml — end-to-end: validate → generate → /sendCode → /getHex. Caches the patch.bin in ~/.tokymaker-mcp/cache/latest.bin ready for Phase 6c's upload_program.
• inspect_program_io — parse the XML's webApp_send/webApp_receive contract (with slot 0..2), design blocks, and target-language hint. When called without xml, reads the cached current_program from state.
• synthesize_agent_folder — write the canonical scaffold to disk (~/Tokymaker/agents/<FOLDER_BTN>/) for webApp_design, aiAgent_design, and aiModel_design blocks. Does NOT call /api/webapp-generate in v1 — that's deferred to v2.
• auto_scaffold_live_control — given a source XML and a list of {name, role, hardware} declarations, return XML with the webApp_design + webApp_send/webApp_receive scaffold inserted.

New prerequisites

• Node ≥ 20 on PATH (or set [generator] node_path in config.toml). The validator works without Node, but xml_to_arduino_preview and compile_xml will return node_missing unless Node is available.
• Vendored Blockly fork — the Tokymaker Blockly fork shipped under <repo>/blockly/. The Node bridge picks this up automatically via paths.kb_root(). Override with $TOKYMAKER_MCP_BLOCKLY_ROOT if needed.

Smoke checks (after pip install -e .)

1. Validate — "Validate this XML:" paste any of the bundled fixtures under tests/fixtures/xml_samples/ (e.g. minimal.xml). Expect ok=true and an info-level finding pointing out that there are no webApp_* blocks.
2. Author me a snake game — full path: search_families → get_family snake-clone → fetch XML resource → validate_xml → compile_xml. The patch.bin lands in ~/.tokymaker-mcp/cache/latest.bin ready for upload.
3. Make me an LLM-controllable robot template — exercise auto_scaffold_live_control with [{name: "tilt", role: "sensor"}, {name: "led", role: "actuator"}] → feed the resulting XML to synthesize_agent_folder → confirm ~/Tokymaker/agents/<slug>/ contains index.html and prompt.txt.

Configuration additions

~/.tokymaker-mcp/config.toml now also accepts:

[backend]
url = "https://create.dev.tokylabs.com"
sendcode_timeout_s = 30
gethex_timeout_s = 10
retry_attempts = 2
retry_backoff_seconds = [1, 2]
circuit_breaker_threshold = 5
circuit_breaker_trip_seconds = 30
url_safety_limit_bytes = 7800

[generator]
node_path = "node"
node_timeout_ms = 5000
blockly_path = "../../blockly"

[authoring]
agents_dir = "~/Tokymaker/agents"

macOS BLE setup (Phase 6d)

Real-hardware Bluetooth control requires a properly-sealed .app bundle so macOS TCC can attach the NSBluetoothAlwaysUsageDescription entitlement to the Python process that calls CoreBluetooth. The dev install (pip install -e .) cannot get that entitlement because patching an existing Python's Info.plist breaks its code signature; py2app produces a fresh bundle with the key declared from build time.

Build

cd tokymaker-mcp
source .venv/bin/activate     # python.org Python 3.12.x, not Homebrew
make app

This runs python setup-app.py py2app, ad-hoc signs the bundle, and verifies the seal. Output: dist/tokymaker-mcp.app/.

Verify BLE works through the bundle

From a regular Terminal.app / iTerm2 window (not from inside another app like Claude Code):

./dist/tokymaker-mcp.app/Contents/MacOS/tokymaker-mcp serve --self-test-ble

The first time, macOS pops up:

"Tokymaker MCP" wants to use Bluetooth. [Don't Allow] [Allow]

Click Allow. The command then prints BLE OK — found N device(s) and exits 0. Subsequent scans run without prompting.

If you instead see exit code 134 (SIGABRT) with no output, check ~/Library/Logs/DiagnosticReports/tokymaker-mcp-*.ips. The most common cause is TCC responsibility-chain inheritance — when a parent process (e.g. Claude Code, VS Code's integrated terminal, or any app launched without going through Launch Services) spawns the bundle, macOS attributes the Bluetooth request to the parent's bundle identifier and checks its Info.plist for the usage description. Always run the first BLE consent from a plain Terminal session; subsequent launches from other processes inherit the grant.

Wire into Claude Code

Update your project's .mcp.json to point at the bundle (NOT the dev venv's tokymaker-mcp script) and drop --demo:

{
  "mcpServers": {
    "tokymaker": {
      "command": "/abs/path/to/tokymaker-mcp/dist/tokymaker-mcp.app/Contents/MacOS/tokymaker-mcp",
      "args": ["serve"]
    }
  }
}

Then restart Claude Code. Real-hardware tools (scan_for_boards, connect_board, upload_program_tool, slider_write_tool, etc.) now talk to actual Tokymaker boards over BLE.

What's bundled vs. external

Component	Bundle path	Source
Python 3.12 framework	Contents/Frameworks/Python.framework/	python.org installer
Site-packages (bleak, mcp, lxml, pydantic, rich, pyobjc, …)	Contents/Resources/lib/python3.12/	venv
tokymaker_mcp package	same	this repo
KB markdown + blocks.json	Contents/Resources/kb/	parent dir
Blockly fork (5 files needed by generate.mjs)	Contents/Resources/blockly/	parent dir
Node 20+ (used by the generator subprocess)	NOT bundled	system PATH

The bundled KB and Blockly paths are picked up by tokymaker_mcp.paths.app_bundle_root() — see paths.py for the resolution order.

License

Apache 2.0. See LICENSE.