icebox-mcp 1.0.0

package/README.md

@@ -0,0 +1,16 @@
+# icebox-mcp
+
+Query the Icebox Diamonds & Watches catalog (icebox.com, NYC): search diamond jewelry and watches, newest arrivals by type, enriched product details (metal/size/clarity variants), price stats, below-median deals, and category counts. Public storefront data, no API key required. Not affiliated with Icebox.
+
+## Tools
+
+- `search_products` — Keyword search across the catalog.
+- `list_newest` — Newest catalog products, sorted by publish date.
+- `get_product` — Full details: variants with parsed options, images, description, tags.
+- `price_overview` — Ask-price distribution (min/p25/median/p75/max).
+- `find_deals` — Available products priced below the median.
+- `list_categories` — Product-type counts in the catalog sample.
+
+## Source
+
+[icebox-mcp](https://github.com/mrfentmen/awesome-mcps/tree/main/servers/icebox-mcp)

package/dist/api.d.ts

@@ -0,0 +1,10 @@
+export declare class IceboxError extends Error {
+    constructor(message: string);
+}
+export declare function errorMessage(e: unknown): string;
+export declare function searchProducts(query: string, limit?: string, maxPrice?: string, productType?: string): Promise<string>;
+export declare function listNewest(limit?: string, page?: string, productType?: string): Promise<string>;
+export declare function getProduct(handle: string): Promise<string>;
+export declare function priceOverview(limit?: string): Promise<string>;
+export declare function findDeals(limit?: string, sample?: string): Promise<string>;
+export declare function listCategories(): Promise<string>;

package/dist/api.js

@@ -0,0 +1,174 @@
+export class IceboxError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "IceboxError";
+    }
+}
+export function errorMessage(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+const UA = { "User-Agent": "awesome-mcps/1.0" };
+const CATALOG = "https://icebox.com/products.json";
+const SUGGEST = "https://icebox.com/search/suggest.json";
+const PRODUCT_BASE = "https://icebox.com/products";
+function pretty(data) {
+    const t = typeof data === "string" ? data : JSON.stringify(data, null, 2);
+    return t.length > 12000 ? t.slice(0, 12000) + "\n…(truncated)" : t;
+}
+async function getJson(url) {
+    let res;
+    try {
+        res = await fetch(url, { headers: { ...UA } });
+    }
+    catch (e) {
+        throw new IceboxError(`Network error: ${e.message}`);
+    }
+    if (!res.ok)
+        throw new IceboxError(`HTTP ${res.status} for ${new URL(url).hostname}`);
+    return res.json();
+}
+function slim(p) {
+    const variants = Array.isArray(p.variants) ? p.variants : [];
+    const varPrices = variants.map((v) => Number(v.price)).filter((n) => Number.isFinite(n));
+    const topPrice = Number(p.price ?? p.price_min);
+    const prices = varPrices.length ? varPrices : (Number.isFinite(topPrice) ? [topPrice] : []);
+    const images = Array.isArray(p.images) ? p.images : [];
+    const img0 = images.length ? images[0] : null;
+    return {
+        id: p.id,
+        title: p.title,
+        handle: p.handle,
+        vendor: p.vendor,
+        product_type: p.product_type,
+        price_usd: prices.length ? Math.min(...prices) : null,
+        available: variants.some((v) => v.available) || p.available === true,
+        url: `${PRODUCT_BASE}/${p.handle}`,
+        image: typeof img0 === "string" ? img0 : (img0?.src ?? null),
+        published_at: p.published_at ?? null,
+    };
+}
+function passes(s, maxPrice, productType) {
+    if (maxPrice !== undefined && (s.price_usd === null || s.price_usd > maxPrice))
+        return false;
+    if (productType && !s.product_type.toLowerCase().includes(productType.toLowerCase()))
+        return false;
+    return true;
+}
+async function catalogPage(page) {
+    const data = await getJson(`${CATALOG}?limit=250&page=${page}`);
+    return Array.isArray(data.products) ? data.products : [];
+}
+async function sampleCatalog(maxItems, pages) {
+    const out = [];
+    for (const pg of pages) {
+        if (out.length >= maxItems)
+            break;
+        try {
+            for (const p of await catalogPage(pg)) {
+                out.push(p);
+                if (out.length >= maxItems)
+                    break;
+            }
+        }
+        catch { /* page failed — keep what we have */ }
+    }
+    return out;
+}
+export async function searchProducts(query, limit, maxPrice, productType) {
+    const n = Math.min(Number(limit ?? 10) || 10, 25);
+    const mp = maxPrice !== undefined ? Number(maxPrice) : undefined;
+    const data = await getJson(`${SUGGEST}?q=${encodeURIComponent(query)}&resources[type]=product&resources[limit]=${n}`);
+    const products = data?.resources?.results?.products ?? [];
+    const out = [];
+    for (const p of products) {
+        const sl = slim(p);
+        if (passes(sl, mp, productType))
+            out.push(sl);
+        if (out.length >= n)
+            break;
+    }
+    return pretty({ store: "Icebox", query, count: out.length, listings: out });
+}
+export async function listNewest(limit, page, productType) {
+    const n = Math.min(Number(limit ?? 20) || 20, 50);
+    const pg = Math.max(Number(page ?? 1) || 1, 1);
+    const out = [];
+    for (const p of await catalogPage(pg)) {
+        const sl = slim(p);
+        if (sl.product_type && (!productType || sl.product_type.toLowerCase().includes(productType.toLowerCase())))
+            out.push(sl);
+    }
+    out.sort((a, b) => String(b.published_at ?? "").localeCompare(String(a.published_at ?? "")));
+    return pretty({ store: "Icebox", page: pg, count: out.length, listings: out.slice(0, n) });
+}
+function parseParts(title) {
+    return String(title ?? "").split("/").map((s) => s.trim()).filter(Boolean);
+}
+export async function getProduct(handle) {
+    const p = await getJson(`${PRODUCT_BASE}/${encodeURIComponent(handle)}.js`);
+    const sl = slim(p);
+    // .js detail quotes money in cents; catalog/suggest quote dollars.
+    const variants = (Array.isArray(p.variants) ? p.variants : []).map((v) => ({
+        title: v.title, parts: parseParts(v.title),
+        price_usd: Math.round(Number(v.price)) / 100, compare_at_usd: v.compare_at_price !== null && v.compare_at_price !== undefined ? Math.round(Number(v.compare_at_price)) / 100 : null,
+        available: v.available,
+    }));
+    const images = (Array.isArray(p.images) ? p.images : []).map((i) => typeof i === "string" ? i : i.src).filter(Boolean);
+    const html = typeof p.body_html === "string" ? p.body_html : (typeof p.description === "string" ? p.description : "");
+    const dollar = variants.length && Number.isFinite(variants[0].price_usd) ? variants[0].price_usd : (sl.price_usd !== null ? Math.round(sl.price_usd) / 100 : null);
+    return pretty({
+        store: "Icebox", ...sl, price_usd: dollar, variants, images,
+        description: html.replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim().slice(0, 1500) || null,
+        tags: p.tags,
+    });
+}
+export async function priceOverview(limit) {
+    const n = Math.min(Number(limit ?? 200) || 200, 500);
+    const prices = [];
+    for (const p of await sampleCatalog(n, [1, 2, 3])) {
+        const sl = slim(p);
+        if (sl.price_usd !== null)
+            prices.push(sl.price_usd);
+    }
+    if (!prices.length)
+        throw new IceboxError("No priced products found.");
+    const a = [...prices].sort((x, y) => x - y);
+    const mid = a.length % 2 ? a[(a.length - 1) / 2] : (a[a.length / 2 - 1] + a[a.length / 2]) / 2;
+    return pretty({
+        store: "Icebox", currency: "USD", sample: a.length,
+        min: a[0], p25: a[Math.floor(a.length * 0.25)], median: mid,
+        p75: a[Math.floor(a.length * 0.75)], max: a[a.length - 1],
+        note: "Storefront asking prices. Not affiliated with Icebox.",
+    });
+}
+export async function findDeals(limit, sample) {
+    const n = Math.min(Number(limit ?? 10) || 10, 25);
+    const per = Math.min(Number(sample ?? 200) || 200, 500);
+    const all = [];
+    for (const p of await sampleCatalog(per, [1, 2, 3])) {
+        const sl = slim(p);
+        if (sl.price_usd !== null && sl.available)
+            all.push(sl);
+    }
+    if (!all.length)
+        throw new IceboxError("No available priced products found.");
+    const ps = all.map((s) => s.price_usd).sort((a, b) => a - b);
+    const median = ps.length % 2 ? ps[(ps.length - 1) / 2] : (ps[ps.length / 2 - 1] + ps[ps.length / 2]) / 2;
+    const deals = all
+        .filter((s) => s.price_usd < median)
+        .map((s) => ({ ...s, vs_median_usd: Math.round((s.price_usd - median) * 100) / 100, vs_median_pct: Math.round(((s.price_usd - median) / median) * 1000) / 10 }))
+        .sort((a, b) => a.vs_median_pct - b.vs_median_pct);
+    return pretty({
+        store: "Icebox", sample: all.length, median_usd: median, count: Math.min(deals.length, n),
+        deals: deals.slice(0, n),
+        note: "Below-median asks, not appraisals. Not affiliated with Icebox.",
+    });
+}
+export async function listCategories() {
+    const counts = {};
+    for (const p of await sampleCatalog(500, [1, 2])) {
+        const t = p.product_type || "unknown";
+        counts[t] = (counts[t] ?? 0) + 1;
+    }
+    return pretty({ store: "Icebox", sample: Object.values(counts).reduce((a, b) => a + b, 0), categories: counts });
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,12 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("MCP server running on stdio");
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,107 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { errorMessage, searchProducts, listNewest, getProduct, priceOverview, findDeals, listCategories, } from "./api.js";
+const text = (t) => ({ content: [{ type: "text", text: t }] });
+const textError = (t) => ({ content: [{ type: "text", text: t }], isError: true });
+const READ_ONLY = { readOnlyHint: true, openWorldHint: true };
+export function createServer() {
+    const server = new McpServer({
+        name: "icebox-mcp",
+        version: "1.0.0",
+    });
+    server.registerTool("search_products", {
+        title: "Search products",
+        description: "Keyword search across the catalog.",
+        inputSchema: z.object({
+            query: z.string().describe("Keyword, e.g. cuban link, datejust, pendant."),
+            limit: z.string().describe("Max results (default 10, max 25).").optional(),
+            max_price: z.string().describe("Max USD price.").optional(),
+            product_type: z.string().describe("Filter, e.g. Watch, Ring, Chain.").optional()
+        }),
+        annotations: READ_ONLY,
+    }, async ({ query, limit, max_price: maxPrice, product_type: productType }) => {
+        try {
+            return text(await searchProducts(query, limit, maxPrice, productType));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("list_newest", {
+        title: "Newest arrivals",
+        description: "Newest catalog products, sorted by publish date.",
+        inputSchema: z.object({
+            limit: z.string().describe("Max results (default 20, max 50).").optional(),
+            page: z.string().describe("Catalog page (default 1).").optional(),
+            product_type: z.string().describe("Filter by type.").optional()
+        }),
+        annotations: READ_ONLY,
+    }, async ({ limit, page, product_type: productType }) => {
+        try {
+            return text(await listNewest(limit, page, productType));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("get_product", {
+        title: "Get product",
+        description: "Full details: variants with parsed options, images, description, tags.",
+        inputSchema: z.object({
+            handle: z.string().describe("Product handle/slug.")
+        }),
+        annotations: READ_ONLY,
+    }, async ({ handle }) => {
+        try {
+            return text(await getProduct(handle));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("price_overview", {
+        title: "Price overview",
+        description: "Ask-price distribution (min/p25/median/p75/max).",
+        inputSchema: z.object({
+            limit: z.string().describe("Sample size (default 200, max 500).").optional()
+        }),
+        annotations: READ_ONLY,
+    }, async ({ limit }) => {
+        try {
+            return text(await priceOverview(limit));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("find_deals", {
+        title: "Find deals",
+        description: "Available products priced below the median.",
+        inputSchema: z.object({
+            limit: z.string().describe("Max deals (default 10, max 25).").optional(),
+            sample: z.string().describe("Products sampled (default 200, max 500).").optional()
+        }),
+        annotations: READ_ONLY,
+    }, async ({ limit, sample }) => {
+        try {
+            return text(await findDeals(limit, sample));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("list_categories", {
+        title: "Categories",
+        description: "Product-type counts in the catalog sample.",
+        inputSchema: z.object({}),
+        annotations: READ_ONLY,
+    }, async ({}) => {
+        try {
+            return text(await listCategories());
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    return server;
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "icebox-mcp",
+  "version": "1.0.0",
+  "description": "Icebox Diamonds jewelry: search, products, prices. Keyless.",
+  "type": "module",
+  "mcpName": "io.github.mrfentmen/icebox-mcp",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mrfentmen/awesome-mcps.git"
+  },
+  "bin": {
+    "icebox-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "dev": "rm -rf dist && tsc -p tsconfig.json && node dist/index.js",
+    "inspect": "npx @modelcontextprotocol/inspector node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "icebox",
+    "jewelry",
+    "diamonds",
+    "watches"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}