hackshop-mcp 0.0.3 → 0.0.5

package/README.md

@@ -8,31 +8,39 @@ You describe a project. The agent surfaces 3-5 hackable hardware options you wou
 
 A tinkerer has an idea. The idea would be cooler with the right piece of hardware attached: an old screen, an abandoned smart speaker, a bricked frame, a hackable handheld. The tinkerer doesn't know what hardware exists, what's hackable, or what would creatively *fit* the idea. So the idea stays purely software, or gets paired with a Raspberry Pi.
 
-This is a hardware-knowledge layer on top of LLMs. Two tools, 27 hand-vetted devices, one closed-set tag vocabulary, and a brick-risk safety rule that won't let the agent fabricate a score for hardware classes where bricks are unrecoverable.
+This is a hardware-knowledge layer on top of LLMs. Four tools, 80 researched devices, one closed-set tag vocabulary, and a brick-risk safety rule that won't let the agent fabricate a score for hardware classes where bricks are unrecoverable. `simulate_assembly` drops a proposed robot into a MuJoCo physics world and tells you, honestly, whether it would actually move.
+
+Hackshop now knows about Meta's Muse Gadgets SDK: ESP32 boards and Linux machines that can become a physical body for Muse, Meta's personal AI agent. Muse recommendations include the SDK tier, setup path, supported features, printable stand/enclosure links when available, and the required terms caveat: personal, non-commercial use only, at most 50 devices per token, no selling or public marketplace listing, and revocable access.
 
 ## Status
 
-V0.0.2 — published on npm. Install with `npx hackshop-mcp` or add to your MCP client config.
+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
 
@@ -53,11 +61,67 @@ 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?, 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`, `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`, 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:
+
+- `success` — did the rollout pass the typed position, collision, and upright acceptance criteria
+- `summary` / `post_mortem` — natural-language verdict plus honest failure theatre (stuck / tipped / collisions / heading-oscillation)
+- `artifacts` — hosted URLs for the rendered `video`, `scene` (MJCF), `control` (control.py), and `telemetry.json`
+- `metric_value`, `telemetry`, `authored_by`, `world_desc`
+
+Today it simulates the diff-drive **`navigate`** slice; other goal kinds return an honest `unsupported` rather than faking a pass. Set `SIM_WORKER_URL` to point at a running sim-worker (defaults to `http://127.0.0.1:8000`). The bounded rollout here is intentionally small so it fits in a single tool call; the **rich, longer, agent-driven runs happen via the web app** at [hackshop.dev](https://hackshop.dev), backed by the worker at [hackshop-sim.fly.dev](https://hackshop-sim.fly.dev).
+
+## Simulation (v2)
+
+The site turns a proposal into a watchable robot: **proposal → select one complete build → deterministic feasibility check → MuJoCo rollout → interactive 3D replay**, with a shareable summary page you can link to. Honest by design — a robot that gets stuck on a ramp gets a post-mortem, not a green checkmark.
+
+The current navigation slice deliberately has a narrow fidelity contract:
+
+- alternative chassis are separate candidates, never merged into one BOM;
+- Create 3 uses an explicit Pi + RPLIDAR build, while TurtleBot 4 Lite preserves its factory-integrated Pi/camera/lidar stack;
+- versioned manifests provide real outer dimensions and mass to product-specific primitive proxies (not pretend CAD);
+- the controller only runs when the assembly declares the 2D-lidar observations it consumes;
+- typed position/collision/upright criteria drive the verdict; and
+- the browser replay supports orbit, zoom, playback/scrubbing, world geometry, path/goal overlays, and collision/failure markers.
+
+- **Live:** [https://hackshop.dev](https://hackshop.dev)
+- **Worker:** [https://hackshop-sim.fly.dev](https://hackshop-sim.fly.dev)
+- **Design doc:** [`docs/v2-simulation-plan.md`](docs/v2-simulation-plan.md)
+
+The `simulate_assembly` MCP tool above is the bounded, single-call entry point into this same physics worker.
+
 ## Architecture
 
 - TypeScript + `@modelcontextprotocol/sdk`
-- LLM reasoning delegated to the host via `sampling/createMessage` (no Anthropic SDK bundled, no BYO key)
-- Catalog stored as `catalog.json` in the repo (JSON, version-controllable, 27 devices in V0.0.2 — growing)
+- 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
 - eBay integration is **not** in this server. Compose with [`ebay-mcp`](https://github.com/YosefHayim/ebay-mcp) at the host level.
 
@@ -72,32 +136,13 @@ npm test           # safety + schema + lookup tests
 npm run build      # tsc -> dist/
 ```
 
-## Day-0 Smoke Test (REQUIRED before scaffolding more)
+## Troubleshooting: quick deterministic check
 
-This server depends on `sampling/createMessage`. Some MCP hosts don't support it. Verify yours does first.
+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.
 
-```bash
-npm install
-```
+## Install (local build → host)
 
-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"]
-    }
-  }
-}
-```
-
-Restart Claude Desktop. Ask Claude to call the `smoke_check` tool. If it returns "Smoke OK," your architecture works. If it fails, stop here — `hackshop-mcp` won't work in this host.
-
-## Install (target host)
-
-After dev is done and smoke passes, add to your MCP client config:
+To run a locally built copy instead of `npx`, add to your MCP client config:
 
 ```json
 {
@@ -118,7 +163,16 @@ 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
+
+Starting with v0.0.4 the MCP server sends an anonymous ping when it starts and after each tool call. It exists so the maintainer can tell whether anyone is actually using the server.
+
+- **Sent:** the event name, tool name, success/degraded flag, duration, `hackshop-mcp` version, MCP client name/version (e.g. `claude-code`), OS platform, Node major version, and a random install id stored in `~/.config/hackshop-mcp/telemetry.json`.
+- **Never sent:** tool arguments, your idea text, device names, results, API keys, or file paths.
+- **Destination:** `https://www.hackshop.dev/api/telemetry/mcp`, which forwards to the project's PostHog.
+- **Opt out:** set `HACKSHOP_TELEMETRY=0` (or `DO_NOT_TRACK=1`) in the server's `env`. Telemetry is also off automatically in CI and under test runners. The implementation is `src/telemetry.ts`.
 
 ## Contributing