ikea-mcp 1.0.0 → 1.1.0

package/README.md

@@ -9,7 +9,9 @@ Read-only MCP server for IKEA product search and in-store stock lookup.
 | Tool | What it does |
 |---|---|
 | `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 |
+| `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 |
 
@@ -54,6 +56,36 @@ Search IKEA products by keyword.
 
 ---
 
+### `get_product_details`
+
+Get details for a single IKEA product by item number.
+
+**Input**
+| param | type | default | required |
+|---|---|---|---|
+| `itemNo` | string | — | yes |
+| `countryCode` | string | `"us"` | no |
+| `langCode` | string | `"en"` | no |
+
+**Output**
+```json
+{
+  "itemNo": "20522046",
+  "name": "BILLY",
+  "typeName": "Bookcase",
+  "salesPrice": { "amount": 79, "currencyCode": "USD" },
+  "pipUrl": "https://www.ikea.com/us/en/p/billy-bookcase-white-20522046/",
+  "designText": "white",
+  "measureText": "31 1/2x11x79 1/2 \"",
+  "ratingValue": 4.6,
+  "ratingCount": 2620
+}
+```
+
+> `shortDescription` and `materials` are not available from the underlying API.
+
+---
+
 ### `check_store_stock`
 
 Check stock at a single IKEA store.
@@ -104,6 +136,36 @@ Compare stock for one item across multiple stores.
 
 ---
 
+### `check_multi_item_stock`
+
+Check cash-and-carry stock for multiple items at a single store in one call.
+
+**Input**
+| param | type | default | required |
+|---|---|---|---|
+| `storeId` | string | — | yes |
+| `itemNos` | string[] (min 1, max 20) | — | yes |
+
+**Output** — array of per-item stock entries in the same order as `itemNos`:
+
+```json
+[
+  {
+    "itemNo": "20522046",
+    "storeId": "399",
+    "storeLabel": "399 (Burbank, CA)",
+    "availableForCashCarry": true,
+    "quantity": 104,
+    "messageType": "HIGH_IN_STOCK",
+    "errors": []
+  }
+]
+```
+
+Items not stocked at that store appear with `availableForCashCarry: false`, `quantity: null`, and a 404 error entry. An invalid `storeId` (405) returns that error on every entry.
+
+---
+
 ### `find_best_store_for_item`
 
 Find stores with the highest in-stock quantity for an item. Queries stores in parallel, excludes invalid stores (405), out-of-stock stores (404), and stores with unknown quantity. Results sorted by quantity descending; ties broken by `storeId` lexicographically.
@@ -148,9 +210,9 @@ node smoke.mjs       # end-to-end stdio smoke test
 
 **stdio** (default — for Claude Desktop / MCP CLI):
 ```bash
-node dist/index.js
-# or during dev:
-npm run dev
+npx ikea-mcp          # after npm install (uses bin entry)
+node dist/index.js    # after local build
+npm run dev           # dev (tsx, no build needed)
 ```
 
 **Streamable HTTP** (for remote / network clients):
@@ -184,7 +246,23 @@ Endpoints after deploy:
 
 > **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.
 
-## Connecting a remote MCP client
+## Connecting a local MCP client (stdio)
+
+**Claude Desktop** (`claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "ikea-mcp": {
+      "command": "npx",
+      "args": ["-y", "ikea-mcp"]
+    }
+  }
+}
+```
+
+---
+
+## Connecting a remote MCP client (HTTP)
 
 Point your MCP client at `https://<your-host>/mcp`.
 

package/dist/index.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createServer } from "./server.js";
 const transport = new StdioServerTransport();

package/dist/schemas/index.js

@@ -20,3 +20,12 @@ export const FindBestStoreInput = z.object({
     storeIds: z.array(z.string().min(1)).optional(),
     maxResults: z.number().int().min(1).max(10).default(3),
 });
+export const GetProductDetailsInput = z.object({
+    itemNo: z.string().min(1),
+    countryCode: z.string().length(2).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),
+});

package/dist/server.js

@@ -4,7 +4,9 @@ import { searchProductsTool } from "./tools/search_products.js";
 import { checkStoreStockTool } from "./tools/check_store_stock.js";
 import { compareStoreStockTool } from "./tools/compare_store_stock.js";
 import { findBestStoreForItemTool } from "./tools/find_best_store_for_item.js";
-const tools = [searchProductsTool, checkStoreStockTool, compareStoreStockTool, findBestStoreForItemTool];
+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];
 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

@@ -19,6 +19,68 @@ export function projectStock(result) {
         errors: annotateStockErrors(result.errors) ?? [],
     };
 }
+export function projectMultiItemStock(result, itemNos) {
+    // Build lookup maps
+    const byItemNo = new Map();
+    for (const a of result.availabilities ?? []) {
+        byItemNo.set(a.itemKey.itemNo, a);
+    }
+    const errorByItemNo = new Map();
+    for (const e of result.errors ?? []) {
+        if (e.details?.itemNo)
+            errorByItemNo.set(e.details.itemNo, e);
+    }
+    // 405 = store doesn't exist — applies to all items
+    const storeError = result.errors?.find((e) => e.code === 405);
+    return itemNos.map((itemNo) => {
+        if (storeError) {
+            return {
+                itemNo,
+                availableForCashCarry: false,
+                quantity: null,
+                messageType: null,
+                errors: [{ ...storeError, meaning: "store ID does not exist" }],
+            };
+        }
+        const a = byItemNo.get(itemNo);
+        if (a) {
+            return {
+                itemNo,
+                availableForCashCarry: a.availableForCashCarry,
+                quantity: a.buyingOption.cashCarry.availability.quantity,
+                messageType: a.buyingOption.cashCarry.availability.probability.thisDay.messageType,
+                errors: [],
+            };
+        }
+        const itemErr = errorByItemNo.get(itemNo);
+        const annotatedNotStocked = [
+            itemErr
+                ? { ...itemErr, meaning: itemErr.code === 404 ? "item not stocked at this store" : "unknown" }
+                : { code: 404, message: "Not found", meaning: "item not stocked at this store" },
+        ];
+        return {
+            itemNo,
+            availableForCashCarry: false,
+            quantity: null,
+            messageType: null,
+            errors: annotatedNotStocked,
+        };
+    });
+}
+// ── Product projection ────────────────────────────────────────────────────────
+export function projectProduct(p) {
+    return {
+        itemNo: p.itemNo,
+        name: p.name,
+        typeName: p.typeName,
+        salesPrice: { amount: p.salesPrice.numeral, currencyCode: p.salesPrice.currencyCode },
+        pipUrl: p.pipUrl,
+        designText: p.validDesignText ?? null,
+        measureText: p.itemMeasureReferenceText ?? null,
+        ratingValue: p.ratingValue,
+        ratingCount: p.ratingCount,
+    };
+}
 // ── Service functions ─────────────────────────────────────────────────────────
 export async function searchProducts(query, countryCode, langCode, size) {
     // Correct endpoint: /search-result-page (not /search — returns 404)
@@ -28,6 +90,22 @@ export async function searchProducts(query, countryCode, langCode, size) {
         "User-Agent": "Mozilla/5.0",
     });
 }
+export async function getProductDetails(itemNo, countryCode, langCode) {
+    const result = await searchProducts(itemNo, countryCode, langCode, 5);
+    const items = result.searchResultPage.products.main.items;
+    const match = items.find((i) => i.product?.itemNo === itemNo || i.product?.itemNoGlobal === itemNo);
+    if (!match) {
+        throw new Error(`item not found: ${itemNo}`);
+    }
+    return projectProduct(match.product);
+}
+export async function getMultiItemStock(itemNos, storeId) {
+    const url = `${STOCK_BASE}/sto/${storeId}` +
+        `?itemNos=${itemNos.map(encodeURIComponent).join(",")}&expand=StoresList,Restocks`;
+    return fetchJson(url, {
+        "X-Client-Id": STOCK_CLIENT_ID,
+    });
+}
 export async function getStoreStock(itemNo, storeId, 
 // countryCode unused: endpoint path is /sto/{storeId}, country is implicit in storeId
 _countryCode) {

package/dist/tools/check_multi_item_stock.js

@@ -0,0 +1,30 @@
+import { CheckMultiItemStockInput } from "../schemas/index.js";
+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.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            storeId: { type: "string" },
+            itemNos: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 20 },
+        },
+        required: ["storeId", "itemNos"],
+    },
+    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 } : {}),
+            availableForCashCarry: row.availableForCashCarry,
+            quantity: row.quantity,
+            messageType: row.messageType,
+            errors: row.errors,
+        }));
+        return { content: [{ type: "text", text: JSON.stringify(rows, null, 2) }] };
+    },
+};

package/dist/tools/get_product_details.js

@@ -0,0 +1,20 @@
+import { GetProductDetailsInput } from "../schemas/index.js";
+import { getProductDetails } from "../services/ikea.js";
+export const getProductDetailsTool = {
+    name: "get_product_details",
+    description: "Get details for a single IKEA product by item number.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            itemNo: { type: "string" },
+            countryCode: { type: "string", default: "us" },
+            langCode: { type: "string", default: "en" },
+        },
+        required: ["itemNo"],
+    },
+    async handler(rawInput) {
+        const input = GetProductDetailsInput.parse(rawInput);
+        const output = await getProductDetails(input.itemNo, input.countryCode, input.langCode);
+        return { content: [{ type: "text", text: JSON.stringify(output, null, 2) }] };
+    },
+};

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "ikea-mcp",
-  "version": "1.0.0",
+  "version": "1.1.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",
   "main": "dist/index.js",
+  "bin": {
+    "ikea-mcp": "dist/index.js"
+  },
   "files": [
     "dist/",
     "Procfile"