ikea-mcp 1.6.2 → 1.10.0

package/dist/tools/check_multi_item_stock.js

@@ -3,7 +3,7 @@ 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.",
+    description: "Check cash-and-carry stock for multiple items at a single IKEA store. inRange: false on a row means the item is not sold at that store or in that country's market; null means the upstream response carried no range information.",
     inputSchema: {
         type: "object",
         properties: {
@@ -20,6 +20,7 @@ export const checkMultiItemStockTool = {
             storeId: input.storeId,
             storeLabel: storeLabel(input.storeId) ?? input.storeId,
             availableForCashCarry: row.availableForCashCarry,
+            inRange: row.inRange,
             quantity: row.quantity,
             messageType: row.messageType,
             eligibleForStockNotification: row.eligibleForStockNotification,

package/dist/tools/check_store_stock.js

@@ -3,13 +3,13 @@ import { getStoreStock, projectStock } from "../services/ikea.js";
 import { storeLabel } from "../data/stores.js";
 export const checkStoreStockTool = {
     name: "check_store_stock",
-    description: "Check stock availability for an item at a specific IKEA store.",
+    description: "Check cash-and-carry stock availability for an item at a specific IKEA store. inRange: false means the item is not sold at that store or in that country's market; null means the upstream response carried no range information.",
     inputSchema: {
         type: "object",
         properties: {
             itemNo: { type: "string" },
             storeId: { type: "string" },
-            countryCode: { type: "string", default: "us" },
+            countryCode: { type: "string", default: "US" },
         },
         required: ["itemNo", "storeId"],
     },

package/dist/tools/compare_store_stock.js

@@ -2,15 +2,16 @@ 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";
+import { COUNTRY_CODES } from "../data/countries.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.",
+    description: "Compare cash-and-carry stock for an item across multiple IKEA stores. Provide explicit storeIds, or use countryCode ('US', 'CA' or 'NO') to compare all catalog stores for that country. inRange: false on a row means the item is not sold at that store or in that country's market; null means the upstream response carried no range information.",
     inputSchema: {
         type: "object",
         properties: {
             itemNo: { type: "string" },
             storeIds: { type: "array", items: { type: "string" }, minItems: 2 },
-            countryCode: { type: "string", enum: ["US", "CA"] },
+            countryCode: { type: "string", enum: [...COUNTRY_CODES] },
             sortBy: { type: "string", enum: ["quantity", "storeId"] },
         },
         required: ["itemNo"],

package/dist/tools/find_best_store_for_cart.js

@@ -1,10 +1,12 @@
 import { FindBestStoreForCartInput } from "../schemas/index.js";
 import { getMultiItemStock, projectMultiItemStock } from "../services/ikea.js";
-import { STORE_LABELS, storeLabel, storeIdsByCountry } from "../data/stores.js";
+import { storeLabel } from "../data/stores.js";
+import { resolveTargets } from "./targets.js";
 import { pMap } from "../utils/http.js";
+import { COUNTRY_CODES } from "../data/countries.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.",
+    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 distance when `near` is given, then by total in-stock sum. Optionally filter by countryCode ('US', 'CA' or 'NO'). Explicit storeIds take precedence over countryCode.",
     inputSchema: {
         type: "object",
         properties: {
@@ -22,15 +24,22 @@ export const findBestStoreForCartTool = {
                 maxItems: 20,
             },
             storeIds: { type: "array", items: { type: "string" } },
-            countryCode: { type: "string", enum: ["US", "CA"] },
+            countryCode: { type: "string", enum: [...COUNTRY_CODES] },
+            near: {
+                type: "object",
+                description: "Search only the stores closest to this point (the user's city or address). Use this instead of countryCode when you know where the user is.",
+                properties: { latitude: { type: "number" }, longitude: { type: "number" } },
+                required: ["latitude", "longitude"],
+            },
+            nearestStores: { type: "number", default: 5, description: "With near: how many of the closest stores to search (1–20)." },
+            maxDistanceKm: { type: "number", description: "Leave out stores farther than this." },
             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 { storeIds: targetIds, distances } = resolveTargets(input);
         const itemNos = input.items.map((i) => i.itemNo);
         const storeResults = await pMap(targetIds, async (storeId) => {
             const data = await getMultiItemStock(itemNos, storeId);
@@ -62,6 +71,10 @@ export const findBestStoreForCartTool = {
             const fc = b.fulfilledCount - a.fulfilledCount;
             if (fc !== 0)
                 return fc;
+            // With `near`, among stores that fill the cart equally well the closest comes first.
+            const closer = (distances.get(a.storeId) ?? 0) - (distances.get(b.storeId) ?? 0);
+            if (closer !== 0)
+                return closer;
             const ts = b.totalStock - a.totalStock;
             if (ts !== 0)
                 return ts;
@@ -73,6 +86,7 @@ export const findBestStoreForCartTool = {
             allSufficient: fulfilledCount === input.items.length,
             fulfilledCount,
             totalCount: input.items.length,
+            ...(distances.has(storeId) ? { distanceKm: distances.get(storeId) } : {}),
             items,
         }));
         return { content: [{ type: "text", text: JSON.stringify(ranked, null, 2) }] };

package/dist/tools/find_best_store_for_item.js

@@ -1,25 +1,34 @@
 import { FindBestStoreInput } from "../schemas/index.js";
 import { getStoreStock, projectStock } from "../services/ikea.js";
-import { STORE_LABELS, storeLabel, storeIdsByCountry } from "../data/stores.js";
+import { storeLabel } from "../data/stores.js";
+import { resolveTargets } from "./targets.js";
 import { pMap } from "../utils/http.js";
+import { COUNTRY_CODES } from "../data/countries.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.",
+    description: "Find stores with the highest in-stock quantity for an item. Returns up to maxResults stores sorted by quantity descending, or nearest first when `near` is given. Optionally filter by countryCode ('US', 'CA' or 'NO'). 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"] },
+            countryCode: { type: "string", enum: [...COUNTRY_CODES] },
+            near: {
+                type: "object",
+                description: "Search only the stores closest to this point (the user's city or address). Use this instead of countryCode when you know where the user is.",
+                properties: { latitude: { type: "number" }, longitude: { type: "number" } },
+                required: ["latitude", "longitude"],
+            },
+            nearestStores: { type: "number", default: 5, description: "With near: how many of the closest stores to search (1–20)." },
+            maxDistanceKm: { type: "number", description: "Leave out stores farther than this." },
             minQuantity: { type: "number" },
         },
         required: ["itemNo"],
     },
     async handler(rawInput) {
         const input = FindBestStoreInput.parse(rawInput);
-        const targetIds = input.storeIds
-            ?? (input.countryCode ? storeIdsByCountry(input.countryCode) : Object.keys(STORE_LABELS));
+        const { storeIds: targetIds, distances } = resolveTargets(input);
         const results = await pMap(targetIds, async (storeId) => {
             const data = await getStoreStock(input.itemNo, storeId, "us");
             const stock = projectStock(data);
@@ -30,6 +39,10 @@ export const findBestStoreForItemTool = {
             r.stock.quantity !== null &&
             (input.minQuantity === undefined || r.stock.quantity >= input.minQuantity))
             .sort((a, b) => {
+            // With `near`, any store that has the item is good enough, so the closest comes first.
+            const closer = (distances.get(a.storeId) ?? 0) - (distances.get(b.storeId) ?? 0);
+            if (closer !== 0)
+                return closer;
             const diff = (b.stock.quantity ?? 0) - (a.stock.quantity ?? 0);
             return diff !== 0 ? diff : a.storeId.localeCompare(b.storeId);
         })
@@ -40,6 +53,7 @@ export const findBestStoreForItemTool = {
             availableForCashCarry: stock.availableForCashCarry,
             quantity: stock.quantity,
             messageType: stock.messageType,
+            ...(distances.has(storeId) ? { distanceKm: distances.get(storeId) } : {}),
         }));
         return { content: [{ type: "text", text: JSON.stringify(ranked, null, 2) }] };
     },

package/dist/tools/find_nearby_stores.js

@@ -0,0 +1,29 @@
+import { FindNearbyStoresInput } from "../schemas/index.js";
+import { nearestStores } from "../data/geo.js";
+import { storeLabel } from "../data/stores.js";
+import { COUNTRY_CODES } from "../data/countries.js";
+export const findNearbyStoresTool = {
+    name: "find_nearby_stores",
+    description: "Find the IKEA stores closest to a place. Pass the latitude and longitude of the user's city or address (an approximate city-centre coordinate is fine). Returns stores nearest first with the straight-line distance in km. Use the returned storeId values with the stock tools, or pass the same coordinates as `near` to find_best_store_for_item / find_best_store_for_cart.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            latitude: { type: "number", minimum: -90, maximum: 90, description: "Latitude in decimal degrees, e.g. 43.65 for Toronto." },
+            longitude: { type: "number", minimum: -180, maximum: 180, description: "Longitude in decimal degrees, e.g. -79.38 for Toronto." },
+            countryCode: { type: "string", enum: [...COUNTRY_CODES], description: "Only return stores in this country." },
+            maxResults: { type: "number", default: 5, description: "How many stores to return (1–20)." },
+            maxDistanceKm: { type: "number", description: "Leave out stores farther than this." },
+        },
+        required: ["latitude", "longitude"],
+    },
+    async handler(rawInput) {
+        const input = FindNearbyStoresInput.parse(rawInput);
+        const stores = nearestStores({ lat: input.latitude, lon: input.longitude }, { countryCode: input.countryCode, limit: input.maxResults, maxDistanceKm: input.maxDistanceKm }).map((s) => ({
+            storeId: s.storeId,
+            storeLabel: storeLabel(s.storeId) ?? s.storeId,
+            countryCode: s.countryCode,
+            distanceKm: s.distanceKm,
+        }));
+        return { content: [{ type: "text", text: JSON.stringify({ stores }, null, 2) }] };
+    },
+};

package/dist/tools/get_product_details.js

@@ -7,8 +7,8 @@ export const getProductDetailsTool = {
         type: "object",
         properties: {
             itemNo: { type: "string" },
-            countryCode: { type: "string", default: "us" },
-            langCode: { type: "string", default: "en" },
+            countryCode: { type: "string", default: "US", description: "Two-letter country code of the IKEA market to price and localise the product in, e.g. US, CA, NO." },
+            langCode: { type: "string", description: "Two-letter language code. Defaults to the country's language: en for US and CA, no for NO." },
         },
         required: ["itemNo"],
     },

package/dist/tools/list_stores.js

@@ -1,29 +1,24 @@
 import { ListStoresInput } from "../schemas/index.js";
-import { STORE_LABELS, storeLabel, storeIdsByCountry } from "../data/stores.js";
+import { STORES, storeLabelFor } from "../data/stores.js";
+import { COUNTRY_CODES } from "../data/countries.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.",
+    description: "List known IKEA store IDs and display names. Use countryCode ('US', 'CA' or 'NO') to filter by country, or omit to return all stores. Use the returned storeId values with the stock tools.",
     inputSchema: {
         type: "object",
         properties: {
-            countryCode: { type: "string", enum: ["US", "CA"] },
+            countryCode: { type: "string", enum: [...COUNTRY_CODES] },
         },
     },
     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",
+        const records = input.countryCode
+            ? STORES.filter((s) => s.countryCode === input.countryCode)
+            : STORES;
+        const stores = records.map((s) => ({
+            storeId: s.storeId,
+            storeLabel: storeLabelFor(s),
+            countryCode: s.countryCode,
         }));
         return { content: [{ type: "text", text: JSON.stringify({ stores }, null, 2) }] };
     },

package/dist/tools/search_products.js

@@ -7,8 +7,8 @@ export const searchProductsTool = {
         type: "object",
         properties: {
             query: { type: "string" },
-            countryCode: { type: "string", default: "us" },
-            langCode: { type: "string", default: "en" },
+            countryCode: { type: "string", default: "US", description: "Two-letter country code of the IKEA market to search, e.g. US, CA, NO." },
+            langCode: { type: "string", description: "Two-letter language code. Defaults to the country's language: en for US and CA, no for NO." },
             size: { type: "number", default: 10 },
         },
         required: ["query"],

package/dist/tools/targets.js

@@ -0,0 +1,16 @@
+import { nearestStores } from "../data/geo.js";
+import { allStoreIds, storeIdsByCountry } from "../data/stores.js";
+/**
+ * The stores a ranking tool should search. Explicit storeIds win; then the stores closest to `near`
+ * (within countryCode when both are given; with `near`, `maxDistanceKm` leaves out stores farther than that,
+ * and it is ignored with explicit storeIds); then every store in countryCode; then the whole catalog.
+ */
+export function resolveTargets(input) {
+    if (input.storeIds)
+        return { storeIds: input.storeIds, distances: new Map() };
+    if (input.near) {
+        const nearest = nearestStores({ lat: input.near.latitude, lon: input.near.longitude }, { countryCode: input.countryCode, limit: input.nearestStores, maxDistanceKm: input.maxDistanceKm });
+        return { storeIds: nearest.map((s) => s.storeId), distances: new Map(nearest.map((s) => [s.storeId, s.distanceKm])) };
+    }
+    return { storeIds: input.countryCode ? storeIdsByCountry(input.countryCode) : allStoreIds(), distances: new Map() };
+}

package/dist/utils/errors.js

@@ -0,0 +1,27 @@
+import { ZodError } from "zod";
+function describeIssues(err) {
+    return err.issues
+        .map((issue) => {
+        const where = issue.path.length ? issue.path.join(".") : "input";
+        return `${where}: ${issue.message}`;
+    })
+        .join("; ");
+}
+/**
+ * Turns anything a tool handler threw into a tool result with isError set.
+ * Invalid input names the field so the model can correct the call; anything else is reported as an upstream failure.
+ */
+export function toToolError(toolName, err) {
+    let text;
+    if (err instanceof ZodError) {
+        text = `Invalid input for ${toolName}: ${describeIssues(err)}. Fix the arguments and call the tool again.`;
+    }
+    else if (err instanceof Error && (err.name === "TimeoutError" || err.name === "AbortError")) {
+        text = `${toolName} failed: the IKEA API did not answer in time. Try again shortly.`;
+    }
+    else {
+        const message = err instanceof Error ? err.message : String(err);
+        text = `${toolName} failed: ${message}. The IKEA API may be unavailable or may have changed; try again shortly.`;
+    }
+    return { isError: true, content: [{ type: "text", text }] };
+}

package/dist/utils/http.js

@@ -1,9 +1,14 @@
 const RETRY_DELAY_MS = 500;
+/** No single request to IKEA may hang a tool call: give up after this long. */
+export const REQUEST_TIMEOUT_MS = 10_000;
 function shouldRetry(status) {
     return status === 429 || status >= 500;
 }
 async function attempt(url, headers) {
-    const res = await fetch(url, { headers: { Accept: "application/json", ...headers } });
+    const res = await fetch(url, {
+        headers: { Accept: "application/json", ...headers },
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
     if (!res.ok) {
         if (shouldRetry(res.status)) {
             const retryAfter = Number(res.headers.get("Retry-After") ?? 0) * 1000;

package/package.json

@@ -1,53 +1,59 @@
-{
-  "name": "ikea-mcp",
-  "version": "1.6.2",
-  "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"
-  ],
-  "keywords": [
-    "mcp",
-    "ikea",
-    "model-context-protocol",
-    "stock",
-    "inventory"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/taejin5314/ikea-mcp.git"
-  },
-  "homepage": "https://github.com/taejin5314/ikea-mcp#readme",
-  "bugs": {
-    "url": "https://github.com/taejin5314/ikea-mcp/issues"
-  },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsx src/index.ts",
-    "dev:http": "tsx src/http.ts",
-    "start": "node dist/index.js",
-    "start:http": "node dist/http.js",
-    "smoke": "node smoke.mjs",
-    "smoke:http": "node smoke-http.mjs",
-    "test": "node --import tsx/esm --test test/unit.test.ts",
-    "typecheck": "tsc -p tsconfig.test.json"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "zod": "^3.22.0"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "tsx": "^4.0.0",
-    "typescript": "^5.0.0"
-  }
-}
+{
+  "name": "ikea-mcp",
+  "version": "1.10.0",
+  "description": "MCP server for IKEA product search and live in-store stock in the US, Canada and Norway: find the nearest store that has an item or a whole shopping list. Read-only, stdio and Streamable HTTP.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "ikea-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "Procfile",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "mcp",
+    "ikea",
+    "model-context-protocol",
+    "stock",
+    "inventory",
+    "mcp-server",
+    "claude",
+    "store-locator",
+    "availability"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/taejin5314/ikea-mcp.git"
+  },
+  "homepage": "https://github.com/taejin5314/ikea-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/taejin5314/ikea-mcp/issues"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "dev:http": "tsx src/http.ts",
+    "start": "node dist/index.js",
+    "start:http": "node dist/http.js",
+    "smoke": "node smoke.mjs",
+    "smoke:http": "node smoke-http.mjs",
+    "test": "node --import tsx/esm --test test/unit.test.ts",
+    "typecheck": "tsc -p tsconfig.test.json",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  }
+}