hackshop-mcp — Muse Gadget project

Tools

propose_hardware(idea, budget_usd?, constraints?)

Returns 3-5 hardware proposals, each with:

• name and category
• why_this_fits — one sentence referencing your idea explicitly
• hack_difficulty (1-5)
• brick_risk — numeric score, OR null + "unknown" label for hard-to-recover categories with LLM-inferred risk
• brick_risk_disclaimer — present when llm-inferred but score retained
• firmware_links — github repos, hackaday articles
• community_size — tiny | small | active | thriving
• ebay_query_suggestion — pass to ebay-mcp's search tool for live listings

assess_hackability(device_name)

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, backed by the worker at 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

• Worker: https://hackshop-sim.fly.dev

• Design doc: 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 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 at the host level.

Install (local dev)

git clone <this-repo>
cd hackshop-mcp
npm install
npm run validate   # verifies catalog + tags
npm test           # safety + schema + lookup tests
npm run build      # tsc -> dist/

Troubleshooting: quick deterministic check

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)

To run a locally built copy instead of npx, add to your MCP client config:

{
  "mcpServers": {
    "hackshop": {
      "command": "node",
      "args": ["/Users/YOU/hackshop-mcp/dist/server.js"]
    }
  }
}

For idea-to-hardware-to-listings flow, also install ebay-mcp from YosefHayim/ebay-mcp.

The Story

The founder had an Electric Objects EO1 picture frame. The company shut down; the device bricked. He revived it with Claude, ~6 hours of firmware reverse-engineering. Wondered: "what if an agent already knew this stuff?" That's hackshop-mcp.

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 | 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

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.

License

MIT.