ikea-mcp 1.3.0 → 1.4.0

package/README.md

@@ -8,6 +8,7 @@ Read-only MCP server for IKEA product search and in-store stock lookup.
 ## Capabilities
 | Tool | What it does |
 |---|---|
+| `list_stores` | List known store IDs and labels, optionally filtered by country |
 | `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 |
@@ -32,7 +33,7 @@ Search IKEA products by keyword.
 | param | type | default | required |
 |---|---|---|---|
 | `query` | string | — | yes |
-| `countryCode` | string | `"us"` | no |
+| `countryCode` | string | `"US"` | no |
 | `langCode` | string | `"en"` | no |
 | `size` | number | `10` | no |
 
@@ -64,7 +65,7 @@ Get details for a single IKEA product by item number.
 | param | type | default | required |
 |---|---|---|---|
 | `itemNo` | string | — | yes |
-| `countryCode` | string | `"us"` | no |
+| `countryCode` | string | `"US"` | no |
 | `langCode` | string | `"en"` | no |
 
 **Output**
@@ -95,7 +96,7 @@ Check stock at a single IKEA store.
 |---|---|---|---|
 | `itemNo` | string | — | yes |
 | `storeId` | string | — | yes |
-| `countryCode` | string | `"us"` | no |
+| `countryCode` | string | `"US"` | no |
 
 **Output**
 ```json
@@ -131,8 +132,10 @@ Compare stock for one item across multiple stores. Provide explicit `storeIds`,
 | `itemNo` | string | — | yes |
 | `storeIds` | string[] (min 2) | — | one of `storeIds`/`countryCode` |
 | `countryCode` | `"US"` \| `"CA"` | — | one of `storeIds`/`countryCode` |
+| `sortBy` | `"quantity"` \| `"storeId"` | — | no |
 
 `storeIds` takes precedence — if both are provided, `countryCode` only sets the IKEA API locale.
+`sortBy: "quantity"` sorts descending, null quantities last, `storeId` as tie-breaker. `sortBy: "storeId"` sorts ascending. Omitting `sortBy` preserves input order.
 
 **Examples**
 ```json
@@ -144,6 +147,8 @@ Compare stock for one item across multiple stores. Provide explicit `storeIds`,
 
 **Output** — array of the same shape as `check_store_stock` (one entry per store).
 
+**Detecting partial failures:** rows with `errors` containing any code other than `404` indicate a store-level or API failure (e.g. `405` = invalid store ID). Rows with only `404` errors mean the item is simply not stocked at that store — this is expected, not a failure.
+
 ---
 
 ### `check_multi_item_stock`
@@ -185,10 +190,11 @@ Find stores with the highest in-stock quantity for an item. Queries stores in pa
 |---|---|---|---|
 | `itemNo` | string | — | yes |
 | `storeIds` | string[] | all known stores | no |
-| `maxResults` | number | `3` (max 10) | no |
+| `maxResults` | number | `3` (max 50) | no |
 | `countryCode` | `"US"` \| `"CA"` | — | no |
+| `minQuantity` | number (int ≥ 1) | — | no |
 
-`storeIds` takes precedence. If only `countryCode` is given, searches all catalog stores for that country. If neither is given, searches all ~65 known stores.
+`storeIds` takes precedence. If only `countryCode` is given, searches all catalog stores for that country. If neither is given, searches all ~65 known stores. `minQuantity` excludes stores with quantity below the threshold.
 
 **Output** — array of matching stores, up to `maxResults`:
 ```json
@@ -205,6 +211,8 @@ 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 ~65 US and Canada entries in `src/data/stores.ts`.
 
+**Note on failures:** stores that return a store-level error (405 invalid store ID) are silently excluded from results rather than appearing as rows. Use `compare_store_stock` with the same `storeIds` to inspect per-store `errors` directly.
+
 ---
 
 ## Example workflows
@@ -378,6 +386,46 @@ An invalid or unsupported `storeId` returns a 405 error in the `errors` array.
 
 - Uses unofficial public IKEA APIs — no SLA, no auth required, may break without notice.
 - Read-only: no cart, no order, no account operations.
-- `compare_store_stock` fires all store requests in parallel — large `storeIds` arrays or a full `countryCode` expansion may hit rate limits.
+- Country-wide fan-out (`countryCode: "US"` ≈ 52 stores, `"CA"` ≈ 15) is capped at 10 concurrent requests and retries once on transient 5xx/network errors.
 - Click-and-collect and home-delivery availability are not exposed (cash-and-carry only).
 - `size` in `search_products` is capped by IKEA's API (observed max ~24 per page; `total` reflects the full catalogue count).
+- US and Canada only — no other countries supported.
+
+## Item numbers
+
+`itemNo` fields accept several formats — all are normalised to 8 digits internally:
+
+| Input | Normalised |
+|---|---|
+| `"20522046"` | `"20522046"` |
+| `"522132"` | `"00522132"` |
+| `"005.221.32"` | `"00522132"` |
+| `"5-221-32"` | `"00522132"` |
+
+6- and 7-digit inputs are left-padded to 8 digits. 8- and 9-digit inputs are kept as-is. Values outside 6–9 digits after stripping are rejected.
+
+## Supported countries
+
+| Country | Code | Store count |
+|---|---|---|
+| United States | `US` | ~52 |
+| Canada | `CA` | ~15 |
+
+Use `list_stores` to get the current catalog. Some store IDs in the catalog are unverified — they are listed but may return 405 from the stock API.
+
+## Rate limits & reliability
+
+- Fan-out requests (country-wide `compare_store_stock` / `find_best_store_for_item`) are capped at **10 concurrent** outbound requests.
+- `fetchJson` retries **once** after 500 ms on 5xx, 429, or network errors. 404 and 405 are not retried (they are semantic responses, not transient failures).
+- `Retry-After` header is respected for 429 responses.
+- Do not use in high-frequency loops — the upstream IKEA API has no published rate limit but will block repeated bursts.
+
+## Troubleshooting
+
+| Symptom | Likely cause |
+|---|---|
+| `405` in `errors` | Invalid `storeId` — use `list_stores` to find valid IDs |
+| `404` in `errors` | Item not stocked at that store |
+| Empty `find_best_store_for_item` result | No store has the item in stock, or `minQuantity` is too high |
+| Slow `countryCode` query | Normal — fan-out to all country stores (capped at 10 concurrent) |
+| `itemNo` validation error | Input must resolve to 6–9 digits; see Item numbers above |

package/dist/schemas/index.js

@@ -1,32 +1,71 @@
 import { z } from "zod";
+// ── normalizeItemNo ───────────────────────────────────────────────────────────
+/**
+ * Strips non-digit characters, then left-pads to 8 digits when the result is
+ * 6 or 7 digits long. 8- and 9-digit results are kept as-is. All other lengths
+ * are left unchanged and will be rejected by the downstream Zod regex.
+ *
+ * Exported so it can be unit-tested independently.
+ */
+export function normalizeItemNo(raw) {
+    const digits = raw.replace(/\D/g, "");
+    return digits.length === 6 || digits.length === 7
+        ? digits.padStart(8, "0")
+        : digits;
+}
+// Zod schema for a single IKEA item number.
+// Accepts dotted ("005.221.32"), hyphenated ("5-221-32"), and plain ("522132") inputs.
+// Rejects empty strings, <6-digit results, and >9-digit results.
+const ItemNo = z
+    .string()
+    .transform(normalizeItemNo)
+    .pipe(z
+    .string()
+    .regex(/^\d{8,9}$/, "itemNo must resolve to 8 or 9 digits after stripping non-digit characters"));
+// ── countryCode helpers ───────────────────────────────────────────────────────
+const toUpper = (v) => typeof v === "string" ? v.toUpperCase() : v;
+// Free-form 2-letter ISO country code normalised to uppercase.
+// Used by search and product-detail tools that accept any country code.
+const CountryCode2 = z.preprocess(toUpper, z.string().length(2));
+// Uppercase-normalised enum restricted to the two countries supported by the
+// stock-lookup API. Accepts "us"/"ca" and normalises to "US"/"CA".
+const CountryCodeEnum = z.preprocess(toUpper, z.enum(["US", "CA"]));
+// ── Input schemas ─────────────────────────────────────────────────────────────
 export const SearchProductsInput = z.object({
     query: z.string().min(1),
-    countryCode: z.string().length(2).default("us"),
+    countryCode: CountryCode2.default("US"),
     langCode: z.string().length(2).default("en"),
     size: z.number().int().min(1).max(50).default(10),
 });
 export const CheckStoreStockInput = z.object({
-    itemNo: z.string().min(1),
+    itemNo: ItemNo,
     storeId: z.string().min(1),
-    countryCode: z.string().length(2).default("us"),
+    countryCode: CountryCode2.default("US"),
 });
-export const CompareStoreStockInput = z.object({
-    itemNo: z.string().min(1),
+export const CompareStoreStockInput = z
+    .object({
+    itemNo: ItemNo,
     storeIds: z.array(z.string().min(1)).min(2).max(10).optional(),
-    countryCode: z.enum(["US", "CA"]).optional(),
-}).refine((d) => d.storeIds !== undefined || d.countryCode !== undefined, { message: "provide storeIds or countryCode" });
+    countryCode: CountryCodeEnum.optional(),
+    sortBy: z.enum(["quantity", "storeId"]).optional(),
+})
+    .refine((d) => d.storeIds !== undefined || d.countryCode !== undefined, { message: "provide storeIds or countryCode" });
+export const ListStoresInput = z.object({
+    countryCode: CountryCodeEnum.optional(),
+});
 export const FindBestStoreInput = z.object({
-    itemNo: z.string().min(1),
+    itemNo: ItemNo,
     storeIds: z.array(z.string().min(1)).optional(),
-    maxResults: z.number().int().min(1).max(10).default(3),
-    countryCode: z.enum(["US", "CA"]).optional(),
+    maxResults: z.number().int().min(1).max(50).default(3),
+    countryCode: CountryCodeEnum.optional(),
+    minQuantity: z.number().int().min(1).optional(),
 });
 export const GetProductDetailsInput = z.object({
-    itemNo: z.string().min(1),
-    countryCode: z.string().length(2).default("us"),
+    itemNo: ItemNo,
+    countryCode: CountryCode2.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),
+    itemNos: z.array(ItemNo).min(1).max(20),
 });

package/dist/server.js

@@ -6,7 +6,8 @@ import { compareStoreStockTool } from "./tools/compare_store_stock.js";
 import { findBestStoreForItemTool } from "./tools/find_best_store_for_item.js";
 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];
+import { listStoresTool } from "./tools/list_stores.js";
+const tools = [listStoresTool, 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

@@ -16,6 +16,7 @@ export function projectStock(result) {
         availableForCashCarry: a?.availableForCashCarry ?? false,
         quantity: a?.buyingOption.cashCarry.availability.quantity ?? null,
         messageType: a?.buyingOption.cashCarry.availability.probability.thisDay.messageType ?? null,
+        eligibleForStockNotification: a?.buyingOption.cashCarry.eligibleForStockNotification ?? null,
         errors: annotateStockErrors(result.errors) ?? [],
     };
 }

package/dist/tools/check_multi_item_stock.js

@@ -15,11 +15,10 @@ export const checkMultiItemStockTool = {
     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 } : {}),
+            storeLabel: storeLabel(input.storeId) ?? input.storeId,
             availableForCashCarry: row.availableForCashCarry,
             quantity: row.quantity,
             messageType: row.messageType,

package/dist/tools/check_store_stock.js

@@ -16,10 +16,9 @@ export const checkStoreStockTool = {
     async handler(rawInput) {
         const input = CheckStoreStockInput.parse(rawInput);
         const result = await getStoreStock(input.itemNo, input.storeId, input.countryCode);
-        const label = storeLabel(input.storeId);
         const output = {
             storeId: input.storeId,
-            ...(label ? { storeLabel: label } : {}),
+            storeLabel: storeLabel(input.storeId) ?? input.storeId,
             ...projectStock(result),
         };
         return { content: [{ type: "text", text: JSON.stringify(output, null, 2) }] };

package/dist/tools/compare_store_stock.js

@@ -1,6 +1,7 @@
 import { CompareStoreStockInput } from "../schemas/index.js";
 import { getStoreStock, projectStock } from "../services/ikea.js";
 import { storeLabel, storeIdsByCountry } from "../data/stores.js";
+import { pMap } from "../utils/http.js";
 export const compareStoreStockTool = {
     name: "compare_store_stock",
     description: "Compare stock availability for an item across multiple IKEA stores. Provide explicit storeIds, or use countryCode ('US' or 'CA') to compare all catalog stores for that country.",
@@ -10,6 +11,7 @@ export const compareStoreStockTool = {
             itemNo: { type: "string" },
             storeIds: { type: "array", items: { type: "string" }, minItems: 2 },
             countryCode: { type: "string", enum: ["US", "CA"] },
+            sortBy: { type: "string", enum: ["quantity", "storeId"] },
         },
         required: ["itemNo"],
     },
@@ -18,14 +20,20 @@ export const compareStoreStockTool = {
         const targetIds = input.storeIds
             ?? storeIdsByCountry(input.countryCode);
         const apiCountry = input.countryCode?.toLowerCase() ?? "us";
-        const results = await Promise.all(targetIds.map((storeId) => getStoreStock(input.itemNo, storeId, apiCountry).then((data) => {
-            const label = storeLabel(storeId);
-            return {
-                storeId,
-                ...(label ? { storeLabel: label } : {}),
-                ...projectStock(data),
-            };
-        })));
+        const results = await pMap(targetIds, (storeId) => getStoreStock(input.itemNo, storeId, apiCountry).then((data) => ({
+            storeId,
+            storeLabel: storeLabel(storeId) ?? storeId,
+            ...projectStock(data),
+        })), 10);
+        if (input.sortBy === "quantity") {
+            results.sort((a, b) => {
+                const diff = (b.quantity ?? -Infinity) - (a.quantity ?? -Infinity);
+                return diff !== 0 ? diff : a.storeId.localeCompare(b.storeId);
+            });
+        }
+        else if (input.sortBy === "storeId") {
+            results.sort((a, b) => a.storeId.localeCompare(b.storeId));
+        }
         return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
     },
 };

package/dist/tools/find_best_store_for_item.js

@@ -1,6 +1,7 @@
 import { FindBestStoreInput } from "../schemas/index.js";
 import { getStoreStock, projectStock } from "../services/ikea.js";
 import { STORE_LABELS, storeLabel, storeIdsByCountry } from "../data/stores.js";
+import { pMap } from "../utils/http.js";
 export const findBestStoreForItemTool = {
     name: "find_best_store_for_item",
     description: "Find stores with the highest in-stock quantity for an item. Returns up to maxResults stores sorted by quantity descending. Optionally filter by countryCode ('US' or 'CA'). Explicit storeIds take precedence over countryCode.",
@@ -11,6 +12,7 @@ export const findBestStoreForItemTool = {
             storeIds: { type: "array", items: { type: "string" } },
             maxResults: { type: "number", default: 3 },
             countryCode: { type: "string", enum: ["US", "CA"] },
+            minQuantity: { type: "number" },
         },
         required: ["itemNo"],
     },
@@ -18,28 +20,27 @@ export const findBestStoreForItemTool = {
         const input = FindBestStoreInput.parse(rawInput);
         const targetIds = input.storeIds
             ?? (input.countryCode ? storeIdsByCountry(input.countryCode) : Object.keys(STORE_LABELS));
-        const results = await Promise.all(targetIds.map(async (storeId) => {
+        const results = await pMap(targetIds, async (storeId) => {
             const data = await getStoreStock(input.itemNo, storeId, "us");
             const stock = projectStock(data);
             return { storeId, stock };
-        }));
+        }, 10);
         const ranked = results
-            .filter((r) => r.stock.availableForCashCarry && r.stock.quantity !== null)
+            .filter((r) => r.stock.availableForCashCarry &&
+            r.stock.quantity !== null &&
+            (input.minQuantity === undefined || r.stock.quantity >= input.minQuantity))
             .sort((a, b) => {
             const diff = (b.stock.quantity ?? 0) - (a.stock.quantity ?? 0);
             return diff !== 0 ? diff : a.storeId.localeCompare(b.storeId);
         })
             .slice(0, input.maxResults)
-            .map(({ storeId, stock }) => {
-            const label = storeLabel(storeId);
-            return {
-                storeId,
-                ...(label ? { storeLabel: label } : {}),
-                availableForCashCarry: stock.availableForCashCarry,
-                quantity: stock.quantity,
-                messageType: stock.messageType,
-            };
-        });
+            .map(({ storeId, stock }) => ({
+            storeId,
+            storeLabel: storeLabel(storeId) ?? storeId,
+            availableForCashCarry: stock.availableForCashCarry,
+            quantity: stock.quantity,
+            messageType: stock.messageType,
+        }));
         return { content: [{ type: "text", text: JSON.stringify(ranked, null, 2) }] };
     },
 };

package/dist/tools/list_stores.js

@@ -0,0 +1,30 @@
+import { ListStoresInput } from "../schemas/index.js";
+import { STORE_LABELS, storeLabel, storeIdsByCountry } from "../data/stores.js";
+export const listStoresTool = {
+    name: "list_stores",
+    description: "List known IKEA store IDs and display names. Use countryCode ('US' or 'CA') to filter by country, or omit to return all stores.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            countryCode: { type: "string", enum: ["US", "CA"] },
+        },
+    },
+    async handler(rawInput) {
+        const input = ListStoresInput.parse(rawInput);
+        const storeIds = input.countryCode
+            ? storeIdsByCountry(input.countryCode)
+            : Object.keys(STORE_LABELS);
+        // When returning all stores, build a CA set for tagging.
+        const caSet = input.countryCode === "CA"
+            ? new Set(storeIds)
+            : input.countryCode === "US"
+                ? new Set()
+                : new Set(storeIdsByCountry("CA"));
+        const stores = storeIds.map((storeId) => ({
+            storeId,
+            storeLabel: storeLabel(storeId) ?? storeId,
+            countryCode: caSet.has(storeId) ? "CA" : "US",
+        }));
+        return { content: [{ type: "text", text: JSON.stringify({ stores }, null, 2) }] };
+    },
+};

package/dist/utils/http.js

@@ -1,12 +1,52 @@
-export async function fetchJson(url, headers) {
-    const res = await fetch(url, {
-        headers: {
-            Accept: "application/json",
-            ...headers,
-        },
-    });
+const RETRY_DELAY_MS = 500;
+function shouldRetry(status) {
+    return status === 429 || status >= 500;
+}
+async function attempt(url, headers) {
+    const res = await fetch(url, { headers: { Accept: "application/json", ...headers } });
     if (!res.ok) {
+        if (shouldRetry(res.status)) {
+            const retryAfter = Number(res.headers.get("Retry-After") ?? 0) * 1000;
+            throw Object.assign(new Error(`HTTP ${res.status} ${res.statusText}: ${url}`), {
+                retryable: true,
+                delay: retryAfter > 0 ? retryAfter : RETRY_DELAY_MS,
+            });
+        }
         throw new Error(`HTTP ${res.status} ${res.statusText}: ${url}`);
     }
     return res.json();
 }
+export async function fetchJson(url, headers = {}) {
+    try {
+        return await attempt(url, headers);
+    }
+    catch (err) {
+        const e = err;
+        if (e.retryable) {
+            await new Promise((r) => setTimeout(r, e.delay ?? RETRY_DELAY_MS));
+            return attempt(url, headers);
+        }
+        // Network-level failures (TypeError from fetch) also get one retry.
+        if (err instanceof TypeError) {
+            await new Promise((r) => setTimeout(r, RETRY_DELAY_MS));
+            return attempt(url, headers);
+        }
+        throw err;
+    }
+}
+/**
+ * Runs tasks with at most `limit` concurrent promises, preserving input order.
+ */
+export async function pMap(items, fn, limit) {
+    const results = new Array(items.length);
+    let next = 0;
+    async function worker() {
+        while (next < items.length) {
+            const i = next++;
+            results[i] = await fn(items[i]);
+        }
+    }
+    const workers = Array.from({ length: Math.min(limit, items.length) }, worker);
+    await Promise.all(workers);
+    return results;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ikea-mcp",
-  "version": "1.3.0",
+  "version": "1.4.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",