ikea-mcp 1.1.0 → 1.2.1

package/README.md

@@ -17,9 +17,9 @@ Read-only MCP server for IKEA product search and in-store stock lookup.
 
 ## 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
+- 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
@@ -190,7 +190,51 @@ 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`.
+
+---
+
+## 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.
 
 ---
 
@@ -244,7 +288,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)
 
@@ -302,12 +350,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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ikea-mcp",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Read-only MCP server for IKEA product search and in-store stock lookup. Supports stdio and Streamable HTTP transports.",
   "license": "MIT",
   "type": "module",