hackshop-mcp 0.0.1

package/CONTRIBUTING.md

@@ -0,0 +1,68 @@
+# Contributing to hackshop-mcp
+
+The catalog is the moat. New devices come in via PR. Tags come in via `tags.md` edits. Provenance matters.
+
+## Adding a device
+
+1. **Pick an id.** lowercase-kebab-case, unique. Format: `manufacturer-model-revision`. Example: `electric-objects-eo1`.
+2. **Verify hackability.** Either:
+   - You've personally flashed / modded this device → `brick_provenance: "founder-verified"` (only the maintainer's commits count for this).
+   - You've found credible community reports (3+ unique sources, not all linking back to the same forum thread) → `brick_provenance: "community-reported"`.
+   - Otherwise → `brick_provenance: "llm-inferred"`. Note: for `category: "handheld" | "sbc"`, llm-inferred brick-risk is **stripped from output** by the safety rule. The device will still appear, but with "brick-risk unknown."
+3. **Write the entry** in `catalog.json`. All fields required (see `src/catalog/schema.ts`).
+4. **Tags must be in `tags.md`.** Server fails to start otherwise. If you need a new tag, edit `tags.md` in the same PR.
+5. **Notes capped at 500 chars.** Keep them concrete. If the same thing keeps showing up across many devices, it should become a structured field, not a notes blurb.
+6. **`last_verified` is the date you confirmed the entry, in `YYYY-MM-DD` format.** Quarterly re-verification is the eventual goal.
+
+## Adding a tag
+
+1. Edit `tags.md`. Format: `- \`tag-name\` — short description`.
+2. Tag names: lowercase-kebab-case. Singular. No emoji.
+3. Try to fit into an existing section (Output / Audio / Input / etc.) before creating a new one.
+4. Total tag count target: ~25. If you're pushing past 30, the vocabulary is too granular — fold tags together.
+
+## PR template
+
+```
+## Device added
+- id: ...
+- category: ...
+- provenance: founder-verified | community-reported | llm-inferred
+
+## Verification (required for non-llm-inferred)
+- [ ] I have flashed / modded this device personally, OR
+- [ ] I have linked 3+ credible community sources
+
+## Sources
+- (url)
+- (url)
+
+## Tag changes (if any)
+- New tag: ...
+- Reason: ...
+
+## Brick-risk provenance check (for handheld | sbc)
+- [ ] I understand that llm-inferred provenance for handheld/sbc results in brick-risk being stripped from output (the safety rule).
+```
+
+## What not to add
+
+- Devices that aren't hackable. The catalog is for hackable hardware only.
+- Devices you can't find in any secondary market. The point is helping users acquire them.
+- Devices with brand-new firmware updates that closed the hack. (These get removed quarterly.)
+
+## Tests must pass
+
+Before opening a PR:
+
+```bash
+npm run validate   # catalog + tags
+npm test           # safety, schema, lookup
+npm run regress    # regression examples
+```
+
+Boot validation will catch tag drift; the regression runner will catch catalog/prompt drift on the existing examples.
+
+## License
+
+By contributing, you agree your contribution is MIT-licensed.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Miguel Sanchez-Grice
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# hackshop-mcp
+
+Hardware-literate AI scout for tinkerers. Idea-to-hardware mapping via MCP.
+
+You describe a project. The agent surfaces 3-5 hackable hardware options you wouldn't have thought of, with brick risk, firmware links, and a suggested eBay search query. Compose with [`ebay-mcp`](https://github.com/YosefHayim/ebay-mcp) for live listings.
+
+## Why
+
+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.
+
+## Status
+
+V0.0.1 — local development only. Not yet on npm or the MCP registry.
+
+## 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.
+
+## 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)
+- 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.
+
+## Install (local dev)
+
+```bash
+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/
+```
+
+## Day-0 Smoke Test (REQUIRED before scaffolding more)
+
+This server depends on `sampling/createMessage`. Some MCP hosts don't support it. Verify yours does first.
+
+```bash
+npm install
+```
+
+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:
+
+```json
+{
+  "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 | 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`.
+
+## 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.

package/SAMPLING.md

@@ -0,0 +1,76 @@
+# Sampling Contract
+
+This server uses MCP's `sampling/createMessage` to delegate LLM reasoning to the host. No Anthropic / OpenAI SDK is bundled. The host pays for tokens; users don't ship a second API key.
+
+## Boot probe
+
+`src/server.ts` calls `probeSamplingSupport(server)` after connect. This sends a no-op `sampling/createMessage` and logs whether the host responded. Failure is non-fatal — `propose_hardware` will return degraded responses (raw catalog matches without reasoning).
+
+Hosts known to support sampling:
+- Claude Desktop
+- Claude Code
+
+Hosts unverified as of 2026-Q1:
+- Cursor
+- other clients
+
+## propose_hardware sampling call
+
+`propose_hardware` calls `sampleJson<SamplerPick>(...)` once per invocation. Schema:
+
+### Inputs
+
+System prompt is fixed (see `src/tools/propose_hardware.ts:SYSTEM_PROMPT`).
+
+User prompt format:
+
+```
+Project idea: <idea>
+Budget (USD): <budget_usd, if present>
+Constraints: <constraints, if present>
+
+Candidate hardware:
+- id: <device-id> | name: <name> | category: <cat> | tags: <a, b, c> | notes: <notes>
+- ...
+```
+
+### Expected output
+
+JSON only, no markdown. Code-fence allowed (the parser strips it).
+
+```json
+{
+  "picks": [
+    { "id": "device-id-from-candidate-list", "why_this_fits": "one sentence" }
+  ],
+  "rationale": "one paragraph on the overall theme"
+}
+```
+
+### Constraints on the host model
+
+- `picks` must contain 0-5 entries.
+- Each `id` MUST be in the candidate list. Hallucinated ids are dropped on the server side, not surfaced to the user.
+- `why_this_fits` must reference the user's idea. The server doesn't enforce this, but the regression suite does.
+
+### Token budget
+
+`maxTokens: 1500` per call. With ~50 candidates × ~80 chars/line ≈ 4k token input + 1.5k output. Stay below 6k total.
+
+### Error handling
+
+- Sampling rejects → `sampleJson` returns `null`.
+- Sampling response is non-text → `null`.
+- Sampling response is text but not JSON-parseable → `null`.
+- On `null`, `propose_hardware` retries once. On second `null`, returns degraded response.
+
+The retry is in `sampleJson` itself (`src/sampling.ts`).
+
+### What the server NEVER does
+
+- 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.
+
+If a future feature seems to need a direct provider call, treat that as a redesign signal — not a quick patch.

package/catalog.json

@@ -0,0 +1,97 @@
+[
+  {
+    "id": "electric-objects-eo1",
+    "name": "Electric Objects EO1",
+    "category": "display",
+    "idea_fit_tags": ["display", "framed-art", "ambient", "creative-coding"],
+    "hack_difficulty": 3,
+    "brick_risk": 2,
+    "brick_provenance": "founder-verified",
+    "last_verified": "2026-05-04",
+    "firmware_links": [
+      "https://github.com/dasl-/electric-objects-revival",
+      "https://hackaday.com/tag/electric-objects/"
+    ],
+    "community_size_bucket": "small",
+    "notes": "23-inch wall-mount picture frame, abandoned by manufacturer. Linux-based, SSH access via stock firmware bug. Founder revived one in ~6h with Claude assistance."
+  },
+  {
+    "id": "raspberry-pi-4b",
+    "name": "Raspberry Pi 4 Model B",
+    "category": "sbc",
+    "idea_fit_tags": ["sbc", "low-power", "creative-coding", "kiosk"],
+    "hack_difficulty": 1,
+    "brick_risk": 1,
+    "brick_provenance": "founder-verified",
+    "last_verified": "2026-05-04",
+    "firmware_links": [
+      "https://www.raspberrypi.com/documentation/"
+    ],
+    "community_size_bucket": "thriving",
+    "notes": "Default tinkerer choice. Boring but always works. Use as baseline; recommend more interesting hardware first."
+  },
+  {
+    "id": "tidbyt-gen1",
+    "name": "Tidbyt (Gen 1)",
+    "category": "display",
+    "idea_fit_tags": ["display", "ambient", "framed-art", "creative-coding", "low-power"],
+    "hack_difficulty": 2,
+    "brick_risk": 2,
+    "brick_provenance": "community-reported",
+    "last_verified": "2026-05-04",
+    "firmware_links": [
+      "https://github.com/tidbyt/pixlet",
+      "https://github.com/tronbyt/server"
+    ],
+    "community_size_bucket": "active",
+    "notes": "64x32 LED matrix, ESP32-based. Community firmware (Tronbyt) supports self-hosted apps without Tidbyt cloud."
+  },
+  {
+    "id": "barnes-noble-nook-touch",
+    "name": "Barnes & Noble Nook Simple Touch (BNRV300)",
+    "category": "display",
+    "idea_fit_tags": ["display", "e-ink", "low-power", "framed-art", "ambient"],
+    "hack_difficulty": 2,
+    "brick_risk": 2,
+    "brick_provenance": "community-reported",
+    "last_verified": "2026-05-04",
+    "firmware_links": [
+      "https://wiki.mobileread.com/wiki/Nook_ST",
+      "https://forum.xda-developers.com/c/barnes-noble-nook.5045/"
+    ],
+    "community_size_bucket": "active",
+    "notes": "2011 e-reader, runs Android 2.1 underneath. Well-documented root path via SD card image. Community projects use it as a wall-mounted dashboard / status display."
+  },
+  {
+    "id": "amazon-kindle-paperwhite-gen2",
+    "name": "Amazon Kindle Paperwhite (Gen 2, 2013)",
+    "category": "display",
+    "idea_fit_tags": ["display", "e-ink", "low-power", "framed-art", "ambient", "kiosk"],
+    "hack_difficulty": 3,
+    "brick_risk": 3,
+    "brick_provenance": "community-reported",
+    "last_verified": "2026-05-04",
+    "firmware_links": [
+      "https://www.mobileread.com/forums/forumdisplay.php?f=150",
+      "https://github.com/koreader/koreader"
+    ],
+    "community_size_bucket": "thriving",
+    "notes": "Older Kindles (PW2 era) jailbreak via known firmware paths; newer ones harder. Used widely as low-power dashboard / calendar / weather displays. KOReader runs custom apps on jailbroken units."
+  },
+  {
+    "id": "ipad-2",
+    "name": "Apple iPad 2",
+    "category": "display",
+    "idea_fit_tags": ["display", "kiosk", "creative-coding", "framed-art"],
+    "hack_difficulty": 2,
+    "brick_risk": 1,
+    "brick_provenance": "community-reported",
+    "last_verified": "2026-05-04",
+    "firmware_links": [
+      "https://support.apple.com/guided-access",
+      "https://github.com/sponsorpay/iPad-Kiosk"
+    ],
+    "community_size_bucket": "thriving",
+    "notes": "Dirt-cheap on eBay. Guided Access locks it to a single app for a kiosk display. No jailbreak required for calendar/dashboard use cases. Older models can run iOS 9.x with vintage Safari."
+  }
+]

package/dist/catalog/load.d.ts

@@ -0,0 +1,7 @@
+import { type DeviceEntry } from "./schema.js";
+export interface LoadResult {
+    devices: DeviceEntry[];
+    tags: Set<string>;
+}
+export declare function parseTags(markdown: string): Set<string>;
+export declare function loadCatalog(): LoadResult;

package/dist/catalog/load.js

@@ -0,0 +1,73 @@
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Catalog } from "./schema.js";
+// Resolve repo root relative to this file: dist/catalog/load.js -> ../../
+const repoRoot = () => {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return join(here, "..", "..");
+};
+// Parse tags.md and extract the closed-set tag vocabulary.
+// Tags are markdown bullets like "- `tag-name` — description"
+export function parseTags(markdown) {
+    const tags = new Set();
+    const re = /^-\s+`([a-z0-9-]+)`/gm;
+    let match;
+    while ((match = re.exec(markdown)) !== null) {
+        if (match[1])
+            tags.add(match[1]);
+    }
+    return tags;
+}
+export function loadCatalog() {
+    const root = repoRoot();
+    const catalogPath = join(root, "catalog.json");
+    const tagsPath = join(root, "tags.md");
+    const rawCatalog = readFileSync(catalogPath, "utf8");
+    const rawTags = readFileSync(tagsPath, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(rawCatalog);
+    }
+    catch (e) {
+        throw new Error(`catalog.json is not valid JSON: ${e.message}\n` +
+            `Path: ${catalogPath}`);
+    }
+    const result = Catalog.safeParse(parsed);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((i) => `  - ${i.path.join(".")}: ${i.message}`)
+            .join("\n");
+        throw new Error(`catalog.json failed schema validation:\n${issues}\n` +
+            `Path: ${catalogPath}`);
+    }
+    const devices = result.data;
+    const tags = parseTags(rawTags);
+    if (tags.size === 0) {
+        throw new Error(`tags.md produced zero tags. Check the markdown format.\nPath: ${tagsPath}`);
+    }
+    // Validate every catalog tag is in tags.md (hard fail, no warnings).
+    const violations = [];
+    for (const device of devices) {
+        for (const tag of device.idea_fit_tags) {
+            if (!tags.has(tag)) {
+                violations.push(`  - device "${device.id}" uses unknown tag "${tag}"`);
+            }
+        }
+    }
+    if (violations.length > 0) {
+        throw new Error(`Tag drift detected. Catalog uses tags not declared in tags.md:\n` +
+            violations.join("\n") +
+            `\n\nFix: add the tag to tags.md, or correct the catalog entry.`);
+    }
+    // Validate device id uniqueness.
+    const seen = new Set();
+    for (const device of devices) {
+        if (seen.has(device.id)) {
+            throw new Error(`Duplicate device id in catalog: "${device.id}"`);
+        }
+        seen.add(device.id);
+    }
+    return { devices, tags };
+}
+//# sourceMappingURL=load.js.map

package/dist/catalog/load.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load.js","sourceRoot":"","sources":["../../src/catalog/load.ts"],"names":[],"mappings":"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"}

package/dist/catalog/schema.d.ts

@@ -0,0 +1,83 @@
+import { z } from "zod";
+export declare const Category: z.ZodEnum<["display", "speaker", "input", "sensor", "bulb", "sbc", "handheld", "mini-pc", "wearable", "router", "other"]>;
+export declare const Provenance: z.ZodEnum<["founder-verified", "community-reported", "llm-inferred"]>;
+export declare const CommunitySize: z.ZodEnum<["tiny", "small", "active", "thriving"]>;
+export declare const DeviceEntry: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    category: z.ZodEnum<["display", "speaker", "input", "sensor", "bulb", "sbc", "handheld", "mini-pc", "wearable", "router", "other"]>;
+    idea_fit_tags: z.ZodArray<z.ZodString, "many">;
+    hack_difficulty: z.ZodNumber;
+    brick_risk: z.ZodNumber;
+    brick_provenance: z.ZodEnum<["founder-verified", "community-reported", "llm-inferred"]>;
+    last_verified: z.ZodString;
+    firmware_links: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    community_size_bucket: z.ZodEnum<["tiny", "small", "active", "thriving"]>;
+    notes: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    name: string;
+    category: "display" | "speaker" | "input" | "sensor" | "bulb" | "sbc" | "handheld" | "mini-pc" | "wearable" | "router" | "other";
+    idea_fit_tags: string[];
+    hack_difficulty: number;
+    brick_risk: number;
+    brick_provenance: "founder-verified" | "community-reported" | "llm-inferred";
+    last_verified: string;
+    firmware_links: string[];
+    community_size_bucket: "tiny" | "small" | "active" | "thriving";
+    notes: string;
+}, {
+    id: string;
+    name: string;
+    category: "display" | "speaker" | "input" | "sensor" | "bulb" | "sbc" | "handheld" | "mini-pc" | "wearable" | "router" | "other";
+    idea_fit_tags: string[];
+    hack_difficulty: number;
+    brick_risk: number;
+    brick_provenance: "founder-verified" | "community-reported" | "llm-inferred";
+    last_verified: string;
+    community_size_bucket: "tiny" | "small" | "active" | "thriving";
+    notes: string;
+    firmware_links?: string[] | undefined;
+}>;
+export type DeviceEntry = z.infer<typeof DeviceEntry>;
+export type Category = z.infer<typeof Category>;
+export type Provenance = z.infer<typeof Provenance>;
+export declare const Catalog: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    category: z.ZodEnum<["display", "speaker", "input", "sensor", "bulb", "sbc", "handheld", "mini-pc", "wearable", "router", "other"]>;
+    idea_fit_tags: z.ZodArray<z.ZodString, "many">;
+    hack_difficulty: z.ZodNumber;
+    brick_risk: z.ZodNumber;
+    brick_provenance: z.ZodEnum<["founder-verified", "community-reported", "llm-inferred"]>;
+    last_verified: z.ZodString;
+    firmware_links: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    community_size_bucket: z.ZodEnum<["tiny", "small", "active", "thriving"]>;
+    notes: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    name: string;
+    category: "display" | "speaker" | "input" | "sensor" | "bulb" | "sbc" | "handheld" | "mini-pc" | "wearable" | "router" | "other";
+    idea_fit_tags: string[];
+    hack_difficulty: number;
+    brick_risk: number;
+    brick_provenance: "founder-verified" | "community-reported" | "llm-inferred";
+    last_verified: string;
+    firmware_links: string[];
+    community_size_bucket: "tiny" | "small" | "active" | "thriving";
+    notes: string;
+}, {
+    id: string;
+    name: string;
+    category: "display" | "speaker" | "input" | "sensor" | "bulb" | "sbc" | "handheld" | "mini-pc" | "wearable" | "router" | "other";
+    idea_fit_tags: string[];
+    hack_difficulty: number;
+    brick_risk: number;
+    brick_provenance: "founder-verified" | "community-reported" | "llm-inferred";
+    last_verified: string;
+    community_size_bucket: "tiny" | "small" | "active" | "thriving";
+    notes: string;
+    firmware_links?: string[] | undefined;
+}>, "many">;
+export type Catalog = z.infer<typeof Catalog>;
+export declare const UNRECOVERABLE_BRICK_CATEGORIES: ReadonlySet<Category>;

package/dist/catalog/schema.js

@@ -0,0 +1,41 @@
+import { z } from "zod";
+export const Category = z.enum([
+    "display",
+    "speaker",
+    "input",
+    "sensor",
+    "bulb",
+    "sbc",
+    "handheld",
+    "mini-pc",
+    "wearable",
+    "router",
+    "other",
+]);
+export const Provenance = z.enum([
+    "founder-verified",
+    "community-reported",
+    "llm-inferred",
+]);
+export const CommunitySize = z.enum(["tiny", "small", "active", "thriving"]);
+export const DeviceEntry = z.object({
+    id: z.string().min(1).regex(/^[a-z0-9-]+$/, "id must be lowercase-kebab-case"),
+    name: z.string().min(1),
+    category: Category,
+    idea_fit_tags: z.array(z.string().min(1)).min(1).max(8),
+    hack_difficulty: z.number().int().min(1).max(5),
+    brick_risk: z.number().int().min(1).max(5),
+    brick_provenance: Provenance,
+    last_verified: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "last_verified must be ISO date YYYY-MM-DD"),
+    firmware_links: z.array(z.string().url()).default([]),
+    community_size_bucket: CommunitySize,
+    notes: z.string().max(500, "notes capped at 500 chars to discourage dumping"),
+});
+export const Catalog = z.array(DeviceEntry).min(1);
+// Categories where bricking is unrecoverable. LLM-inferred brick-risk MUST be
+// stripped from output (replaced with "unknown") for these. Hard refusal rule.
+export const UNRECOVERABLE_BRICK_CATEGORIES = new Set([
+    "handheld",
+    "sbc",
+]);
+//# sourceMappingURL=schema.js.map

package/dist/catalog/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/catalog/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,CAAC,IAAI,CAAC;IAC7B,SAAS;IACT,SAAS;IACT,OAAO;IACP,QAAQ;IACR,MAAM;IACN,KAAK;IACL,UAAU;IACV,SAAS;IACT,UAAU;IACV,QAAQ;IACR,OAAO;CACR,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,IAAI,CAAC;IAC/B,kBAAkB;IAClB,oBAAoB;IACpB,cAAc;CACf,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC;AAE7E,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,cAAc,EAAE,iCAAiC,CAAC;IAC9E,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,QAAQ,EAAE,QAAQ;IAClB,aAAa,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACvD,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/C,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1C,gBAAgB,EAAE,UAAU;IAC5B,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,qBAAqB,EAAE,2CAA2C,CAAC;IACnG,cAAc,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACrD,qBAAqB,EAAE,aAAa;IACpC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,iDAAiD,CAAC;CAC9E,CAAC,CAAC;AAMH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAGnD,8EAA8E;AAC9E,+EAA+E;AAC/E,MAAM,CAAC,MAAM,8BAA8B,GAA0B,IAAI,GAAG,CAAC;IAC3E,UAAU;IACV,KAAK;CACN,CAAC,CAAC"}

package/dist/safety.d.ts

@@ -0,0 +1,7 @@
+import { type DeviceEntry } from "./catalog/schema.js";
+export interface BrickRiskOutput {
+    brick_risk: number | null;
+    brick_risk_label: string;
+    brick_risk_disclaimer: string | null;
+}
+export declare function applyBrickRiskSafety(device: DeviceEntry): BrickRiskOutput;

package/dist/safety.js

@@ -0,0 +1,31 @@
+import { UNRECOVERABLE_BRICK_CATEGORIES, } from "./catalog/schema.js";
+// Apply the V1 brick-risk safety rule. P0 — tested as a release gate.
+//
+// Rule:
+//   - llm-inferred + (handheld | sbc): strip score, replace with "unknown" label
+//   - llm-inferred + other categories:  keep score, append disclaimer
+//   - founder-verified | community-reported: keep score, no disclaimer
+export function applyBrickRiskSafety(device) {
+    const isLlmInferred = device.brick_provenance === "llm-inferred";
+    const isUnrecoverable = UNRECOVERABLE_BRICK_CATEGORIES.has(device.category);
+    if (isLlmInferred && isUnrecoverable) {
+        return {
+            brick_risk: null,
+            brick_risk_label: "brick-risk unknown — research before flashing",
+            brick_risk_disclaimer: null,
+        };
+    }
+    if (isLlmInferred) {
+        return {
+            brick_risk: device.brick_risk,
+            brick_risk_label: `${device.brick_risk}/5 (LLM-inferred, unverified)`,
+            brick_risk_disclaimer: "Brick risk for this device is LLM-inferred and unverified. Confirm with the linked community before flashing.",
+        };
+    }
+    return {
+        brick_risk: device.brick_risk,
+        brick_risk_label: `${device.brick_risk}/5 (${device.brick_provenance})`,
+        brick_risk_disclaimer: null,
+    };
+}
+//# sourceMappingURL=safety.js.map

package/dist/safety.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safety.js","sourceRoot":"","sources":["../src/safety.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,8BAA8B,GAE/B,MAAM,qBAAqB,CAAC;AAQ7B,sEAAsE;AACtE,EAAE;AACF,QAAQ;AACR,iFAAiF;AACjF,sEAAsE;AACtE,uEAAuE;AACvE,MAAM,UAAU,oBAAoB,CAAC,MAAmB;IACtD,MAAM,aAAa,GAAG,MAAM,CAAC,gBAAgB,KAAK,cAAc,CAAC;IACjE,MAAM,eAAe,GAAG,8BAA8B,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAE5E,IAAI,aAAa,IAAI,eAAe,EAAE,CAAC;QACrC,OAAO;YACL,UAAU,EAAE,IAAI;YAChB,gBAAgB,EACd,+CAA+C;YACjD,qBAAqB,EAAE,IAAI;SAC5B,CAAC;IACJ,CAAC;IAED,IAAI,aAAa,EAAE,CAAC;QAClB,OAAO;YACL,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,gBAAgB,EAAE,GAAG,MAAM,CAAC,UAAU,+BAA+B;YACrE,qBAAqB,EACnB,+GAA+G;SAClH,CAAC;IACJ,CAAC;IAED,OAAO;QACL,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,gBAAgB,EAAE,GAAG,MAAM,CAAC,UAAU,OAAO,MAAM,CAAC,gBAAgB,GAAG;QACvE,qBAAqB,EAAE,IAAI;KAC5B,CAAC;AACJ,CAAC"}

package/dist/sampling.d.ts

@@ -0,0 +1,8 @@
+import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
+export declare function sampleJson<T>(opts: {
+    server: Server;
+    systemPrompt: string;
+    userPrompt: string;
+    maxTokens?: number;
+}): Promise<T | null>;
+export declare function probeSamplingSupport(server: Server): Promise<boolean>;

package/dist/sampling.js

@@ -0,0 +1,65 @@
+// Wraps sampling/createMessage with retry-once + degraded-response semantics.
+// Returns either parsed JSON of shape T, or null if the host failed twice.
+//
+// The MCP server NEVER bundles an Anthropic/OpenAI SDK. All reasoning is
+// delegated to the host's LLM via this protocol. Cost: must verify host
+// support via boot probe (see scripts/smoke.ts and src/server.ts boot path).
+export async function sampleJson(opts) {
+    const { server, systemPrompt, userPrompt, maxTokens = 1024 } = opts;
+    const tryOnce = async () => {
+        try {
+            const response = await server.createMessage({
+                systemPrompt,
+                messages: [
+                    {
+                        role: "user",
+                        content: { type: "text", text: userPrompt },
+                    },
+                ],
+                maxTokens,
+                modelPreferences: {
+                    // hint to the host: prefer a fast model; reasoning is light here.
+                    intelligencePriority: 0.6,
+                    speedPriority: 0.4,
+                },
+            });
+            const content = response.content;
+            if (content.type !== "text")
+                return null;
+            const text = content.text.trim();
+            // Strip a possible markdown code fence around the JSON.
+            const fenced = text.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
+            const jsonText = fenced ? fenced[1] : text;
+            if (!jsonText)
+                return null;
+            return JSON.parse(jsonText);
+        }
+        catch {
+            return null;
+        }
+    };
+    const first = await tryOnce();
+    if (first !== null)
+        return first;
+    // One retry on transient failure.
+    const second = await tryOnce();
+    return second;
+}
+// Boot-time probe to verify the host actually supports sampling/createMessage.
+// Returns true if the host responded; false if it errored or returned nothing.
+export async function probeSamplingSupport(server) {
+    try {
+        const response = await server.createMessage({
+            systemPrompt: "Respond with the single word: ok. No punctuation, no explanation.",
+            messages: [
+                { role: "user", content: { type: "text", text: "probe" } },
+            ],
+            maxTokens: 8,
+        });
+        return response.content.type === "text";
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=sampling.js.map

package/dist/sampling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampling.js","sourceRoot":"","sources":["../src/sampling.ts"],"names":[],"mappings":"AAEA,8EAA8E;AAC9E,2EAA2E;AAC3E,EAAE;AACF,yEAAyE;AACzE,wEAAwE;AACxE,6EAA6E;AAC7E,MAAM,CAAC,KAAK,UAAU,UAAU,CAAI,IAKnC;IACC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,SAAS,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;IAEpE,MAAM,OAAO,GAAG,KAAK,IAAuB,EAAE;QAC5C,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC;gBAC1C,YAAY;gBACZ,QAAQ,EAAE;oBACR;wBACE,IAAI,EAAE,MAAM;wBACZ,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE;qBAC5C;iBACF;gBACD,SAAS;gBACT,gBAAgB,EAAE;oBAChB,kEAAkE;oBAClE,oBAAoB,EAAE,GAAG;oBACzB,aAAa,EAAE,GAAG;iBACnB;aACF,CAAC,CAAC;YAEH,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC;YACjC,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM;gBAAE,OAAO,IAAI,CAAC;YACzC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YAEjC,wDAAwD;YACxD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAC;YAC7D,MAAM,QAAQ,GAAG,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YAC3C,IAAI,CAAC,QAAQ;gBAAE,OAAO,IAAI,CAAC;YAE3B,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAM,CAAC;QACnC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,KAAK,GAAG,MAAM,OAAO,EAAE,CAAC;IAC9B,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAEjC,kCAAkC;IAClC,MAAM,MAAM,GAAG,MAAM,OAAO,EAAE,CAAC;IAC/B,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,+EAA+E;AAC/E,+EAA+E;AAC/E,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,MAAc;IACvD,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC;YAC1C,YAAY,EACV,mEAAmE;YACrE,QAAQ,EAAE;gBACR,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE;aAC3D;YACD,SAAS,EAAE,CAAC;SACb,CAAC,CAAC;QACH,OAAO,QAAQ,CAAC,OAAO,CAAC,IAAI,KAAK,MAAM,CAAC;IAC1C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/server.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { loadCatalog } from "./catalog/load.js";
+import { probeSamplingSupport } from "./sampling.js";
+import { proposeHardware, proposeHardwareInput, } from "./tools/propose_hardware.js";
+import { assessHackability, assessHackabilityInput, } from "./tools/assess_hackability.js";
+const NAME = "hackshop-mcp";
+const VERSION = "0.0.1";
+async function main() {
+    // Boot validation. Refuses to start on bad catalog/tags.
+    const { devices, tags } = loadCatalog();
+    process.stderr.write(`[hackshop-mcp] Catalog loaded: ${devices.length} devices, ${tags.size} tags.\n`);
+    // Note: sampling is a CLIENT capability, not a server one. We don't declare
+    // it here; we just call server.createMessage(...) and the host either
+    // supports it or doesn't. probeSamplingSupport() handles the check.
+    const server = new Server({ name: NAME, version: VERSION }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [
+            {
+                name: "propose_hardware",
+                description: "Given a project idea (vague is fine), return 3-5 hardware proposals with 'why this fits', hack difficulty, brick risk (with safety rule applied), firmware links, community size, and a suggested eBay search query string. Compose with ebay-mcp at the host level for live listings.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        idea: {
+                            type: "string",
+                            description: "Project idea, free-form. Vague is OK; the agent will use creativity.",
+                        },
+                        budget_usd: {
+                            type: "number",
+                            description: "Optional budget in USD. Affects eBay query suggestions.",
+                        },
+                        constraints: {
+                            type: "string",
+                            description: "Optional constraints (e.g., 'must be wall-mountable', 'low power').",
+                        },
+                    },
+                    required: ["idea"],
+                },
+            },
+            {
+                name: "assess_hackability",
+                description: "Given a device name, return: hackable y/n, hack difficulty, brick risk (with safety rule applied), firmware links, community size, last verified date, and notes. Looks up by id, exact name, or substring.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        device_name: {
+                            type: "string",
+                            description: "Device name or id.",
+                        },
+                    },
+                    required: ["device_name"],
+                },
+            },
+        ],
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        if (name === "propose_hardware") {
+            const input = proposeHardwareInput.parse(args);
+            const out = await proposeHardware(input, devices, server);
+            return {
+                content: [{ type: "text", text: JSON.stringify(out, null, 2) }],
+            };
+        }
+        if (name === "assess_hackability") {
+            const input = assessHackabilityInput.parse(args);
+            const out = assessHackability(input, devices);
+            return {
+                content: [{ type: "text", text: JSON.stringify(out, null, 2) }],
+            };
+        }
+        throw new Error(`Unknown tool: ${name}`);
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Probe sampling support after connect. Logs to stderr; never fatal.
+    // Some hosts (Claude Desktop, Claude Code) support sampling/createMessage;
+    // some clients don't. If unsupported, propose_hardware degrades gracefully.
+    void probeSamplingSupport(server).then((ok) => {
+        if (!ok) {
+            process.stderr.write("[hackshop-mcp] Warning: this MCP host does not appear to support " +
+                "sampling/createMessage. The propose_hardware tool will return " +
+                "degraded responses (raw catalog matches without reasoning). " +
+                "Hosts known to support sampling: Claude Desktop, Claude Code.\n");
+        }
+        else {
+            process.stderr.write("[hackshop-mcp] Sampling probe OK.\n");
+        }
+    });
+    process.stderr.write(`[hackshop-mcp] ${NAME} v${VERSION} ready.\n`);
+}
+main().catch((err) => {
+    process.stderr.write(`[hackshop-mcp] Fatal: ${err.message}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EACL,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EACL,eAAe,EACf,oBAAoB,GACrB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,+BAA+B,CAAC;AAEvC,MAAM,IAAI,GAAG,cAAc,CAAC;AAC5B,MAAM,OAAO,GAAG,OAAO,CAAC;AAExB,KAAK,UAAU,IAAI;IACjB,yDAAyD;IACzD,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,WAAW,EAAE,CAAC;IACxC,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,kCAAkC,OAAO,CAAC,MAAM,aAAa,IAAI,CAAC,IAAI,UAAU,CACjF,CAAC;IAEF,4EAA4E;IAC5E,sEAAsE;IACtE,oEAAoE;IACpE,MAAM,MAAM,GAAG,IAAI,MAAM,CACvB,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,EAChC,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,CAChC,CAAC;IAEF,MAAM,CAAC,iBAAiB,CAAC,sBAAsB,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;QAC5D,KAAK,EAAE;YACL;gBACE,IAAI,EAAE,kBAAkB;gBACxB,WAAW,EACT,wRAAwR;gBAC1R,WAAW,EAAE;oBACX,IAAI,EAAE,QAAQ;oBACd,UAAU,EAAE;wBACV,IAAI,EAAE;4BACJ,IAAI,EAAE,QAAQ;4BACd,WAAW,EACT,sEAAsE;yBACzE;wBACD,UAAU,EAAE;4BACV,IAAI,EAAE,QAAQ;4BACd,WAAW,EAAE,yDAAyD;yBACvE;wBACD,WAAW,EAAE;4BACX,IAAI,EAAE,QAAQ;4BACd,WAAW,EACT,qEAAqE;yBACxE;qBACF;oBACD,QAAQ,EAAE,CAAC,MAAM,CAAC;iBACnB;aACF;YACD;gBACE,IAAI,EAAE,oBAAoB;gBAC1B,WAAW,EACT,6MAA6M;gBAC/M,WAAW,EAAE;oBACX,IAAI,EAAE,QAAQ;oBACd,UAAU,EAAE;wBACV,WAAW,EAAE;4BACX,IAAI,EAAE,QAAQ;4BACd,WAAW,EAAE,oBAAoB;yBAClC;qBACF;oBACD,QAAQ,EAAE,CAAC,aAAa,CAAC;iBAC1B;aACF;SACF;KACF,CAAC,CAAC,CAAC;IAEJ,MAAM,CAAC,iBAAiB,CAAC,qBAAqB,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QAChE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;QAEjD,IAAI,IAAI,KAAK,kBAAkB,EAAE,CAAC;YAChC,MAAM,KAAK,GAAG,oBAAoB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC/C,MAAM,GAAG,GAAG,MAAM,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;YAC1D,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;aAChE,CAAC;QACJ,CAAC;QAED,IAAI,IAAI,KAAK,oBAAoB,EAAE,CAAC;YAClC,MAAM,KAAK,GAAG,sBAAsB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACjD,MAAM,GAAG,GAAG,iBAAiB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YAC9C,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;aAChE,CAAC;QACJ,CAAC;QAED,MAAM,IAAI,KAAK,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;IAEH,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,qEAAqE;IACrE,2EAA2E;IAC3E,4EAA4E;IAC5E,KAAK,oBAAoB,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE;QAC5C,IAAI,CAAC,EAAE,EAAE,CAAC;YACR,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,mEAAmE;gBACjE,gEAAgE;gBAChE,8DAA8D;gBAC9D,iEAAiE,CACpE,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,qCAAqC,CAAC,CAAC;QAC9D,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,kBAAkB,IAAI,KAAK,OAAO,WAAW,CAAC,CAAC;AACtE,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,yBAA0B,GAAa,CAAC,OAAO,IAAI,CAAC,CAAC;IAC1E,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/tools/assess_hackability.d.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import type { DeviceEntry } from "../catalog/schema.js";
+export declare const assessHackabilityInput: z.ZodObject<{
+    device_name: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    device_name: string;
+}, {
+    device_name: string;
+}>;
+export type AssessInput = z.infer<typeof assessHackabilityInput>;
+export interface AssessOutput {
+    found: boolean;
+    device?: {
+        id: string;
+        name: string;
+        category: string;
+        hackable: boolean;
+        hack_difficulty: number;
+        brick_risk: number | null;
+        brick_risk_label: string;
+        brick_risk_disclaimer: string | null;
+        firmware_links: string[];
+        community_size: string;
+        last_verified: string;
+        notes: string;
+    };
+    message?: string;
+}
+export declare function assessHackability(input: AssessInput, catalog: DeviceEntry[]): AssessOutput;

package/dist/tools/assess_hackability.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { applyBrickRiskSafety } from "../safety.js";
+export const assessHackabilityInput = z.object({
+    device_name: z.string().min(1).max(200),
+});
+// Simple normalization for fuzzy lookup: lowercase, strip non-alnum.
+function norm(s) {
+    return s.toLowerCase().replace(/[^a-z0-9]+/g, "");
+}
+export function assessHackability(input, catalog) {
+    const target = norm(input.device_name);
+    // Exact match by id, then by normalized name, then substring.
+    let match = catalog.find((d) => d.id === input.device_name);
+    if (!match)
+        match = catalog.find((d) => norm(d.name) === target);
+    if (!match)
+        match = catalog.find((d) => norm(d.name).includes(target) || target.includes(norm(d.name)));
+    if (!match) {
+        return {
+            found: false,
+            message: `"${input.device_name}" is not in the catalog. Cannot assess hackability without verification. Try a more specific name, or check the firmware links section of similar devices.`,
+        };
+    }
+    const safety = applyBrickRiskSafety(match);
+    return {
+        found: true,
+        device: {
+            id: match.id,
+            name: match.name,
+            category: match.category,
+            hackable: true, // presence in catalog implies hackable
+            hack_difficulty: match.hack_difficulty,
+            brick_risk: safety.brick_risk,
+            brick_risk_label: safety.brick_risk_label,
+            brick_risk_disclaimer: safety.brick_risk_disclaimer,
+            firmware_links: match.firmware_links,
+            community_size: match.community_size_bucket,
+            last_verified: match.last_verified,
+            notes: match.notes,
+        },
+    };
+}
+//# sourceMappingURL=assess_hackability.js.map

package/dist/tools/assess_hackability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assess_hackability.js","sourceRoot":"","sources":["../../src/tools/assess_hackability.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEpD,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;CACxC,CAAC,CAAC;AAuBH,qEAAqE;AACrE,SAAS,IAAI,CAAC,CAAS;IACrB,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC;AACpD,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,KAAkB,EAClB,OAAsB;IAEtB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IAEvC,8DAA8D;IAC9D,IAAI,KAAK,GAA4B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,KAAK,CAAC,WAAW,CAAC,CAAC;IACrF,IAAI,CAAC,KAAK;QAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,MAAM,CAAC,CAAC;IACjE,IAAI,CAAC,KAAK;QAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAExG,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,OAAO,EAAE,IAAI,KAAK,CAAC,WAAW,4JAA4J;SAC3L,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;IAE3C,OAAO;QACL,KAAK,EAAE,IAAI;QACX,MAAM,EAAE;YACN,EAAE,EAAE,KAAK,CAAC,EAAE;YACZ,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,QAAQ,EAAE,IAAI,EAAE,uCAAuC;YACvD,eAAe,EAAE,KAAK,CAAC,eAAe;YACtC,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;YACzC,qBAAqB,EAAE,MAAM,CAAC,qBAAqB;YACnD,cAAc,EAAE,KAAK,CAAC,cAAc;YACpC,cAAc,EAAE,KAAK,CAAC,qBAAqB;YAC3C,aAAa,EAAE,KAAK,CAAC,aAAa;YAClC,KAAK,EAAE,KAAK,CAAC,KAAK;SACnB;KACF,CAAC;AACJ,CAAC"}

package/dist/tools/propose_hardware.d.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { DeviceEntry } from "../catalog/schema.js";
+export declare const proposeHardwareInput: z.ZodObject<{
+    idea: z.ZodString;
+    budget_usd: z.ZodOptional<z.ZodNumber>;
+    constraints: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    idea: string;
+    budget_usd?: number | undefined;
+    constraints?: string | undefined;
+}, {
+    idea: string;
+    budget_usd?: number | undefined;
+    constraints?: string | undefined;
+}>;
+export type ProposeInput = z.infer<typeof proposeHardwareInput>;
+export interface Proposal {
+    id: string;
+    name: string;
+    category: string;
+    why_this_fits: string;
+    hack_difficulty: number;
+    brick_risk: number | null;
+    brick_risk_label: string;
+    brick_risk_disclaimer: string | null;
+    firmware_links: string[];
+    community_size: string;
+    ebay_query_suggestion: string;
+    notes: string;
+}
+export interface ProposeOutput {
+    proposals: Proposal[];
+    reasoning: string;
+    degraded: boolean;
+    message?: string;
+}
+export declare function proposeHardware(input: ProposeInput, catalog: DeviceEntry[], server: Server): Promise<ProposeOutput>;

package/dist/tools/propose_hardware.js

@@ -0,0 +1,117 @@
+import { z } from "zod";
+import { applyBrickRiskSafety } from "../safety.js";
+import { sampleJson } from "../sampling.js";
+export const proposeHardwareInput = z.object({
+    idea: z.string().min(3, "idea is too short").max(2000, "idea is too long"),
+    budget_usd: z.number().positive().max(100000).optional(),
+    constraints: z.string().max(500).optional(),
+});
+const SYSTEM_PROMPT = `You are a hardware-literate AI scout for tinkerers. The user gives you a project idea (often vague). You pick 3-5 hardware items from the candidate list that creatively fit the idea. Surface options the user wouldn't have thought of. Avoid recommending the obvious choice (Raspberry Pi) unless the idea genuinely calls for it.
+
+Return JSON only, no markdown, with this shape:
+{
+  "picks": [
+    { "id": "<device id from candidate list>", "why_this_fits": "<one sentence, concrete>" }
+  ],
+  "rationale": "<one paragraph on the overall theme of your picks>"
+}
+
+Rules:
+- Pick 3-5 devices. Never more than 5.
+- Only pick from the candidate list provided. Do not invent devices.
+- "why_this_fits" must mention the user's idea explicitly. No generic praise.
+- If candidates are weak for the idea, say so in the rationale rather than padding with bad picks.`;
+function buildEbayQuery(device, idea) {
+    // Suggest an eBay search query the user can pass to ebay-mcp at the host.
+    // Avoid LLM model names; use the device's marketing name.
+    const cond = device.brick_risk >= 4 ? "working" : "used";
+    return `${device.name} ${cond}`;
+}
+function candidateContext(catalog) {
+    return catalog
+        .map((d) => `- id: ${d.id} | name: ${d.name} | category: ${d.category} | tags: ${d.idea_fit_tags.join(", ")} | notes: ${d.notes}`)
+        .join("\n");
+}
+function shortlistCandidates(catalog, idea) {
+    // Naive prefilter: if the idea text mentions any tag substring, prefer those.
+    // Otherwise return the full catalog (LLM does the real picking).
+    const lower = idea.toLowerCase();
+    const tagged = catalog.filter((d) => d.idea_fit_tags.some((t) => lower.includes(t.replace("-", " "))));
+    if (tagged.length >= 5)
+        return tagged;
+    return catalog;
+}
+export async function proposeHardware(input, catalog, server) {
+    if (catalog.length === 0) {
+        return {
+            proposals: [],
+            reasoning: "Catalog is empty. Cannot propose hardware.",
+            degraded: true,
+        };
+    }
+    const candidates = shortlistCandidates(catalog, input.idea);
+    const userPrompt = [
+        `Project idea: ${input.idea}`,
+        input.budget_usd ? `Budget (USD): ${input.budget_usd}` : null,
+        input.constraints ? `Constraints: ${input.constraints}` : null,
+        "",
+        "Candidate hardware:",
+        candidateContext(candidates),
+    ]
+        .filter(Boolean)
+        .join("\n");
+    const sampled = await sampleJson({
+        server,
+        systemPrompt: SYSTEM_PROMPT,
+        userPrompt,
+        maxTokens: 1500,
+    });
+    // Degraded path: sampling failed twice. Return raw shortlist matches with a
+    // clear "reasoning unavailable" note. No hallucination, no crash.
+    if (!sampled || !Array.isArray(sampled.picks)) {
+        const fallback = candidates.slice(0, 3).map((d) => buildProposal(d, input.idea, "Reasoning unavailable; raw catalog match."));
+        return {
+            proposals: fallback,
+            reasoning: "Reasoning unavailable. The host LLM failed twice. Returning raw catalog matches; verify hackability against the linked communities.",
+            degraded: true,
+        };
+    }
+    const proposals = [];
+    for (const pick of sampled.picks.slice(0, 5)) {
+        const device = catalog.find((d) => d.id === pick.id);
+        if (!device)
+            continue; // sampler hallucinated an id; drop it
+        proposals.push(buildProposal(device, input.idea, pick.why_this_fits));
+    }
+    if (proposals.length === 0) {
+        return {
+            proposals: [],
+            reasoning: sampled.rationale ?? "No catalog match for this idea.",
+            degraded: false,
+            message: "No catalog devices fit this idea well. Consider expanding the catalog or trying a more concrete description.",
+        };
+    }
+    return {
+        proposals,
+        reasoning: sampled.rationale ?? "",
+        degraded: false,
+    };
+}
+function buildProposal(device, idea, whyThisFits) {
+    const safety = applyBrickRiskSafety(device);
+    return {
+        id: device.id,
+        name: device.name,
+        category: device.category,
+        why_this_fits: whyThisFits,
+        hack_difficulty: device.hack_difficulty,
+        brick_risk: safety.brick_risk,
+        brick_risk_label: safety.brick_risk_label,
+        brick_risk_disclaimer: safety.brick_risk_disclaimer,
+        firmware_links: device.firmware_links,
+        community_size: device.community_size_bucket,
+        ebay_query_suggestion: buildEbayQuery(device, idea),
+        notes: device.notes,
+    };
+}
+//# sourceMappingURL=propose_hardware.js.map

package/dist/tools/propose_hardware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"propose_hardware.js","sourceRoot":"","sources":["../../src/tools/propose_hardware.ts"],"names":[],"mappings":"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"}

package/examples/01-eo-revival.json

@@ -0,0 +1,7 @@
+{
+  "idea": "wall-mountable digital art display, sub-$300, supports custom firmware",
+  "expected_devices": [
+    "electric-objects-eo1"
+  ],
+  "notes": "EO revival regression test (P0 from /office-hours). The single E2E anchor: if the agent doesn't surface the EO frame for this idea, the catalog or the system prompt is broken. Do not ship until this passes."
+}

package/examples/02-house-calendar.json

@@ -0,0 +1,9 @@
+{
+  "idea": "Always-on family calendar for the kitchen wall. Light colors, no animation, minimalist list of upcoming events for the family (kids' visits, appointments). Don't want a regular LCD monitor — looking for something more like an old e-reader or repurposed tablet.",
+  "expected_devices": [
+    "barnes-noble-nook-touch",
+    "amazon-kindle-paperwhite-gen2",
+    "ipad-2"
+  ],
+  "notes": "Founder's first hand-curated example (2026-05-04). Constraints: e-ink preferred for the no-animation/light-colors aesthetic; iPad 2 as cheap kiosk fallback. Per founder research: B&N Nook Touch (Android 2.1, well-documented hack) and Amazon Kindle (older models jailbreakable) are real candidates. The agent should NOT default to Raspberry Pi for this idea — that misses the e-paper / minimalist intent."
+}

package/examples/TEMPLATE.json.example

@@ -0,0 +1,8 @@
+{
+  "idea": "REPLACE: one sentence describing your project. Vague is fine. Example: 'I want a meditation app for the bedroom.'",
+  "expected_devices": [
+    "REPLACE: device id from catalog.json that you'd expect propose_hardware to surface",
+    "REPLACE: another device id"
+  ],
+  "notes": "OPTIONAL: why these devices fit, any constraints, what surprised you when you researched manually."
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "hackshop-mcp",
+  "version": "0.0.1",
+  "description": "Hardware-literate AI scout for tinkerers. Idea-to-hardware mapping via MCP.",
+  "type": "module",
+  "bin": {
+    "hackshop-mcp": "./dist/server.js"
+  },
+  "main": "dist/server.js",
+  "files": [
+    "dist",
+    "catalog.json",
+    "tags.md",
+    "examples",
+    "README.md",
+    "SAMPLING.md",
+    "CONTRIBUTING.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/server.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "regress": "tsx scripts/regress.ts",
+    "validate": "tsx scripts/validate-catalog.ts",
+    "smoke": "tsx scripts/smoke.ts",
+    "prepublishOnly": "npm run build && npm test && npm run validate"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "hardware",
+    "hacking",
+    "tinkerer",
+    "agent"
+  ],
+  "license": "MIT",
+  "author": "Miguel Sanchez-Grice <msanchezgrice@gmail.com>",
+  "homepage": "https://github.com/msanchezgrice/hackshop-mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/msanchezgrice/hackshop-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/msanchezgrice/hackshop-mcp/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/tags.md

@@ -0,0 +1,39 @@
+# Tag Vocabulary (closed set)
+
+These are the only tags valid for `idea_fit_tags` in `catalog.json`. Adding a new tag requires editing this file. The server validates catalog tags against this list at boot — boot fails on drift.
+
+## Output / Display
+- `display` — has a screen (any kind)
+- `framed-art` — picture-frame form factor, wall-mount
+- `e-ink` — low-power monochrome / color-e-ink display
+- `ambient` — peripheral visual presence, not foreground
+
+## Audio
+- `voice` — input/output for speech
+- `audio-out` — speakers / line-out
+- `drone` — sustained ambient soundscape capable
+
+## Input
+- `input` — buttons, dials, sensors as user input
+- `kiosk` — locked-down single-purpose interface
+- `wearable` — body-worn
+
+## Sensors / Smart Home
+- `sensor` — environmental sensing (motion, temp, light)
+- `bulb` — controllable lighting
+- `color-cycle` — RGB / programmable color animation
+
+## Compute
+- `sbc` — single-board computer (Pi-class)
+- `mini-pc` — x86 small-form-factor
+- `low-power` — battery-friendly, sub-1W ideal
+
+## Form / Use
+- `retrogaming` — handheld / console for emulation
+- `handheld` — battery, portable
+- `network` — router/switch repurposing
+- `iot` — small connected device
+- `peripheral` — USB or aux to other compute
+- `educational` — kid/learning oriented
+- `industrial` — heavy-duty, repurposable
+- `creative-coding` — pixel art, generative output