Metadata-Version: 2.4
Name: tokymaker-mcp
Version: 0.2.1
Summary: Model Context Protocol server for Tokymaker — author Blockly programs, compile them, and flash the ESP32 maker board, from any AI assistant.
Author: Toky Labs / Tokymaker contributors
License: Apache-2.0
Project-URL: Homepage, https://tokylabs.com
Project-URL: Repository, https://gitlab.com/eduardotokylabs/tokymaker-mcp
Project-URL: Issues, https://gitlab.com/eduardotokylabs/tokymaker-mcp/-/issues
Keywords: mcp,model-context-protocol,tokymaker,blockly,esp32,robotics,stem,education,claude
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Education
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0
Requires-Dist: pydantic>=2.7
Requires-Dist: platformdirs>=4.2
Requires-Dist: lxml>=5.0
Requires-Dist: rich>=13.0
Requires-Dist: bleak>=0.21
Requires-Dist: fastapi>=0.115
Requires-Dist: uvicorn[standard]>=0.30
Requires-Dist: httpx>=0.27
Requires-Dist: sse-starlette>=2.1
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: black>=24; extra == "dev"
Requires-Dist: respx>=0.22; extra == "dev"
Dynamic: license-file

# 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](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:

```bash
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:**

```bash
# 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:

```json
{
  "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

```bash
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:**

```bash
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):**

```bash
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:**

```bash
tokymaker-mcp serve --no-ble
```

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

### CLI additions

```bash
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:

```toml
[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

```bash
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):

```bash
./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`:

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