ikea-mcp 1.5.0 → 1.6.0

package/README.md

@@ -2,7 +2,7 @@
 
 Read-only MCP server for IKEA product search and in-store stock lookup.
 
-**Transports:** stdio (Claude Desktop / MCP CLI) · Streamable HTTP (remote clients)  
+**Transports:** stdio (Claude Desktop / MCP CLI) · Streamable HTTP (remote clients)
 **License:** MIT · **No auth required to run locally**
 
 ## Capabilities
@@ -15,10 +15,15 @@ Read-only MCP server for IKEA product search and in-store stock lookup.
 | `check_multi_item_stock` | Check stock for multiple items at one store |
 | `compare_store_stock` | Compare stock across explicit stores or a country catalog |
 | `find_best_store_for_item` | Rank stores by in-stock quantity (optionally filter by country) |
+| `check_cart_availability` | Check whether all items in a shopping list are available at one store |
+| `find_best_store_for_cart` | Rank stores by cart fulfillment across multiple items |
 
 ## MVP limitations
 - Uses unofficial public IKEA APIs — no SLA, may break without notice
-- ~65 confirmed US and Canada stores in catalog (`src/data/stores.ts`); some IDs remain unverified
+- Canada store coverage is complete (15 stores)
+- US coverage is incomplete — 4 small-format stores have unknown API IDs (Queens, Alpharetta, Indianapolis, Arlington)
+- San Francisco small-format store is intentionally excluded (known ID 3136 returns 405)
+- No extra stores are included
 - Cash-and-carry availability only — click-and-collect and home delivery not exposed
 - HTTP transport is open by default — set `API_KEY` env var to require `x-api-key` header on `/mcp`
 - Read-only — no cart, order, or account operations
@@ -215,6 +220,79 @@ Returns `[]` if no store has the item in stock. "All known stores" means the ~65
 
 ---
 
+### `check_cart_availability`
+
+Check whether all items in a shopping list are available in sufficient quantity at a single IKEA store.
+
+**Input**
+| param | type | default | required |
+|---|---|---|---|
+| `storeId` | string | — | yes |
+| `items` | array of `{ itemNo, quantity }` | — | yes |
+| `items[].itemNo` | string | — | yes |
+| `items[].quantity` | number | `1` | no |
+
+**Output**
+```json
+{
+  "storeId": "399",
+  "storeLabel": "399 (Burbank, CA)",
+  "allSufficient": true,
+  "items": [
+    {
+      "itemNo": "20522046",
+      "quantity": 2,
+      "inStock": 42,
+      "sufficient": true,
+      "eligibleForStockNotification": false,
+      "errors": []
+    }
+  ]
+}
+```
+
+`allSufficient` is `true` only when every item has `sufficient: true`. Items not stocked appear with `inStock: null` and a 404 error. An invalid `storeId` (405) propagates to all items.
+
+---
+
+### `find_best_store_for_cart`
+
+Find the best store to buy multiple items in one trip. Ranks stores by how many cart items are available in sufficient quantity, then by total in-stock sum. Optionally filter by `countryCode` or provide explicit `storeIds`.
+
+**Input**
+| param | type | default | required |
+|---|---|---|---|
+| `items` | array of `{ itemNo, quantity }` | — | yes |
+| `items[].itemNo` | string | — | yes |
+| `items[].quantity` | number | `1` | no |
+| `storeIds` | string[] | — | no |
+| `countryCode` | `"US"` \| `"CA"` | — | no |
+| `maxResults` | number | `3` (max 50) | 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.
+
+**Output** — array of stores ranked by cart fulfillment, up to `maxResults`:
+```json
+[
+  {
+    "storeId": "399",
+    "storeLabel": "399 (Burbank, CA)",
+    "allSufficient": true,
+    "fulfilledCount": 3,
+    "totalCount": 3,
+    "items": [
+      { "itemNo": "20522046", "quantity": 2, "inStock": 42, "sufficient": true },
+      { "itemNo": "40477340", "quantity": 1, "inStock": 5, "sufficient": true },
+      { "itemNo": "89268919", "quantity": 1, "inStock": 12, "sufficient": true }
+    ]
+  }
+]
+```
+
+`fulfilledCount` = number of items with `sufficient: true`. Sorting: `fulfilledCount` desc → total stock desc → `storeId` asc. Stores with invalid IDs (405) are excluded.
+
+---
+
 ## Example workflows
 
 ### 1. Search → inspect → check one store
@@ -257,6 +335,25 @@ Returns one entry per item in the same order — items not stocked appear with `
 
 Returns the top 3 stores by in-stock quantity across the mixed US/Canada subset. Omit `storeIds` to search all ~65 known stores.
 
+### 4. Best store for a shopping list
+
+Find which store can fulfill the most items from a multi-item cart:
+
+```json
+{
+  "tool": "find_best_store_for_cart",
+  "items": [
+    { "itemNo": "20522046", "quantity": 2 },
+    { "itemNo": "40477340", "quantity": 1 },
+    { "itemNo": "89268919", "quantity": 1 }
+  ],
+  "countryCode": "CA",
+  "maxResults": 3
+}
+```
+
+Returns the top 3 Canada stores ranked by how many items they can fully supply. Use `check_cart_availability` to then verify exact quantities at the chosen store.
+
 ---
 
 ## Build and test
@@ -378,8 +475,6 @@ Confirmed compatible `storeId` formats:
 - 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`.
-
 An invalid or unsupported `storeId` returns a 405 error in the `errors` array.
 
 ## Limitations

package/dist/schemas/index.js

@@ -76,3 +76,12 @@ export const CheckCartAvailabilityInput = z.object({
         quantity: z.number().int().min(1).max(99).default(1),
     })).min(1).max(20),
 });
+export const FindBestStoreForCartInput = z.object({
+    items: z.array(z.object({
+        itemNo: ItemNo,
+        quantity: z.number().int().min(1).max(99).default(1),
+    })).min(1).max(20),
+    storeIds: z.array(z.string().min(1)).optional(),
+    countryCode: CountryCodeEnum.optional(),
+    maxResults: z.number().int().min(1).max(50).default(3),
+});

package/dist/server.js

@@ -8,7 +8,8 @@ import { getProductDetailsTool } from "./tools/get_product_details.js";
 import { checkMultiItemStockTool } from "./tools/check_multi_item_stock.js";
 import { listStoresTool } from "./tools/list_stores.js";
 import { checkCartAvailabilityTool } from "./tools/check_cart_availability.js";
-const tools = [listStoresTool, searchProductsTool, checkStoreStockTool, compareStoreStockTool, findBestStoreForItemTool, getProductDetailsTool, checkMultiItemStockTool, checkCartAvailabilityTool];
+import { findBestStoreForCartTool } from "./tools/find_best_store_for_cart.js";
+const tools = [listStoresTool, searchProductsTool, checkStoreStockTool, compareStoreStockTool, findBestStoreForItemTool, getProductDetailsTool, checkMultiItemStockTool, checkCartAvailabilityTool, findBestStoreForCartTool];
 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

@@ -40,6 +40,7 @@ export function projectMultiItemStock(result, itemNos) {
                 availableForCashCarry: false,
                 quantity: null,
                 messageType: null,
+                eligibleForStockNotification: null,
                 errors: [{ ...storeError, meaning: "store ID does not exist" }],
             };
         }
@@ -50,6 +51,7 @@ export function projectMultiItemStock(result, itemNos) {
                 availableForCashCarry: a.availableForCashCarry,
                 quantity: a.buyingOption.cashCarry.availability.quantity,
                 messageType: a.buyingOption.cashCarry.availability.probability.thisDay.messageType,
+                eligibleForStockNotification: a.buyingOption.cashCarry.eligibleForStockNotification ?? null,
                 errors: [],
             };
         }
@@ -64,6 +66,7 @@ export function projectMultiItemStock(result, itemNos) {
             availableForCashCarry: false,
             quantity: null,
             messageType: null,
+            eligibleForStockNotification: null,
             errors: annotatedNotStocked,
         };
     });

package/dist/tools/check_multi_item_stock.js

@@ -22,6 +22,7 @@ export const checkMultiItemStockTool = {
             availableForCashCarry: row.availableForCashCarry,
             quantity: row.quantity,
             messageType: row.messageType,
+            eligibleForStockNotification: row.eligibleForStockNotification,
             errors: row.errors,
         }));
         return { content: [{ type: "text", text: JSON.stringify(rows, null, 2) }] };

package/dist/tools/find_best_store_for_cart.js

@@ -0,0 +1,80 @@
+import { FindBestStoreForCartInput } from "../schemas/index.js";
+import { getMultiItemStock, projectMultiItemStock } from "../services/ikea.js";
+import { STORE_LABELS, storeLabel, storeIdsByCountry } from "../data/stores.js";
+import { pMap } from "../utils/http.js";
+export const findBestStoreForCartTool = {
+    name: "find_best_store_for_cart",
+    description: "Find the best store to buy multiple items in one trip. Ranks stores by how many cart items are available in sufficient quantity, then by total in-stock sum. Optionally filter by countryCode ('US' or 'CA'). Explicit storeIds take precedence over countryCode.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            items: {
+                type: "array",
+                items: {
+                    type: "object",
+                    properties: {
+                        itemNo: { type: "string" },
+                        quantity: { type: "number", default: 1 },
+                    },
+                    required: ["itemNo"],
+                },
+                minItems: 1,
+                maxItems: 20,
+            },
+            storeIds: { type: "array", items: { type: "string" } },
+            countryCode: { type: "string", enum: ["US", "CA"] },
+            maxResults: { type: "number", default: 3 },
+        },
+        required: ["items"],
+    },
+    async handler(rawInput) {
+        const input = FindBestStoreForCartInput.parse(rawInput);
+        const targetIds = input.storeIds
+            ?? (input.countryCode ? storeIdsByCountry(input.countryCode) : Object.keys(STORE_LABELS));
+        const itemNos = input.items.map((i) => i.itemNo);
+        const storeResults = await pMap(targetIds, async (storeId) => {
+            const data = await getMultiItemStock(itemNos, storeId);
+            const projected = projectMultiItemStock(data, itemNos);
+            return { storeId, projected };
+        }, 10);
+        const scored = storeResults
+            .filter((r) => {
+            // Exclude stores where a 405 store error hit all items
+            const firstErrors = r.projected[0]?.errors ?? [];
+            return !firstErrors.some((e) => e.code === 405);
+        })
+            .map(({ storeId, projected }) => {
+            const items = input.items.map((item, i) => {
+                const p = projected[i];
+                const inStock = p.quantity;
+                return {
+                    itemNo: item.itemNo,
+                    quantity: item.quantity,
+                    inStock,
+                    sufficient: inStock !== null && inStock >= item.quantity,
+                };
+            });
+            const fulfilledCount = items.filter((i) => i.sufficient).length;
+            const totalStock = items.reduce((sum, i) => sum + (i.inStock ?? 0), 0);
+            return { storeId, fulfilledCount, totalStock, items };
+        });
+        scored.sort((a, b) => {
+            const fc = b.fulfilledCount - a.fulfilledCount;
+            if (fc !== 0)
+                return fc;
+            const ts = b.totalStock - a.totalStock;
+            if (ts !== 0)
+                return ts;
+            return a.storeId.localeCompare(b.storeId);
+        });
+        const ranked = scored.slice(0, input.maxResults).map(({ storeId, fulfilledCount, totalStock: _ts, items }) => ({
+            storeId,
+            storeLabel: storeLabel(storeId) ?? storeId,
+            allSufficient: fulfilledCount === input.items.length,
+            fulfilledCount,
+            totalCount: input.items.length,
+            items,
+        }));
+        return { content: [{ type: "text", text: JSON.stringify(ranked, null, 2) }] };
+    },
+};

package/package.json

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