tokymaker-mcp 0.2.0__tar.gz

tokymaker_mcp-0.2.0/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer or hardware failure or malfunction, or any
+      and all other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a
+      fee for, acceptance of support, warranty, indemnity, or other
+      liability obligations and/or rights consistent with this License.
+      However, in accepting such obligations, You may act only on Your
+      own behalf and on Your sole responsibility, not on behalf of any
+      other Contributor, and only if You agree to indemnify, defend,
+      and hold each Contributor harmless for any liability incurred by,
+      or claims asserted against, such Contributor by reason of your
+      accepting any such warranty or support.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Toky Labs and Tokymaker contributors.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

tokymaker_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,471 @@
+Metadata-Version: 2.4
+Name: tokymaker-mcp
+Version: 0.2.0
+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`.