ikea-mcp 1.2.0 → 1.3.0

package/README.md

@@ -12,14 +12,14 @@ Read-only MCP server for IKEA product search and in-store stock lookup.
 | `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 |
+| `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) |
 
 ## 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
 - 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
+- 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
 
 ## Tools
@@ -123,14 +123,24 @@ On error (e.g. item not carried):
 
 ### `compare_store_stock`
 
-Compare stock for one item across multiple stores.
+Compare stock for one item across multiple stores. Provide explicit `storeIds`, or use `countryCode` to expand to all catalog stores for that country. At least one of `storeIds` or `countryCode` is required.
 
 **Input**
 | param | type | default | required |
 |---|---|---|---|
 | `itemNo` | string | — | yes |
-| `storeIds` | string[] (min 2) | — | yes |
-| `countryCode` | string | `"us"` | no |
+| `storeIds` | string[] (min 2) | — | one of `storeIds`/`countryCode` |
+| `countryCode` | `"US"` \| `"CA"` | — | one of `storeIds`/`countryCode` |
+
+`storeIds` takes precedence — if both are provided, `countryCode` only sets the IKEA API locale.
+
+**Examples**
+```json
+{ "itemNo": "20522046", "storeIds": ["399", "026", "921"] }
+```
+```json
+{ "itemNo": "20522046", "countryCode": "CA" }
+```
 
 **Output** — array of the same shape as `check_store_stock` (one entry per store).
 
@@ -176,6 +186,9 @@ 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 |
+| `countryCode` | `"US"` \| `"CA"` | — | 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 matching stores, up to `maxResults`:
 ```json
@@ -194,6 +207,50 @@ Returns `[]` if no store has the item in stock. "All known stores" means the ~65
 
 ---
 
+## Example workflows
+
+### 1. Search → inspect → check one store
+
+```
+1. search_products       { "query": "BILLY bookcase" }
+   → pick itemNo from results, e.g. "20522046"
+
+2. get_product_details   { "itemNo": "20522046" }
+   → confirms name, price, dimensions before checking stock
+
+3. check_store_stock     { "itemNo": "20522046", "storeId": "399" }
+   → { "availableForCashCarry": true, "quantity": 95, "messageType": "HIGH_IN_STOCK" }
+```
+
+### 2. Shopping list at one store
+
+Check whether several items are available in a single trip:
+
+```json
+{
+  "tool": "check_multi_item_stock",
+  "storeId": "399",
+  "itemNos": ["20522046", "40477340", "89268919"]
+}
+```
+
+Returns one entry per item in the same order — items not stocked appear with `availableForCashCarry: false` and a 404 error.
+
+### 3. Best store from a mixed US + Canada subset
+
+```json
+{
+  "tool": "find_best_store_for_item",
+  "itemNo": "20522046",
+  "storeIds": ["399", "039", "216", "149", "026"],
+  "maxResults": 3
+}
+```
+
+Returns the top 3 stores by in-stock quantity across the mixed US/Canada subset. Omit `storeIds` to search all ~65 known stores.
+
+---
+
 ## Build and test
 
 ```bash
@@ -244,7 +301,11 @@ Endpoints after deploy:
 - `POST /mcp` — MCP Streamable HTTP (requires `Accept: application/json, text/event-stream`)
 - `GET /health` — returns `{"status":"ok"}`
 
-> **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.
+> **Security note:** Set `API_KEY` to protect the `/mcp` endpoint. Requests without a matching `x-api-key` header return 401. `/health` is always open. The server is read-only — no cart, order, or account operations are possible.
+>
+> ```bash
+> API_KEY=your-secret node dist/http.js
+> ```
 
 ## Connecting a local MCP client (stdio)
 
@@ -317,6 +378,6 @@ 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 may hit rate limits.
+- `compare_store_stock` fires all store requests in parallel — large `storeIds` arrays or a full `countryCode` expansion may hit rate limits.
 - 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).

package/dist/data/stores.js

@@ -83,3 +83,11 @@ export const STORE_LABELS = {
 export function storeLabel(storeId) {
     return STORE_LABELS[storeId];
 }
+// Canada labels have a province code before the country: "(City, BC, CA)"
+// US state abbreviations like California "(City, CA)" must not match.
+const CA_LABEL_RE = /,\s+[A-Z]{2},\s+CA\)$/;
+export function storeIdsByCountry(countryCode) {
+    return Object.entries(STORE_LABELS)
+        .filter(([, label]) => countryCode === "CA" ? CA_LABEL_RE.test(label) : !CA_LABEL_RE.test(label))
+        .map(([id]) => id);
+}

package/dist/http.js

@@ -3,6 +3,7 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 import { createServer } from "./server.js";
 const PORT = Number(process.env.PORT ?? 3000);
 const BODY_LIMIT = 1024 * 1024; // 1 MB
+const API_KEY = process.env.API_KEY ?? "";
 function readBody(req) {
     return new Promise((resolve, reject) => {
         let raw = "";
@@ -40,6 +41,10 @@ const httpServer = createHttpServer(async (req, res) => {
             sendJson(res, 200, { status: "ok" });
             return;
         }
+        if (API_KEY && req.headers["x-api-key"] !== API_KEY) {
+            sendJson(res, 401, { error: "unauthorized" });
+            return;
+        }
         if (method === "POST" && url === "/mcp") {
             const body = await readBody(req);
             const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
@@ -60,4 +65,5 @@ const httpServer = createHttpServer(async (req, res) => {
 httpServer.listen(PORT, () => {
     console.error(`ikea-mcp HTTP listening on http://localhost:${PORT}/mcp`);
     console.error(`health: http://localhost:${PORT}/health`);
+    console.error(`auth: ${API_KEY ? "API_KEY required (x-api-key header)" : "open (set API_KEY to enable)"}`);
 });

package/dist/schemas/index.js

@@ -12,13 +12,14 @@ export const CheckStoreStockInput = z.object({
 });
 export const CompareStoreStockInput = z.object({
     itemNo: z.string().min(1),
-    storeIds: z.array(z.string().min(1)).min(2).max(10),
-    countryCode: z.string().length(2).default("us"),
-});
+    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" });
 export const FindBestStoreInput = z.object({
     itemNo: z.string().min(1),
     storeIds: z.array(z.string().min(1)).optional(),
     maxResults: z.number().int().min(1).max(10).default(3),
+    countryCode: z.enum(["US", "CA"]).optional(),
 });
 export const GetProductDetailsInput = z.object({
     itemNo: z.string().min(1),

package/dist/tools/compare_store_stock.js

@@ -1,21 +1,24 @@
 import { CompareStoreStockInput } from "../schemas/index.js";
 import { getStoreStock, projectStock } from "../services/ikea.js";
-import { storeLabel } from "../data/stores.js";
+import { storeLabel, storeIdsByCountry } from "../data/stores.js";
 export const compareStoreStockTool = {
     name: "compare_store_stock",
-    description: "Compare stock availability for an item across multiple IKEA stores.",
+    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.",
     inputSchema: {
         type: "object",
         properties: {
             itemNo: { type: "string" },
             storeIds: { type: "array", items: { type: "string" }, minItems: 2 },
-            countryCode: { type: "string", default: "us" },
+            countryCode: { type: "string", enum: ["US", "CA"] },
         },
-        required: ["itemNo", "storeIds"],
+        required: ["itemNo"],
     },
     async handler(rawInput) {
         const input = CompareStoreStockInput.parse(rawInput);
-        const results = await Promise.all(input.storeIds.map((storeId) => getStoreStock(input.itemNo, storeId, input.countryCode).then((data) => {
+        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,

package/dist/tools/find_best_store_for_item.js

@@ -1,21 +1,23 @@
 import { FindBestStoreInput } from "../schemas/index.js";
 import { getStoreStock, projectStock } from "../services/ikea.js";
-import { STORE_LABELS, storeLabel } from "../data/stores.js";
+import { STORE_LABELS, storeLabel, storeIdsByCountry } from "../data/stores.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.",
+    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.",
     inputSchema: {
         type: "object",
         properties: {
             itemNo: { type: "string" },
             storeIds: { type: "array", items: { type: "string" } },
             maxResults: { type: "number", default: 3 },
+            countryCode: { type: "string", enum: ["US", "CA"] },
         },
         required: ["itemNo"],
     },
     async handler(rawInput) {
         const input = FindBestStoreInput.parse(rawInput);
-        const targetIds = input.storeIds ?? Object.keys(STORE_LABELS);
+        const targetIds = input.storeIds
+            ?? (input.countryCode ? storeIdsByCountry(input.countryCode) : Object.keys(STORE_LABELS));
         const results = await Promise.all(targetIds.map(async (storeId) => {
             const data = await getStoreStock(input.itemNo, storeId, "us");
             const stock = projectStock(data);

package/package.json

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