# hackshop (hackshop-mcp)

hackshop helps an agent plan and build a physical body for itself. Muse gadgets are the first supported agent platform.

## Use First

- Hosted MCP: `https://www.hackshop.dev/mcp` (stateless, POST only)
- Planner API: `POST https://www.hackshop.dev/api/plan` (OpenAPI: `https://www.hackshop.dev/openapi.json`)
- Build JSON: `https://www.hackshop.dev/build/<device_id>/plan.json`
- Build brief: `https://www.hackshop.dev/build/<device_id>/build.md`
- Muse boards: `https://www.hackshop.dev/muse`
- Store JSON (every board and part, seller links, difficulty, prices checked date): `https://www.hackshop.dev/store.json`
- Reverse-engineering library: `https://www.hackshop.dev/reverse-engineering`
- Cheap display design starters: `https://www.hackshop.dev/displays`
- Agent guide: `https://www.hackshop.dev/agents.md`
- Source: `https://github.com/hackshopdev/hackshop-mcp`

## MCP Install

Hosted connector:

```json
{
  "url": "https://www.hackshop.dev/mcp",
  "transport": "streamable-http"
}
```

The hosted MCP is stateless: send JSON-RPC with POST. It never sends an `mcp-session-id`; GET and DELETE return 405. Browser clients are allowed (CORS `*`).

Local npm server:

```json
{
  "mcpServers": {
    "hackshop": {
      "command": "npx",
      "args": ["-y", "hackshop-mcp"]
    }
  }
}
```

`ANTHROPIC_API_KEY` is optional. It only improves `propose_hardware` in the local npm server when the MCP host cannot sample.

## Tools

- `intake_gadget`: the 4 intake questions (where it lives, how you interact, room sensing, budget), why they matter and how answers map to `plan_gadget`.
- `plan_gadget`: deterministic Muse board planner. Pass the human's `answers`; it returns fit, warnings, notes, intake status, remaining questions, and picks with difficulty and build links.
- `get_build_plan`: deterministic difficulty, flash warnings, parts, shopping list, assembly with verify checks, flashing, pairing and agent brief.
- `assess_hackability`: catalog lookup with brick risk, firmware links and build-page URL.
- `find_reverse_engineering_examples`: search current source-linked hardware projects and research methods. Results label independent reproductions, documented builds, author demos and analysis-only evidence separately. Optional use_case and max_device_price_usd filters return source-backed design starters with dated device-only prices and stock. Unknown prices are excluded by price filters; hosts, accessories, shipping and tax are extra.
- `find_firmware_playbooks`: discover curated firmware, local-protocol and cloud-replacement paths, preferring the least invasive.
- `check_firmware_compatibility`: exact fail-closed target matching; missing identifiers return unknown and mismatches return unsupported.
- `get_firmware_playbook`: prerequisites, backup, recovery, risks, sources, steps and validation.
- `verify_firmware_artifact`: compare supplied filename/source/SHA-256 metadata only; no binary upload or fetch.
- `prepare_firmware_job`: non-executing manifest and stop points after owner authorization and a confirmed match.
- Local npm only: `propose_hardware`, `simulate_assembly`. The hosted MCP answers these with a `try_instead` hint.

Resources: `hackshop://muse/boards`, `hackshop://muse/sdk-terms`, `hackshop://catalog/tags`, `hackshop://firmware/playbooks`, `hackshop://reverse-engineering/examples`, and the templates `hackshop://build/{device_id}`, `hackshop://firmware/{playbook_id}` and `hackshop://reverse-engineering/{example_id}`.

## Difficulty

Every board has a ski-style level: green = Beginner (no tools), blue = Intermediate (extra steps such as a flash backup or a special port), black = Expert (needs a pro, or better to buy). Ideas that need the body to move or use arms get a warning: Muse boards can't move.

## Agent Rule

Ask the intake questions (skip any already answered), call `plan_gadget` with `answers`, let the human choose, then tell the human to click Start a build so progress is saved. Fetch `get_build_plan` or `/build/<id>/plan.json` and read its `warnings` before flashing (the SenseCAP Watcher needs an nvsfactory backup and the port ending in 3). Show the shopping list, follow the purchase policy, follow `assembly` and its `verify` checks, then flash and pair. Muse replies are text; add a text-to-speech service for spoken replies.

For firmware work: discover, collect exact identifiers, run `check_firmware_compatibility`, inspect the full playbook, verify backup and recovery, then prepare a non-executing manifest. Destructive actions remain human-run. Never upload or redistribute proprietary firmware, device keys, certificates, serials, calibration data or identity partitions.

For reverse-engineering research: search the library, prefer exact-model documented or independently reproduced work, and read every warning and source. Author demos are inspiration, not compatibility proof. Analysis-method entries describe saved evidence or tools and do not prove physical acquisition, runtime behavior or safe flashing.

## Purchase Policy

hackshop never buys anything. Your agent can help you buy the parts: it shows you the exact items, sellers and total, then asks "Place this order for $<total> at <seller>?" and waits for a clear yes before it checks out. If it can't check out on a site, or the site doesn't allow automated checkout (Amazon and eBay don't), it gives you the link to buy yourself.