hackshop-mcp 0.0.2 → 0.0.4

package/README.md

@@ -8,11 +8,13 @@ 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, fifty 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.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).
 
 ## Install in 30 seconds
 
@@ -53,11 +55,54 @@ 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?)`
+
+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
+- `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`
+
+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.
+
+### `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, ~50 devices in V1)
+- 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
+- `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,9 +117,9 @@ npm test           # safety + schema + lookup tests
 npm run build      # tsc -> dist/
 ```
 
-## Day-0 Smoke Test (REQUIRED before scaffolding more)
+## Troubleshooting: verify sampling support
 
-This server depends on `sampling/createMessage`. Some MCP hosts don't support it. Verify yours does first.
+`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
@@ -93,11 +138,11 @@ Add this to your Claude Desktop config (`~/Library/Application Support/Claude/cl
 }
 ```
 
-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.
+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`.
 
-## Install (target host)
+## Install (local build → 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
 {
@@ -120,6 +165,15 @@ The founder had an Electric Objects EO1 picture frame. The company shut down; th
 
 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`.
 
+## 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
 
 See `CONTRIBUTING.md`. New devices come in via PR; tag changes require a `tags.md` edit; `community-reported` is the default provenance for community contributions.

package/SAMPLING.md

@@ -74,11 +74,17 @@ JSON only, no markdown. Code-fence allowed (the parser strips it).
 
 The retry is in `sampleJson` itself (`src/sampling.ts`).
 
-### What the server NEVER does
+### What the server does (v0.0.2 contract)
 
-- Bundle an Anthropic / OpenAI / other-provider SDK.
-- Read a user-side `ANTHROPIC_API_KEY` env var.
-- Make HTTP calls to provider endpoints directly.
-- Crash on sampling failure.
+- **Always tries host sampling first** via `sampling/createMessage`. No key needed; host pays.
+- **Reads `ANTHROPIC_API_KEY` only as a fallback** when host sampling fails twice. Optional: if the env var is unset, the server returns a degraded response instead of calling Anthropic directly.
+- **Bundles `@anthropic-ai/sdk`** as a runtime dependency for the fallback path. (V0.0.1 promised "no SDK" — V0.0.2 chose pragmatism after live testing showed Claude Desktop's sampling support is spotty.)
+- **Never crashes on sampling failure** — degraded response is the floor.
+- **Never makes provider calls when `ANTHROPIC_API_KEY` is unset** — keyless installs stay keyless.
 
-If a future feature seems to need a direct provider call, treat that as a redesign signal — not a quick patch.
+### What the server still NEVER does
+
+- Bundle an OpenAI / other non-Anthropic SDK.
+- Hard-require `ANTHROPIC_API_KEY` (it's optional, host sampling is the preferred path).
+- Persist user prompts or proposals.
+- Make outbound calls beyond the Anthropic API + the user's MCP host.