Inventory Status

Instructions

Implementation Reference

• src/tools/inventory.ts:21-50 (handler)

  The getInventoryStatus function — main handler that fetches products, calculates out-of-stock/low-stock counts, and returns the inventory status result.

  export async function getInventoryStatus(storeId: string): Promise<InventoryStatusResult> {
    validateUUID(storeId, 'store');
    const store = await storage.getStoreById(storeId);
    if (!store) throw new NotFoundError('Store', storeId);
  
    const products = await storage.getProducts(storeId);
    const activeProducts = products.filter((p) => p.status === 'active');
  
    const outOfStock = activeProducts.filter((p) => p.inventory_quantity <= 0);
    const lowStock = activeProducts.filter((p) => p.inventory_quantity > 0 && p.inventory_quantity <= 10);
    const totalUnits = activeProducts.reduce((sum, p) => sum + Math.max(0, p.inventory_quantity), 0);
  
    return {
      store_id: storeId,
      total_products: activeProducts.length,
      total_units: totalUnits,
      out_of_stock: outOfStock.length,
      low_stock: lowStock.length,
      products: activeProducts
        .sort((a, b) => a.inventory_quantity - b.inventory_quantity)
        .slice(0, 50)
        .map((p) => ({
          id: p.id,
          title: p.title,
          sku: p.sku,
          quantity: p.inventory_quantity,
          status: p.inventory_quantity <= 0 ? 'out_of_stock' : p.inventory_quantity <= 10 ? 'low' : 'ok',
        })),
    };
  }

• src/tools/inventory.ts:6-19 (schema)

  InventoryStatusResult interface defining the return shape (store_id, counts, product array with status).

  export interface InventoryStatusResult {
    store_id: string;
    total_products: number;
    total_units: number;
    out_of_stock: number;
    low_stock: number;
    products: Array<{
      id: string;
      title: string;
      sku: string | null;
      quantity: number;
      status: string;
    }>;
  }

• src/index.ts:127-144 (registration)

  Registration of the 'inventory_status' tool via server.registerTool with input schema, description, and handler that calls getInventoryStatus.

  // ── Tool: inventory_status ────────────────────────────────────────
  server.registerTool(
    'inventory_status',
    {
      title: 'Inventory Status',
      description: 'Snapshot of current stock levels for a connected store. Returns a summary object with total product count, out-of-stock count, low-stock count (≤10 units), plus two arrays: out_of_stock and low_stock — each containing product id, title, sku, quantity, and status. Items are sorted by urgency (lowest quantity first). Read-only and idempotent.',
      inputSchema: z.object({
        store_id: z.string().uuid().describe('UUID of a connected store (returned by store_connect with action="connect" or visible in store_connect with action="list" / the store_overview resource)'),
      }),
      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
    },
    async ({ store_id }) => {
      try {
        const result = await getInventoryStatus(store_id);
        return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
      } catch (e) { return handleToolError(e); }
    }
  );

• src/services/demo-seed.ts:137-142 (helper)

  Demo seed function doc comment mentioning inventory_status as a consumer of the generated store_id.

  /**
   * Create a demo store populated with realistic products, customers, and
   * orders. Safe to call multiple times — each call creates a new demo
   * store with a unique ID. Returns the store_id so callers can plug it
   * straight into inventory_status, customers_segment, order_anomalies,
   * etc. without needing real Shopify or WooCommerce credentials.