# megabot — vibeHardware

> vibeHardware is here — type in what sort of robot you want, requirements, what it looks like, whatever, and we’ll show you the parts, and let you 3D print the prototype or get it printed and delivered to you. Live AUD BOMs from open platforms like XLeRobot, NORI A3, Microduck, and Open Duck Mini — no invented shop prices.

vibeHardware is here on megabot: type in what sort of robot you want and agents can generate a robot config from natural language, fetch a verified AUD bill of materials, and return shareable Workshop URLs so makers can 3D print the prototype or get it printed and delivered. No invented shop prices.

## Base URL
https://megabot.tech

## Remote MCP (Cursor / Grok Bot)

Canonical Streamable HTTP endpoint (also speaks MCP 2026-07-28):

- https://megabot.tech/api/mcp
- Alias rewrite: https://megabot.tech/mcp

CORS: `*`. No Capcom assets. AUD on parts; USD only for /pricing subscriptions.

### Catalog tools (no auth)
- `search_robots` — query, platform, maxAud, capability tags. Presets + OSS (XLeRobot, Nori, Microduck, Open Duck Mini, field guide). Battle Mon only if present in the catalogue.
- `get_robot` — by config `c=` or preset/OSS id. Voltage + preset metadata + AUD summary.
- `get_bom` — AUD BOM lines from existing APIs only. Never invents shop prices/SKUs.
- `create_robot` — wraps POST /api/prompt. Returns workshopUrl, BOM, print checklist, known STL links. `auth_required` when Supabase keys are set and the caller is unsigned.
- `validate_design` — requirements string + config/preset. Voltage, DOF hints, capability flags, printable notes. Pass/fail + gaps. Fail-closed.
- `list_stl_sources` — known print/STL/repo URLs from catalogue data only (e.g. Open Duck Mini GitHub /print).
- `get_parts_map` — Linked parts datatable + JSON-LD (family filter). All servos (C001, C046, 12V STS, Nori mix) and Explore-kit BOM lines. Two stacks: Feetech STS3215 bus vs CARA3/OpenArm BLDC+PG+FOC/Damiao — do not mix. Nested QUOTE/EST cost trees. Bare product URLs or URL TBD. Never invents Alibaba SKUs, shop prices, or affiliate params. Never lists STS3215 as a CARA3 shoulder. Example `@id`: https://megabot.tech/parts-map#c001.

### Library tools (Bearer required)
Same behavior as `/api/library/*`. Catalog tools stay public. Library tools call `requireLibraryUser` (cookie session, agent JWT, or Supabase access token). Never a service-role key.

Send the header on the **MCP HTTP transport** (every Streamable HTTP request), not as a tool argument:

```
Authorization: Bearer <agent JWT or session access token>
```

Cursor / Grok Bot: set `headers.Authorization` on the streamable-http MCP server (copy the token from a megabot Library prompt). Example `mcp.json`:

```json
{
  "mcpServers": {
    "megabot": {
      "type": "streamable-http",
      "url": "https://megabot.tech/api/mcp",
      "headers": { "Authorization": "Bearer <TOKEN>" }
    }
  }
}
```

Unauthenticated library tool calls return a 401-style MCP error: `{ "error": "auth_required", "auth_required": true, "status": 401, "message": "…", "hint": "…" }`. Ask the maker to copy a new megabot prompt from Library, or sign in. On expired JWT, copy again.

- `list_library_listings` — `q?` — GET /api/library/listings
- `get_library_listing` — `listing_id`, optional `version` (N or latest) — GET /api/library/listings/<id>
- `list_library_versions` — `listing_id` — GET …/versions
- `get_library_version` — `listing_id`, `version` — GET …/versions/<n>
- `create_library_listing` — paste text + optional files (POST /api/library/paste). Version 1.
- `update_library_listing` — PATCH fields; content bumps a version (`version_note?`)
- `create_library_version` — explicit snapshot POST …/versions
- `attach_library_item` — image / sim / spreadsheet / cad / notes on the current version
- `get_library_download` — signed URL for an item (`preview?`)
- `unlink_library_attachment` — unlink from the current version (older versions keep the file)
- `delete_library_listing` — requires `confirm: true` (DELETE /api/library/listings/<id>)

Inline MCP files are base64 and capped at 8 MiB. Larger uploads: REST multipart. Uploads are not upserts. Never invent shop prices.

Cursor plugin: `cursor-plugin/megabot/` (marketplace name `megabot`). Local install: copy to `~/.cursor/plugins/local/megabot`. Submit: https://cursor.com/marketplace/publish

## Share URL format
- Workshop: `/?c=<slotIds.joinedByDot>`
- Workshop with BOM open: `/?c=<slotIds.joinedByDot>&bom=1`
- Optional compare: `/?c=<a>&d=<b>&compare=1`
- Optional OSS silhouette: `/?c=<config>&oss=<ossRobotId>`

Slot order (always 7 ids): base.lift.leftArm.rightArm.head.power.sensors

## APIs (CORS: *)

### GET /api/catalog
JSON catalogue of presets, swappable parts, and OSS robots (ids, voltages, shop URLs when published). Includes `partsMap` / `partsMapApi` pointers.

### GET /api/parts-map
Linked parts datatable + interchange seed. Optional `?family=openduck|xle|microduck|nori|battle-mon|so-101|orbeet|cara3-openarm`. Includes `parts[]` and JSON-LD `@context` / `@graph`. `?format=jsonld` or `Accept: application/ld+json` returns JSON-LD only. Bare URLs or URL TBD. No invented SKUs.

### GET /api/parts-map.jsonld
Companion JSON-LD (`ItemList` + `Product` / `mb:Part`). Same family filter. Stable part `@id`s such as `https://megabot.tech/parts-map#c001`. Custom predicates: `mb:replaces`, `mb:matesWith`, `mb:incompatibleWith`.

### POST /api/prompt
Body: `{ "prompt": string, "config"?: RobotConfig }`
Returns: spokenReply, action, config?, conceptName?, conceptNote?, source, workshopUrl, bomUrl, bomSummary, total, voltage, encoded

When Supabase auth is configured (`NEXT_PUBLIC_SUPABASE_URL` + anon key), unauthenticated generate calls return `401 { "error": "auth_required" }`. Browse Explore + open existing tiles stay public. Catalog Open/Load does not require auth.

### GET /api/bom?c=<encoded>
Structured BOM for a config string (lines, kit lines, AUD totals, workshopUrl, bomUrl).

### GET /api/robot?c=<encoded>
Same as /api/bom plus matching preset metadata and voltage validation.

### GET /api/agent/prompt
Current copyable agent instructions. No token is minted. CORS `*`.

### POST /api/agent/session
Signed-in browser only (cookie session). Returns `{ prompt, token, expiresAt, tokenKind }`. Dedicated agent JWT lasts ~24 hours when `AGENT_JWT_SECRET` + service role are set; otherwise the signed-in session access token is copied (its own expiry). Never the service role. Copy dock remints on each copy.

### Library APIs (owner-only, CORS `*`)
Send `Authorization: Bearer <TOKEN>` from a copied megabot prompt, or use the signed-in cookie session. The same header on the MCP HTTP transport unlocks the Library tools above.

- `GET /api/library/listings?q=`
- `GET /api/library/listings/<id>` — default latest. `?version=N|latest`
- `GET /api/library/listings/<id>/versions` — history (newest first)
- `GET /api/library/listings/<id>/versions/<n>` — one snapshot + linked attachments (`/versions/latest`)
- `POST /api/library/listings/<id>/versions` — explicit snapshot `{ title?, looks_notes?, description?, workshop_config?, note? }`
- `PATCH /api/library/listings/<id>` — content fields bump a version (not a silent overwrite). Optional `version_note`. status-only does not bump.
- `DELETE /api/library/listings/<id>`
- `POST /api/library/paste` — create listing from text + files as version 1
- `POST /api/library/listings/<id>/attachments` — attach to the *current* version. `kind`: `image` | `sim` | `cad` | `spreadsheet` | `conversation` | `other`. Images (png/jpg/webp/gif/mp4/webm), BOM/Excel (.xlsx/.xls/.csv), sim (MuJoCo/URDF/JSON/md + Onshape links in notes), CAD, PDF. JSON `{ kind, notes, text? }` for writeups without a file.
- `DELETE /api/library/listings/<id>/attachments?item_id=` — unlink from the current version (older versions keep the file)
- `POST /api/library/upload` — fallback; optional `listing_id` + `kind` (current version)
- `GET /api/library?kind=image|sim|cad|spreadsheet|conversation|other`
- `GET /api/library/<itemId>/download` — signed URL; `?preview=1` for inline media
- `PATCH /api/library/<itemId>` — title / notes
- `DELETE /api/library/<itemId>` — hard-delete from every version

Never invent shop prices or SKUs. Link catalog BOM via `GET /api/bom?c=` / MCP `get_bom`. On 401, ask the maker to copy a new megabot prompt. Uploads are not upserts. Apply `supabase/migrations/20260910_listing_versions.sql` for version history.

### MCP POST/GET/DELETE /api/mcp
See Remote MCP above. Catalog tools: search_robots, get_robot, get_bom, create_robot, validate_design, list_stl_sources, get_parts_map. Library tools (Bearer): list_library_listings, get_library_listing, list_library_versions, get_library_version, create_library_listing, update_library_listing, create_library_version, attach_library_item, get_library_download, unlink_library_attachment, delete_library_listing. All: search_robots, get_robot, get_bom, create_robot, validate_design, list_stl_sources, get_parts_map, list_library_listings, get_library_listing, list_library_versions, get_library_version, create_library_listing, update_library_listing, create_library_version, attach_library_item, get_library_download, unlink_library_attachment, delete_library_listing.

## Agent recipe
1. `search_robots` (or POST /api/prompt) with the user’s robot description.
2. `validate_design` against stated requirements (voltage, DOF, chores, print).
3. `create_robot` when they want a new mix; read `config`, `workshopUrl`, `bomUrl`, `printChecklist`.
4. `get_bom` + `list_stl_sources` for AUD lines and real print URLs.
5. Send the user `workshopUrl` / `bomUrl`. Never invent AUD amounts.
6. Private Library (Bearer on the MCP transport): `list_library_listings` → `get_library_listing` → `create_library_listing` / `update_library_listing` / `attach_library_item`. Content updates bump versions (`list_library_versions`, `get_library_version`). Signed files: `get_library_download`.

## Human UI
- Explore (default `/`): Midjourney-style robot masonry + prompt (link: Agent API → /llms.txt). Prominent **Alibaba Parts** button → /parts-map.
- Workshop: project page with INFO / PARTS / WIRING / MECH / INSTRUCTIONS tabs + primary **View BOM** (live AUD) / Parts Map / Buy Now (parts kit, coming soon) / Upgrade (USD plans) / Share. Prompt stays above region chips.
- Library: `/library` (signed-in, Google or magic link) — list saved private robot listings; create via the global Open/Generate prompt, `POST /api/library/paste`, or the signed-in agent dock. `/library/<id>` is the owner-only detail page with Simulations & modelling + Images and a version picker (`?v=N`). Explore links Library / saved into those listings.
- Parts Map: `/parts-map` (alias `/alibaba`) — linked parts datatable (filter/sort/search) of Explore-kit BOM + all servos, kit-family chips, relation inspector, substitutes, replace matrix, expandable QUOTE/EST cost trees, `application/ld+json` on the page. Seed in `data/alibaba-parts-map.ts` + `data/parts-map-cost-trees.ts` + Explore BOMs. GET /api/parts-map?family= · GET /api/parts-map.jsonld
- Pricing: `/pricing` — Basic $0, Pro $20/mo or $156/yr, Ultra $200/mo or $1,500/yr (USD). Credit packs $10 / $50 / $200. Stripe Checkout via POST /api/create-checkout-session. Parts BOMs stay AUD.
- Open BOM via URL: `/?c=<config>&bom=1` or press `B` in Workshop