hackshop-mcp 0.0.4 → 0.0.5

package/README.md

@@ -14,27 +14,33 @@ Hackshop now knows about Meta's Muse Gadgets SDK: ESP32 boards and Linux machine
 
 ## Status
 
-v0.0.4 — published on npm. Install with `npx hackshop-mcp` or add it to your MCP client config. Four tools (`propose_hardware`, `assess_hackability`, `plan_gadget`, `simulate_assembly`), 80 devices. The simulation layer is live at [hackshop.dev](https://hackshop.dev).
+v0.0.5 - published on npm and hosted at `https://www.hackshop.dev/mcp`. The hosted MCP exposes the deterministic tools (`plan_gadget`, `get_build_plan`, `assess_hackability`); the npm server also includes `propose_hardware` and `simulate_assembly`. The simulation layer is live at [hackshop.dev](https://hackshop.dev).
 
 ## Install in 30 seconds
 
-Add to your MCP client config (Claude Desktop / Claude Code / Cursor):
+Hosted connector, when your client supports streamable HTTP:
+
+```json
+{
+  "url": "https://www.hackshop.dev/mcp",
+  "transport": "streamable-http"
+}
+```
+
+Or add the local npm server to your MCP client config (Claude Desktop / Claude Code / Cursor):
 
 ```json
 {
   "mcpServers": {
     "hackshop": {
       "command": "npx",
-      "args": ["-y", "hackshop-mcp"],
-      "env": {
-        "ANTHROPIC_API_KEY": "sk-ant-..."
-      }
+      "args": ["-y", "hackshop-mcp"]
     }
   }
 }
 ```
 
-The `ANTHROPIC_API_KEY` env var is **optional but recommended**. The server first tries `sampling/createMessage` (host-delegated reasoning, no key needed). If your host doesn't support that — many don't yet — the server falls back to a direct Anthropic API call when this key is set. Without it, you'll get raw catalog matches in degraded mode.
+`ANTHROPIC_API_KEY` is optional. It only improves `propose_hardware` in the local npm server when the MCP host cannot sample; `plan_gadget`, `get_build_plan`, and `assess_hackability` never need a key. Anonymous usage telemetry (tool names and timings only) is on by default in the npm server; set `HACKSHOP_TELEMETRY=0` to turn it off.
 
 ## Tools
 
@@ -55,18 +61,31 @@ Returns 3-5 hardware proposals, each with:
 
 Lookup by id, exact name, or substring. Returns the same shape as a single proposal. Use when you have a device in mind and want to verify hackability before searching for one to buy.
 
-### `plan_gadget(idea, platform?, budget_usd?, owned_device_ids?, needs?, limit?)`
+### `plan_gadget(idea, platform?, budget_usd?, owned_device_ids?, needs?, size?, limit?)`
 
 Deterministically plans a physical gadget for an AI agent, with Meta Muse Gadgets as the first supported platform. It infers needs such as voice, screen, camera, air sensors, e-paper, round display, home-network tunnel, or Linux control; ranks supported boards; and returns:
 
-- `inferred_needs` and ranked `picks`
-- each pick's Muse platform, support level, tier, score, concrete `why`, gaps, price label, firmware/build links, setup steps, and caveats
+- `inferred_needs`, `fit` (`all | partial | none`), `notes`, `warnings`, `questions`, and ranked `picks`
+- each pick's Muse platform, support level, tier, score, concrete `why`, gaps, `needs_met`, `within_budget`, price label, firmware/build links, setup steps, and caveats
 - `fabrication.printables` with STL/STEP/SVG/fab.json URLs when a stand or enclosure exists
 - Muse SDK `terms` for every platform represented in the picks
-- concrete `next_steps`
+- concrete `next_steps`, starting with the build page where the human can save progress
 
 This tool does not call an LLM and does not use the network. It never suggests selling Muse devices; the Muse SDK token terms are personal and non-commercial.
 
+### `get_build_plan(device_id)`
+
+Returns the full, deterministic build plan for one device: parts (with store or search links), `shopping_list` with explicit purchase policy, numbered steps with exact commands, machine-readable `assembly`, `try_saying` prompts, caveats, the Muse SDK terms, and `agent_brief_md`, a self-contained Markdown brief a coding agent can follow. It also returns the human page (`https://www.hackshop.dev/build/<device_id>`), raw JSON (`/build/<device_id>/plan.json`) and raw brief (`/build/<device_id>/build.md`). It never buys anything; ordering parts is left to the human.
+
+## Resources and Prompts
+
+Both hosted MCP and npm expose:
+
+- `hackshop://muse/boards` - JSON for every Muse board: ids, names, platform, tier, price, features, build command and build page URL.
+- `hackshop://muse/sdk-terms` - text summary of Muse SDK token terms.
+- `hackshop://catalog/tags` - catalog tag list.
+- Prompt `plan-muse-gadget` - tells an agent to do intake, call `plan_gadget`, call `get_build_plan`, show the shopping list, ask before buying, assemble, flash and pair.
+
 ### `simulate_assembly(assembly)`
 
 Takes an **Assembly IR** — `{ idea, components[{ref,device_id,name,role}], edges[], goal{kind,spec,success_metric}, world{template,goal_xy?} }` (build it from the site's assembly output or by hand) — drops it into a MuJoCo physics world, and runs a **bounded, synchronous** rollout (`duration_s` ≤ 10, default 8) on the sim-worker. It returns:
@@ -100,7 +119,7 @@ The `simulate_assembly` MCP tool above is the bounded, single-call entry point i
 ## Architecture
 
 - TypeScript + `@modelcontextprotocol/sdk`
-- LLM reasoning delegated to the host via `sampling/createMessage` first; falls back to a direct Anthropic API call (`@anthropic-ai/sdk`) when `ANTHROPIC_API_KEY` is set and the host lacks sampling
+- LLM reasoning for `propose_hardware` delegates to the host via `sampling/createMessage` first, then falls back to a direct Anthropic API call (`@anthropic-ai/sdk`) only when optional `ANTHROPIC_API_KEY` is set
 - `simulate_assembly` calls out to a separate Python MuJoCo **sim-worker** over HTTP (`SIM_WORKER_URL`); the worker isn't bundled in the npm package
 - Catalog stored as `catalog.json` in the repo (JSON, version-controllable, 80 devices and growing)
 - Tag vocabulary in `tags.md`, validated at boot — server refuses to start on tag drift
@@ -117,28 +136,9 @@ npm test           # safety + schema + lookup tests
 npm run build      # tsc -> dist/
 ```
 
-## Troubleshooting: verify sampling support
-
-`propose_hardware` reasons via `sampling/createMessage`. Some MCP hosts don't support it (and without an `ANTHROPIC_API_KEY` fallback you'll get degraded, raw-catalog responses). If proposals come back without reasoning, verify your host supports sampling with this quick smoke check.
-
-```bash
-npm install
-```
-
-Add this to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
-
-```json
-{
-  "mcpServers": {
-    "hackshop-smoke": {
-      "command": "tsx",
-      "args": ["/Users/YOU/hackshop-mcp/scripts/smoke.ts"]
-    }
-  }
-}
-```
+## Troubleshooting: quick deterministic check
 
-Restart Claude Desktop. Ask Claude to call the `smoke_check` tool. If it returns "Smoke OK," sampling works in your host. If it fails, set an `ANTHROPIC_API_KEY` (see install above) or expect degraded responses from `propose_hardware`.
+Ask your agent to call `plan_gadget` with `a desk gadget I can talk to`. This should return Muse board picks instantly and without any API key. If `propose_hardware` returns catalog matches without reasoning, your host probably does not support sampling and no optional `ANTHROPIC_API_KEY` is set.
 
 ## Install (local build → host)
 
@@ -163,7 +163,7 @@ The founder had an Electric Objects EO1 picture frame. The company shut down; th
 
 ## Safety Rule (P0)
 
-Bricking unrecoverable hardware is the single failure mode that ends this product. The catalog tracks brick-risk provenance: `founder-verified | community-reported | llm-inferred`. For categories where bricks are unrecoverable (`handheld`, `sbc`), the server **refuses to surface LLM-inferred brick-risk scores**. It returns "brick-risk unknown — research before flashing" instead. This is a tested release gate. See `src/safety.ts` and `test/safety.test.ts`.
+Bricking unrecoverable hardware is the single failure mode that ends this product. The catalog tracks brick-risk provenance: `founder-verified | community-reported | vendor-docs | llm-inferred`. For categories where bricks are unrecoverable (`handheld`, `sbc`), the server **refuses to surface LLM-inferred brick-risk scores**. It returns "brick-risk unknown - research before flashing" instead. This is a tested release gate. See `src/safety.ts` and `test/safety.test.ts`.
 
 ## Telemetry
 

package/catalog.json

@@ -37,7 +37,7 @@
     ],
     "hack_difficulty": 1,
     "brick_risk": 1,
-    "brick_provenance": "founder-verified",
+    "brick_provenance": "vendor-docs",
     "last_verified": "2026-05-04",
     "firmware_links": [
       "https://www.raspberrypi.com/documentation/"
@@ -48,7 +48,8 @@
     "est_used_price_usd_max": 65,
     "image_url": "https://en.wikipedia.org/wiki/Special:FilePath/Raspberry_Pi_4_Model_B_-_Side.jpg?width=640",
     "est_setup_hours_min": 1,
-    "est_setup_hours_max": 2
+    "est_setup_hours_max": 2,
+    "buy_url": "https://www.raspberrypi.com/products/raspberry-pi-4-model-b/"
   },
   {
     "id": "raspberry-pi-zero-2w",
@@ -64,7 +65,7 @@
     ],
     "hack_difficulty": 1,
     "brick_risk": 1,
-    "brick_provenance": "founder-verified",
+    "brick_provenance": "vendor-docs",
     "last_verified": "2026-05-04",
     "firmware_links": [
       "https://www.raspberrypi.com/products/raspberry-pi-zero-2-w/"
@@ -74,7 +75,8 @@
     "est_used_price_usd_min": 15,
     "est_used_price_usd_max": 25,
     "est_setup_hours_min": 1,
-    "est_setup_hours_max": 2
+    "est_setup_hours_max": 2,
+    "buy_url": "https://www.raspberrypi.com/products/raspberry-pi-zero-2-w/"
   },
   {
     "id": "tidbyt-gen1",
@@ -279,7 +281,7 @@
       "https://github.com/OLIMEX/ESP32-POE"
     ],
     "community_size_bucket": "small",
-    "notes": "ESP32 with PoE Ethernet. Single cable for power and network \u2014 good for wall-mounted displays/sensors with no wall-warts.",
+    "notes": "ESP32 with PoE Ethernet. Single cable for power and network — good for wall-mounted displays/sensors with no wall-warts.",
     "est_used_price_usd_min": 20,
     "est_used_price_usd_max": 35,
     "est_setup_hours_min": 2,
@@ -450,7 +452,7 @@
       "https://github.com/LumaTeam/Luma3DS"
     ],
     "community_size_bucket": "thriving",
-    "notes": "Massive modding scene. CFW (Luma3DS) enables homebrew, emulators, region-free play. Brick risk REAL on bad installs \u2014 the 3ds.hacks.guide walkthrough is the canonical source.",
+    "notes": "Massive modding scene. CFW (Luma3DS) enables homebrew, emulators, region-free play. Brick risk REAL on bad installs — the 3ds.hacks.guide walkthrough is the canonical source.",
     "est_used_price_usd_min": 50,
     "est_used_price_usd_max": 150,
     "image_url": "https://en.wikipedia.org/wiki/Special:FilePath/Nintendo-3DS-AquaOpen.png?width=640",
@@ -583,7 +585,7 @@
       "https://github.com/pimoroni/inky"
     ],
     "community_size_bucket": "active",
-    "notes": "800x480 SEVEN-COLOR e-paper HAT. 7-color e-ink is rare \u2014 great for ambient art rotation, family photos, weather displays. Slow refresh (~30s) so static-frame use only. Pi Zero W compatible.",
+    "notes": "800x480 SEVEN-COLOR e-paper HAT. 7-color e-ink is rare — great for ambient art rotation, family photos, weather displays. Slow refresh (~30s) so static-frame use only. Pi Zero W compatible.",
     "est_used_price_usd_min": 90,
     "est_used_price_usd_max": 130,
     "est_setup_hours_min": 3,
@@ -688,7 +690,7 @@
       "https://www.mobileread.com/forums/forumdisplay.php?f=275"
     ],
     "community_size_bucket": "small",
-    "notes": "6\" e-ink with stock Android 10 + Google Play. Sideload any Android app \u2014 Google Calendar, custom dashboards, kiosk launchers. Less hacking required than a Kindle/Kobo because it's already open.",
+    "notes": "6\" e-ink with stock Android 10 + Google Play. Sideload any Android app — Google Calendar, custom dashboards, kiosk launchers. Less hacking required than a Kindle/Kobo because it's already open.",
     "est_used_price_usd_min": 90,
     "est_used_price_usd_max": 160,
     "est_setup_hours_min": 1,
@@ -1656,7 +1658,7 @@
     ],
     "hack_difficulty": 2,
     "brick_risk": 1,
-    "brick_provenance": "llm-inferred",
+    "brick_provenance": "vendor-docs",
     "last_verified": "2026-10-02",
     "firmware_links": [
       "https://github.com/facebookincubator/muse-gadget-sdk/tree/main/esp32",
@@ -1692,7 +1694,8 @@
       "mounting": "No mounting holes on the dimension drawing.",
       "printables": [],
       "source_url": "https://dl.espressif.com/dl/schematics/Dimension_esp32-c5-devkitc-1_v1.2_20250509.pdf"
-    }
+    },
+    "buy_url": "https://www.digikey.com/en/products/detail/espressif-systems/ESP32-C5-DEVKITC-1-N8R8/28718162"
   },
   {
     "id": "ideaspark-esp32-1-9-lcd",
@@ -1706,7 +1709,7 @@
     ],
     "hack_difficulty": 2,
     "brick_risk": 1,
-    "brick_provenance": "llm-inferred",
+    "brick_provenance": "vendor-docs",
     "last_verified": "2026-10-02",
     "firmware_links": [
       "https://github.com/facebookincubator/muse-gadget-sdk/tree/main/esp32",
@@ -1739,7 +1742,8 @@
       "mounting": null,
       "printables": [],
       "source_url": "https://manuals.plus/ae/1005007181435830"
-    }
+    },
+    "buy_url": "https://www.amazon.com/dp/B0D6QXC813"
   },
   {
     "id": "seeed-sensecap-indicator",
@@ -1755,7 +1759,7 @@
     ],
     "hack_difficulty": 2,
     "brick_risk": 1,
-    "brick_provenance": "llm-inferred",
+    "brick_provenance": "vendor-docs",
     "last_verified": "2026-10-02",
     "firmware_links": [
       "https://github.com/facebookincubator/muse-gadget-sdk/tree/main/esp32",
@@ -1793,7 +1797,8 @@
       "mounting": "Fold-out kickstand and keyhole wall slot (no dimensions published).",
       "printables": [],
       "source_url": "https://www.thethingsnetwork.org/device-repository/devices/seeed/sensecap-indicator/"
-    }
+    },
+    "buy_url": "https://www.seeedstudio.com/SenseCAP-Indicator-D1-p-5643.html"
   },
   {
     "id": "seeed-reterminal-e1001",
@@ -1809,7 +1814,7 @@
     ],
     "hack_difficulty": 2,
     "brick_risk": 1,
-    "brick_provenance": "llm-inferred",
+    "brick_provenance": "vendor-docs",
     "last_verified": "2026-10-02",
     "firmware_links": [
       "https://github.com/facebookincubator/muse-gadget-sdk/tree/main/esp32",
@@ -1846,7 +1851,8 @@
       "mounting": "Wall hole on the back; embedded nuts for the included stand.",
       "printables": [],
       "source_url": "https://wiki.seeedstudio.com/getting_started_with_reterminal_e1001/"
-    }
+    },
+    "buy_url": "https://www.seeedstudio.com/reTerminal-E1001-p-6534.html"
   },
   {
     "id": "home-assistant-voice-pe",
@@ -1861,7 +1867,7 @@
     ],
     "hack_difficulty": 2,
     "brick_risk": 1,
-    "brick_provenance": "llm-inferred",
+    "brick_provenance": "vendor-docs",
     "last_verified": "2026-10-02",
     "firmware_links": [
       "https://github.com/facebookincubator/muse-gadget-sdk/tree/main/esp32",
@@ -1898,7 +1904,8 @@
       "mounting": null,
       "printables": [],
       "source_url": "https://www.home-assistant.io/voice-pe/"
-    }
+    },
+    "buy_url": "https://www.home-assistant.io/voice-pe/"
   },
   {
     "id": "waveshare-esp32-s3-touch-amoled-1-75c",
@@ -1914,7 +1921,7 @@
     ],
     "hack_difficulty": 2,
     "brick_risk": 1,
-    "brick_provenance": "llm-inferred",
+    "brick_provenance": "vendor-docs",
     "last_verified": "2026-10-02",
     "firmware_links": [
       "https://github.com/facebookincubator/muse-gadget-sdk/tree/main/esp32",
@@ -1932,8 +1939,8 @@
       "orientation": "upright",
       "shape": "round",
       "size_mm": {
-        "w": 55.0,
-        "h": 55.0,
+        "w": 55,
+        "h": 55,
         "t": 15.05
       },
       "size_confidence": "drawing",
@@ -1953,7 +1960,8 @@
         "desk-stand"
       ],
       "source_url": "https://www.waveshare.com/img/devkit/ESP32-S3-Touch-AMOLED-1.75C/ESP32-S3-Touch-AMOLED-1.75C-details-size.jpg"
-    }
+    },
+    "buy_url": "https://www.waveshare.com/esp32-s3-touch-amoled-1.75c.htm"
   },
   {
     "id": "aipi-lite",
@@ -1968,7 +1976,7 @@
     ],
     "hack_difficulty": 2,
     "brick_risk": 1,
-    "brick_provenance": "llm-inferred",
+    "brick_provenance": "vendor-docs",
     "last_verified": "2026-10-02",
     "firmware_links": [
       "https://github.com/facebookincubator/muse-gadget-sdk/tree/main/esp32",
@@ -2003,7 +2011,8 @@
       "mounting": "Magnets in the case.",
       "printables": [],
       "source_url": "https://static.aipi.com/AIPI_InstructionBook/AIPI_InstructionBook.html"
-    }
+    },
+    "buy_url": "https://aipi.com/products/aipi-lite"
   },
   {
     "id": "waveshare-esp32-c6-touch-amoled-1-8",
@@ -2018,7 +2027,7 @@
     ],
     "hack_difficulty": 2,
     "brick_risk": 1,
-    "brick_provenance": "llm-inferred",
+    "brick_provenance": "vendor-docs",
     "last_verified": "2026-10-02",
     "firmware_links": [
       "https://github.com/facebookincubator/muse-gadget-sdk/tree/main/esp32",
@@ -2038,7 +2047,7 @@
       "size_mm": {
         "w": 37.6,
         "h": 45.2,
-        "t": 15.0
+        "t": 15
       },
       "size_confidence": "drawing",
       "size_note": "Portrait. Display window 28.70 x 34.94 mm.",
@@ -2057,7 +2066,8 @@
         "desk-stand"
       ],
       "source_url": "https://docs.waveshare.com/assets/images/ESP32-C6-Touch-AMOLED-1.8-size-567e74ffd49f34e5d3d0e9ef419fcb30.webp"
-    }
+    },
+    "buy_url": "https://www.waveshare.com/esp32-c6-touch-amoled-1.8.htm"
   },
   {
     "id": "seeed-sensecap-watcher",
@@ -2072,7 +2082,7 @@
     ],
     "hack_difficulty": 2,
     "brick_risk": 1,
-    "brick_provenance": "llm-inferred",
+    "brick_provenance": "vendor-docs",
     "last_verified": "2026-10-02",
     "firmware_links": [
       "https://github.com/facebookincubator/muse-gadget-sdk/tree/main/esp32",
@@ -2110,7 +2120,8 @@
       "mounting": "Ships with a bracket, base plate and 1/4\" adapter set.",
       "printables": [],
       "source_url": "https://www.seeed.cc/product/sensecap-watcher-the-physical-ai-agent-for-smarter-spaces"
-    }
+    },
+    "buy_url": "https://www.seeedstudio.com/SenseCAP-Watcher-W1-A-p-5979.html"
   },
   {
     "id": "m5stack-sticks3",
@@ -2126,7 +2137,7 @@
     ],
     "hack_difficulty": 2,
     "brick_risk": 1,
-    "brick_provenance": "llm-inferred",
+    "brick_provenance": "vendor-docs",
     "last_verified": "2026-10-02",
     "firmware_links": [
       "https://github.com/facebookincubator/muse-gadget-sdk/tree/main/esp32",
@@ -2144,15 +2155,15 @@
       "orientation": "upright",
       "shape": "box",
       "size_mm": {
-        "w": 24.0,
-        "h": 48.0,
-        "t": 15.0
+        "w": 24,
+        "h": 48,
+        "t": 15
       },
       "size_confidence": "drawing",
       "size_note": "Corner radius R3. Hole positions were measured off the drawing; confirm against a unit.",
       "corner_radius_mm": 3,
       "comes_in_case": true,
-      "mass_g": 20.0,
+      "mass_g": 20,
       "usb": {
         "type": "usb-c",
         "count": 1,
@@ -2166,7 +2177,8 @@
         "desk-stand"
       ],
       "source_url": "https://docs.m5stack.com/en/core/StickS3"
-    }
+    },
+    "buy_url": "https://shop.m5stack.com/products/m5sticks3-esp32s3-mini-iot-dev-kit"
   },
   {
     "id": "m5stack-stickc-plus2",
@@ -2181,7 +2193,7 @@
     ],
     "hack_difficulty": 2,
     "brick_risk": 1,
-    "brick_provenance": "llm-inferred",
+    "brick_provenance": "vendor-docs",
     "last_verified": "2026-10-02",
     "firmware_links": [
       "https://github.com/facebookincubator/muse-gadget-sdk/tree/main/esp32",
@@ -2199,8 +2211,8 @@
       "orientation": "upright",
       "shape": "box",
       "size_mm": {
-        "w": 24.0,
-        "h": 48.0,
+        "w": 24,
+        "h": 48,
         "t": 13.5
       },
       "size_confidence": "published",
@@ -2221,7 +2233,8 @@
         "desk-stand"
       ],
       "source_url": "https://docs.m5stack.com/en/core/M5StickC%20PLUS2"
-    }
+    },
+    "buy_url": "https://shop.m5stack.com/products/m5stickc-plus2-esp32-mini-iot-development-kit"
   },
   {
     "id": "raspberry-pi-5",
@@ -2235,7 +2248,7 @@
     ],
     "hack_difficulty": 1,
     "brick_risk": 1,
-    "brick_provenance": "llm-inferred",
+    "brick_provenance": "vendor-docs",
     "last_verified": "2026-10-02",
     "firmware_links": [
       "https://github.com/facebookincubator/muse-gadget-sdk/tree/main/linux",
@@ -2246,6 +2259,7 @@
     "est_used_price_usd_min": 50,
     "est_used_price_usd_max": 120,
     "est_setup_hours_min": 0.5,
-    "est_setup_hours_max": 2
+    "est_setup_hours_max": 2,
+    "buy_url": "https://www.raspberrypi.com/products/raspberry-pi-5/"
   }
 ]

package/dist/build-plan/index.d.ts

@@ -0,0 +1,10 @@
+import type { BuildPlan, DeviceEntry, Platform, PlatformBoard, Printable } from "./types.js";
+export declare function buildPlan(input: {
+    device: DeviceEntry;
+    platform: Platform | null;
+    board: PlatformBoard | null;
+    printables: Printable[];
+    siteUrl: string;
+}): BuildPlan;
+export declare function buildUrls(deviceId: string, siteUrl: string, includeMusePage: boolean): BuildPlan["urls"];
+export declare function platformCaveatsFor(platform: Platform, board: PlatformBoard): string[];