ikea-mcp 1.0.0 → 1.2.0

package/README.md

@@ -9,13 +9,15 @@ Read-only MCP server for IKEA product search and in-store stock lookup.
 | Tool | What it does |
 |---|---|
 | `search_products` | Search IKEA products by keyword |
+| `get_product_details` | Get details for a single product by item number |
 | `check_store_stock` | Check cash-and-carry stock at one store |
+| `check_multi_item_stock` | Check stock for multiple items at one store |
 | `compare_store_stock` | Compare stock across multiple stores |
 | `find_best_store_for_item` | Rank stores by in-stock quantity |
 
 ## MVP limitations
 - Uses unofficial public IKEA APIs — no SLA, may break without notice
-- ~50 confirmed US stores in catalog (`src/data/stores.ts`); some IDs remain unverified
+- ~65 confirmed US and Canada stores in catalog (`src/data/stores.ts`); some IDs remain unverified
 - Cash-and-carry availability only — click-and-collect and home delivery not exposed
 - HTTP transport has no auth — do not expose publicly without adding authentication
 - Read-only — no cart, order, or account operations
@@ -54,6 +56,36 @@ Search IKEA products by keyword.
 
 ---
 
+### `get_product_details`
+
+Get details for a single IKEA product by item number.
+
+**Input**
+| param | type | default | required |
+|---|---|---|---|
+| `itemNo` | string | — | yes |
+| `countryCode` | string | `"us"` | no |
+| `langCode` | string | `"en"` | no |
+
+**Output**
+```json
+{
+  "itemNo": "20522046",
+  "name": "BILLY",
+  "typeName": "Bookcase",
+  "salesPrice": { "amount": 79, "currencyCode": "USD" },
+  "pipUrl": "https://www.ikea.com/us/en/p/billy-bookcase-white-20522046/",
+  "designText": "white",
+  "measureText": "31 1/2x11x79 1/2 \"",
+  "ratingValue": 4.6,
+  "ratingCount": 2620
+}
+```
+
+> `shortDescription` and `materials` are not available from the underlying API.
+
+---
+
 ### `check_store_stock`
 
 Check stock at a single IKEA store.
@@ -104,6 +136,36 @@ Compare stock for one item across multiple stores.
 
 ---
 
+### `check_multi_item_stock`
+
+Check cash-and-carry stock for multiple items at a single store in one call.
+
+**Input**
+| param | type | default | required |
+|---|---|---|---|
+| `storeId` | string | — | yes |
+| `itemNos` | string[] (min 1, max 20) | — | yes |
+
+**Output** — array of per-item stock entries in the same order as `itemNos`:
+
+```json
+[
+  {
+    "itemNo": "20522046",
+    "storeId": "399",
+    "storeLabel": "399 (Burbank, CA)",
+    "availableForCashCarry": true,
+    "quantity": 104,
+    "messageType": "HIGH_IN_STOCK",
+    "errors": []
+  }
+]
+```
+
+Items not stocked at that store appear with `availableForCashCarry: false`, `quantity: null`, and a 404 error entry. An invalid `storeId` (405) returns that error on every entry.
+
+---
+
 ### `find_best_store_for_item`
 
 Find stores with the highest in-stock quantity for an item. Queries stores in parallel, excludes invalid stores (405), out-of-stock stores (404), and stores with unknown quantity. Results sorted by quantity descending; ties broken by `storeId` lexicographically.
@@ -128,7 +190,7 @@ Find stores with the highest in-stock quantity for an item. Queries stores in pa
 ]
 ```
 
-Returns `[]` if no store has the item in stock. "All known stores" means the ~50 entries in `src/data/stores.ts`.
+Returns `[]` if no store has the item in stock. "All known stores" means the ~65 US and Canada entries in `src/data/stores.ts`.
 
 ---
 
@@ -148,9 +210,9 @@ node smoke.mjs       # end-to-end stdio smoke test
 
 **stdio** (default — for Claude Desktop / MCP CLI):
 ```bash
-node dist/index.js
-# or during dev:
-npm run dev
+npx ikea-mcp          # after npm install (uses bin entry)
+node dist/index.js    # after local build
+npm run dev           # dev (tsx, no build needed)
 ```
 
 **Streamable HTTP** (for remote / network clients):
@@ -184,7 +246,23 @@ Endpoints after deploy:
 
 > **Security note:** No auth is implemented in this MVP. Do not expose the `/mcp` endpoint publicly without adding authentication. The server is read-only — no cart, order, or account operations are possible.
 
-## Connecting a remote MCP client
+## Connecting a local MCP client (stdio)
+
+**Claude Desktop** (`claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "ikea-mcp": {
+      "command": "npx",
+      "args": ["-y", "ikea-mcp"]
+    }
+  }
+}
+```
+
+---
+
+## Connecting a remote MCP client (HTTP)
 
 Point your MCP client at `https://<your-host>/mcp`.
 
@@ -224,12 +302,12 @@ The `Accept: application/json, text/event-stream` header is required by the MCP
 
 ## Store IDs
 
-Store metadata (ID → city label) lives in `src/data/stores.ts`. ~50 US stores are confirmed from `ikea.com/us/en/stores/<slug>/` pages.
+Store metadata (ID → city label) lives in `src/data/stores.ts`. ~50 US stores confirmed from `ikea.com/us/en/stores/` pages; 15 Canada stores confirmed from `ikea.com/ca/en/stores/` pages (all probed against the stock API).
 
 Confirmed compatible `storeId` formats:
-- Standard 3-digit: `"399"` (Burbank, CA)
-- Leading-zero 3-digit: `"026"` (Canton, MI), `"042"` (Tampa, FL)
-- 4-digit: `"921"` (Brooklyn, NY), `"1129"` (Syracuse, NY)
+- Standard 3-digit: `"399"` (Burbank, CA, US), `"216"` (Calgary, AB, CA)
+- Leading-zero 3-digit: `"026"` (Canton, MI, US), `"039"` (Montreal, QC, CA)
+- 4-digit: `"921"` (Brooklyn, NY, US), `"1129"` (Syracuse, NY, US)
 
 Some stores remain unconfirmed (no store page ID found or not yet probed). A few valid-looking IDs from the stock API have no known city mapping — see TODO comments in `stores.ts`.
 

package/dist/data/stores.js

@@ -1,10 +1,14 @@
 // US store labels confirmed from ikea.com/us/en/stores/<slug>/ pages (store_id= survey param).
+// CA store labels confirmed from ikea.com/ca/en/stores/<slug>/ pages (storeNo= embedded JSON).
 // IDs match the sto/{storeId} path used by the IKEA stock API.
 // 4-digit IDs (921, 1099, 1129) are newer-format stores — confirmed working with stock API.
 // 3136 (San Francisco) returns 405 from stock API — excluded.
-// TODO: huntsville, arcadia, mcallen-pharr, san-marcos — IDs not found on store pages.
-// TODO: 313, 372, 414, 448, 529, 559, 612, 634, 652, 661, 663, 692, 693 — valid API IDs, city unknown (possibly CA/other).
+// 698 (CA — unknown city) returns 422 from stock API — excluded.
+// 659 (Toronto Downtown) returns 200 but null quantity — included conservatively.
+// TODO: huntsville, arcadia, mcallen-pharr, san-marcos (US) — IDs not found on store pages.
+// TODO: 448, 612, 634, 652, 661, 663, 692, 693 — valid API IDs, city/country unknown.
 export const STORE_LABELS = {
+    // ── United States ────────────────────────────────────────────────────────────
     "026": "026 (Canton, MI)",
     "027": "027 (Round Rock, TX)",
     "028": "028 (Portland, OR)",
@@ -57,6 +61,24 @@ export const STORE_LABELS = {
     "921": "921 (Brooklyn, NY)",
     "1099": "1099 (University Park, TX)",
     "1129": "1129 (Syracuse, NY)",
+    // ── Canada ───────────────────────────────────────────────────────────────────
+    // Confirmed from ikea.com/ca/en/stores/<slug>/ pages (storeNo= embedded JSON).
+    // All probed against stock API with item 20522046 — all return 200.
+    "003": "003 (Richmond, BC, CA)",
+    "004": "004 (Ottawa, ON, CA)",
+    "039": "039 (Montreal, QC, CA)",
+    "040": "040 (Burlington, ON, CA)",
+    "149": "149 (North York, ON, CA)",
+    "216": "216 (Calgary, AB, CA)",
+    "249": "249 (Winnipeg, MB, CA)",
+    "256": "256 (Etobicoke, ON, CA)",
+    "313": "313 (Coquitlam, BC, CA)",
+    "349": "349 (Edmonton, AB, CA)",
+    "372": "372 (Vaughan, ON, CA)",
+    "414": "414 (Boucherville, QC, CA)",
+    "529": "529 (Halifax, NS, CA)",
+    "559": "559 (Quebec City, QC, CA)",
+    "659": "659 (Toronto Downtown, ON, CA)",
 };
 export function storeLabel(storeId) {
     return STORE_LABELS[storeId];

package/dist/index.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createServer } from "./server.js";
 const transport = new StdioServerTransport();

package/dist/schemas/index.js

@@ -20,3 +20,12 @@ export const FindBestStoreInput = z.object({
     storeIds: z.array(z.string().min(1)).optional(),
     maxResults: z.number().int().min(1).max(10).default(3),
 });
+export const GetProductDetailsInput = z.object({
+    itemNo: z.string().min(1),
+    countryCode: z.string().length(2).default("us"),
+    langCode: z.string().length(2).default("en"),
+});
+export const CheckMultiItemStockInput = z.object({
+    storeId: z.string().min(1),
+    itemNos: z.array(z.string().min(1)).min(1).max(20),
+});

package/dist/server.js

@@ -4,7 +4,9 @@ import { searchProductsTool } from "./tools/search_products.js";
 import { checkStoreStockTool } from "./tools/check_store_stock.js";
 import { compareStoreStockTool } from "./tools/compare_store_stock.js";
 import { findBestStoreForItemTool } from "./tools/find_best_store_for_item.js";
-const tools = [searchProductsTool, checkStoreStockTool, compareStoreStockTool, findBestStoreForItemTool];
+import { getProductDetailsTool } from "./tools/get_product_details.js";
+import { checkMultiItemStockTool } from "./tools/check_multi_item_stock.js";
+const tools = [searchProductsTool, checkStoreStockTool, compareStoreStockTool, findBestStoreForItemTool, getProductDetailsTool, checkMultiItemStockTool];
 export function createServer() {
     const server = new Server({ name: "ikea-mcp", version: "1.0.0" }, { capabilities: { tools: {} } });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({

package/dist/services/ikea.js

@@ -19,6 +19,68 @@ export function projectStock(result) {
         errors: annotateStockErrors(result.errors) ?? [],
     };
 }
+export function projectMultiItemStock(result, itemNos) {
+    // Build lookup maps
+    const byItemNo = new Map();
+    for (const a of result.availabilities ?? []) {
+        byItemNo.set(a.itemKey.itemNo, a);
+    }
+    const errorByItemNo = new Map();
+    for (const e of result.errors ?? []) {
+        if (e.details?.itemNo)
+            errorByItemNo.set(e.details.itemNo, e);
+    }
+    // 405 = store doesn't exist — applies to all items
+    const storeError = result.errors?.find((e) => e.code === 405);
+    return itemNos.map((itemNo) => {
+        if (storeError) {
+            return {
+                itemNo,
+                availableForCashCarry: false,
+                quantity: null,
+                messageType: null,
+                errors: [{ ...storeError, meaning: "store ID does not exist" }],
+            };
+        }
+        const a = byItemNo.get(itemNo);
+        if (a) {
+            return {
+                itemNo,
+                availableForCashCarry: a.availableForCashCarry,
+                quantity: a.buyingOption.cashCarry.availability.quantity,
+                messageType: a.buyingOption.cashCarry.availability.probability.thisDay.messageType,
+                errors: [],
+            };
+        }
+        const itemErr = errorByItemNo.get(itemNo);
+        const annotatedNotStocked = [
+            itemErr
+                ? { ...itemErr, meaning: itemErr.code === 404 ? "item not stocked at this store" : "unknown" }
+                : { code: 404, message: "Not found", meaning: "item not stocked at this store" },
+        ];
+        return {
+            itemNo,
+            availableForCashCarry: false,
+            quantity: null,
+            messageType: null,
+            errors: annotatedNotStocked,
+        };
+    });
+}
+// ── Product projection ────────────────────────────────────────────────────────
+export function projectProduct(p) {
+    return {
+        itemNo: p.itemNo,
+        name: p.name,
+        typeName: p.typeName,
+        salesPrice: { amount: p.salesPrice.numeral, currencyCode: p.salesPrice.currencyCode },
+        pipUrl: p.pipUrl,
+        designText: p.validDesignText ?? null,
+        measureText: p.itemMeasureReferenceText ?? null,
+        ratingValue: p.ratingValue,
+        ratingCount: p.ratingCount,
+    };
+}
 // ── Service functions ─────────────────────────────────────────────────────────
 export async function searchProducts(query, countryCode, langCode, size) {
     // Correct endpoint: /search-result-page (not /search — returns 404)
@@ -28,6 +90,22 @@ export async function searchProducts(query, countryCode, langCode, size) {
         "User-Agent": "Mozilla/5.0",
     });
 }
+export async function getProductDetails(itemNo, countryCode, langCode) {
+    const result = await searchProducts(itemNo, countryCode, langCode, 5);
+    const items = result.searchResultPage.products.main.items;
+    const match = items.find((i) => i.product?.itemNo === itemNo || i.product?.itemNoGlobal === itemNo);
+    if (!match) {
+        throw new Error(`item not found: ${itemNo}`);
+    }
+    return projectProduct(match.product);
+}
+export async function getMultiItemStock(itemNos, storeId) {
+    const url = `${STOCK_BASE}/sto/${storeId}` +
+        `?itemNos=${itemNos.map(encodeURIComponent).join(",")}&expand=StoresList,Restocks`;
+    return fetchJson(url, {
+        "X-Client-Id": STOCK_CLIENT_ID,
+    });
+}
 export async function getStoreStock(itemNo, storeId, 
 // countryCode unused: endpoint path is /sto/{storeId}, country is implicit in storeId
 _countryCode) {

package/dist/tools/check_multi_item_stock.js

@@ -0,0 +1,30 @@
+import { CheckMultiItemStockInput } from "../schemas/index.js";
+import { getMultiItemStock, projectMultiItemStock } from "../services/ikea.js";
+import { storeLabel } from "../data/stores.js";
+export const checkMultiItemStockTool = {
+    name: "check_multi_item_stock",
+    description: "Check cash-and-carry stock for multiple items at a single IKEA store.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            storeId: { type: "string" },
+            itemNos: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 20 },
+        },
+        required: ["storeId", "itemNos"],
+    },
+    async handler(rawInput) {
+        const input = CheckMultiItemStockInput.parse(rawInput);
+        const result = await getMultiItemStock(input.itemNos, input.storeId);
+        const label = storeLabel(input.storeId);
+        const rows = projectMultiItemStock(result, input.itemNos).map((row) => ({
+            itemNo: row.itemNo,
+            storeId: input.storeId,
+            ...(label ? { storeLabel: label } : {}),
+            availableForCashCarry: row.availableForCashCarry,
+            quantity: row.quantity,
+            messageType: row.messageType,
+            errors: row.errors,
+        }));
+        return { content: [{ type: "text", text: JSON.stringify(rows, null, 2) }] };
+    },
+};

package/dist/tools/get_product_details.js

@@ -0,0 +1,20 @@
+import { GetProductDetailsInput } from "../schemas/index.js";
+import { getProductDetails } from "../services/ikea.js";
+export const getProductDetailsTool = {
+    name: "get_product_details",
+    description: "Get details for a single IKEA product by item number.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            itemNo: { type: "string" },
+            countryCode: { type: "string", default: "us" },
+            langCode: { type: "string", default: "en" },
+        },
+        required: ["itemNo"],
+    },
+    async handler(rawInput) {
+        const input = GetProductDetailsInput.parse(rawInput);
+        const output = await getProductDetails(input.itemNo, input.countryCode, input.langCode);
+        return { content: [{ type: "text", text: JSON.stringify(output, null, 2) }] };
+    },
+};

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "ikea-mcp",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Read-only MCP server for IKEA product search and in-store stock lookup. Supports stdio and Streamable HTTP transports.",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",
+  "bin": {
+    "ikea-mcp": "dist/index.js"
+  },
   "files": [
     "dist/",
     "Procfile"