Inventory Status

Instructions

Implementation Reference

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

  Core handler function for the inventory_status tool. Validates the store UUID, fetches products from storage, filters active products, computes out-of-stock and low-stock (<=10 units) counts, and returns a sorted (by quantity ascending) list of up to 50 products with their status.

  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)

  TypeScript interface defining the return shape of getInventoryStatus: store_id, summary counts, and a products array with per-product stock 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)

  MCP server registration of the 'inventory_status' tool via server.registerTool(). Defines the input schema (store_id UUID), annotations, and the handler that delegates to 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/storage.ts:79-82 (helper)

  Storage helper used by getInventoryStatus to look up the store by UUID, throwing NotFoundError if missing.

  async getStoreById(id: string): Promise<StoreConfig | undefined> {
    const stores = await this.getStores();
    return stores.find((s) => s.id === id);
  }

• src/services/storage.ts:106-109 (helper)

  Storage helper used by getInventoryStatus to fetch all products for a given store_id from the JSON file-based storage.

  async getProducts(storeId: string): Promise<Product[]> {
    const all = await this.readJSON<Product>('products');
    return all.filter((p) => p.store_id === storeId);
  }