@hisaabo/mcp 0.1.0

package/src/tools/reports.ts

@@ -0,0 +1,246 @@
+/**
+ * Business report tools — financial analysis and summaries.
+ *
+ * Tools registered:
+ *   report_daybook         — daily transaction log (invoices + payments + expenses)
+ *   report_outstanding     — outstanding receivables/payables with aging buckets
+ *   report_tax_summary     — tax collected/paid summary by rate
+ *   report_item_sales      — item-wise sales analysis with revenue and quantity
+ *   report_stock_summary   — current stock levels and values
+ *   report_party_statement — party balance statement with transaction history
+ *   report_payment_summary — payment trends by mode and type
+ */
+
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { HisaaboClient } from "../client.js";
+import { wrapTool } from "../lib/errors.js";
+
+export function registerReportTools(server: McpServer, client: HisaaboClient) {
+
+  server.tool(
+    "report_daybook",
+    [
+      "Get the daybook (daily transaction log) for a date range.",
+      "Returns all invoices, payments, and expenses in chronological order with debit/credit columns.",
+      "Use type_filter to narrow to only invoices, payments, or expenses.",
+      "The summary shows totals: sales invoiced, purchases invoiced, payments received, payments made, expenses, and net cash movement.",
+      "Dates are plain date strings (YYYY-MM-DD), not ISO datetime.",
+    ].join(" "),
+    {
+      from_date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/)
+        .describe("Start date in YYYY-MM-DD format, e.g. '2024-04-01'."),
+      to_date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/)
+        .describe("End date in YYYY-MM-DD format, e.g. '2024-04-30'."),
+      type_filter: z.enum(["all", "invoices", "payments", "expenses"]).default("all")
+        .describe("'all' = everything, 'invoices' = only invoice entries, 'payments' = only payment entries, 'expenses' = only expense entries."),
+    },
+    wrapTool(async (input) => {
+      const result = await client.reports.daybook({
+        fromDate: input.from_date,
+        toDate: input.to_date,
+        typeFilter: input.type_filter,
+      });
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(result, null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "report_outstanding",
+    [
+      "Get outstanding receivables (what customers owe you) and/or payables (what you owe suppliers).",
+      "Results are grouped by party with aging buckets: current (0-30 days), 31-60 days, 61-90 days, 90+ days.",
+      "Use type='receivable' for unpaid customer invoices, 'payable' for unpaid supplier bills, 'both' for all.",
+      "as_of_date lets you see outstanding amounts as of a specific past date.",
+    ].join(" "),
+    {
+      type: z.enum(["receivable", "payable", "both"]).default("receivable")
+        .describe("'receivable' = unpaid customer invoices, 'payable' = unpaid supplier bills, 'both' = all outstanding."),
+      as_of_date: z.string().datetime().optional()
+        .describe("Calculate outstanding as of this date (ISO 8601). Defaults to today."),
+    },
+    wrapTool(async (input) => {
+      const result = await client.reports.outstanding({
+        type: input.type,
+        asOfDate: input.as_of_date,
+      });
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(result, null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "report_tax_summary",
+    [
+      "Get a tax summary (GST collected/paid) for a date range, broken down by tax rate.",
+      "Use this to answer 'How much GST did we collect this month?' or 'What is our total ITC (input tax credit)?'",
+      "Results are grouped by tax rate (0%, 5%, 12%, 18%, 28%) showing taxable amount and tax amount.",
+      "type='sales' = output tax (collected from customers), 'purchases' = input tax (ITC from suppliers).",
+    ].join(" "),
+    {
+      from_date: z.string().datetime()
+        .describe("Start date (ISO 8601)."),
+      to_date: z.string().datetime()
+        .describe("End date (ISO 8601)."),
+      type: z.enum(["sales", "purchases", "both"]).default("both")
+        .describe("'sales' = tax on outward supplies, 'purchases' = input tax credit, 'both' = combined."),
+    },
+    wrapTool(async (input) => {
+      const result = await client.reports.taxSummary({
+        fromDate: input.from_date,
+        toDate: input.to_date,
+        type: input.type,
+      });
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(result, null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "report_item_sales",
+    [
+      "Get item-wise sales analysis for a date range.",
+      "Returns revenue, quantity sold, invoice count, and margin for each item.",
+      "Use sort_by to rank items by revenue (default), quantity, number of invoices, or profit margin.",
+      "Use compare_to_previous=true to include comparison with the equivalent prior period.",
+      "Use this to answer 'What were our top-selling products this quarter?' or 'Which items have the best margins?'",
+    ].join(" "),
+    {
+      from_date: z.string().datetime()
+        .describe("Start date (ISO 8601)."),
+      to_date: z.string().datetime()
+        .describe("End date (ISO 8601)."),
+      category: z.string().max(100).optional()
+        .describe("Filter by item category."),
+      item_type: z.enum(["product", "service"]).optional()
+        .describe("'product' for physical goods, 'service' for services."),
+      sort_by: z.enum(["revenue", "quantity", "invoices", "margin"]).default("revenue")
+        .describe("Sort by: 'revenue' (total sales amount), 'quantity' (units sold), 'invoices' (order count), 'margin' (profit)."),
+      compare_to_previous: z.boolean().default(false)
+        .describe("If true, include comparison data from the previous equivalent period."),
+    },
+    wrapTool(async (input) => {
+      const result = await client.reports.itemSales({
+        fromDate: input.from_date,
+        toDate: input.to_date,
+        category: input.category,
+        itemType: input.item_type,
+        sortBy: input.sort_by,
+        compareToPrevious: input.compare_to_previous,
+      });
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(result, null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "report_stock_summary",
+    [
+      "Get current stock levels and values for all inventory items.",
+      "Returns quantity on hand, sale value, and purchase value for each product.",
+      "Use category to filter by product category.",
+      "Set show_zero_stock=true to include items with zero stock (useful for identifying out-of-stock items).",
+      "Use this to answer 'What is the total value of our inventory?' or 'Which products are out of stock?'",
+    ].join(" "),
+    {
+      category: z.string().max(100).optional()
+        .describe("Filter by item category."),
+      show_zero_stock: z.boolean().default(false)
+        .describe("If true, include items with zero stock. Default false (only items with stock > 0)."),
+    },
+    wrapTool(async (input) => {
+      const result = await client.reports.stockSummary({
+        category: input.category,
+        showZeroStock: input.show_zero_stock,
+      });
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(result, null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "report_party_statement",
+    [
+      "Get a party (customer or supplier) account statement showing all transactions and running balance.",
+      "Returns invoices, payments, credit notes, and other entries in chronological order.",
+      "Use this to answer 'Show me the complete transaction history with Customer X' or 'What is the account statement for this supplier?'",
+      "Note: for a quick balance only, use party_get instead.",
+    ].join(" "),
+    {
+      party_id: z.string().uuid()
+        .describe("Party UUID from party_list or party_get."),
+      from_date: z.string().datetime().optional()
+        .describe("Start date for the statement (ISO 8601). Omit for full history."),
+      to_date: z.string().datetime().optional()
+        .describe("End date for the statement (ISO 8601)."),
+    },
+    wrapTool(async (input) => {
+      const result = await client.reports.partyStatement({
+        partyId: input.party_id,
+        fromDate: input.from_date,
+        toDate: input.to_date,
+      });
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(result, null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "report_payment_summary",
+    [
+      "Get a payment summary showing trends by payment mode (cash, UPI, bank, cheque) over a date range.",
+      "Use type='received' for incoming payments from customers, 'made' for payments to suppliers, 'both' for all.",
+      "Filter by bank_account_id to see payments for a specific account.",
+      "Use this to answer 'How much did we receive via UPI this month?' or 'What were our total bank deposits?'",
+    ].join(" "),
+    {
+      from_date: z.string().datetime()
+        .describe("Start date (ISO 8601)."),
+      to_date: z.string().datetime()
+        .describe("End date (ISO 8601)."),
+      type: z.enum(["received", "made", "both"]).default("both")
+        .describe("'received' = payments from customers, 'made' = payments to suppliers, 'both' = all."),
+      bank_account_id: z.string().uuid().optional()
+        .describe("Filter to payments recorded against a specific bank/cash account."),
+    },
+    wrapTool(async (input) => {
+      const result = await client.reports.paymentSummary({
+        fromDate: input.from_date,
+        toDate: input.to_date,
+        type: input.type,
+        bankAccountId: input.bank_account_id,
+      });
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(result, null, 2),
+        }],
+      };
+    })
+  );
+}

package/src/tools/shipment.ts

@@ -0,0 +1,222 @@
+/**
+ * Shipment tools — track outbound and inbound shipments.
+ *
+ * Tools registered:
+ *   shipment_list    — list shipments with filters
+ *   shipment_get     — get full shipment details
+ *   shipment_create  — create a new shipment record
+ *   shipment_update  — update status, tracking, or delivery dates
+ *   shipment_delete  — delete a shipment record
+ */
+
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { HisaaboClient } from "../client.js";
+import { wrapTool } from "../lib/errors.js";
+import { MAX_PAGE_SIZE, withPaginationMeta } from "../lib/pagination.js";
+
+const SHIPMENT_STATUSES = ["pending", "shipped", "in_transit", "delivered", "returned"] as const;
+
+export function registerShipmentTools(server: McpServer, client: HisaaboClient) {
+
+  server.tool(
+    "shipment_list",
+    [
+      "List shipments for the active business with optional filters.",
+      "Use status='pending' to find shipments not yet dispatched, or status='in_transit' for active deliveries.",
+      "Filter by invoice_id to see all shipments for a specific invoice, or by party_id for a specific customer.",
+    ].join(" "),
+    {
+      status: z.enum(SHIPMENT_STATUSES).optional()
+        .describe("Filter by shipment status: 'pending', 'shipped', 'in_transit', 'delivered', or 'returned'."),
+      invoice_id: z.string().uuid().optional()
+        .describe("Filter shipments linked to a specific invoice UUID."),
+      party_id: z.string().uuid().optional()
+        .describe("Filter shipments for a specific customer/party UUID."),
+      page: z.number().int().min(1).default(1)
+        .describe("Page number for pagination."),
+    },
+    wrapTool(async (input) => {
+      const result = await client.shipment.list({
+        status: input.status,
+        invoiceId: input.invoice_id,
+        partyId: input.party_id,
+        page: input.page,
+        limit: MAX_PAGE_SIZE,
+      });
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(withPaginationMeta(result), null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "shipment_get",
+    [
+      "Get full details of a single shipment, including tracking info, carrier, address, and delivery dates.",
+      "If the carrier is one of the 7 pre-configured Indian carriers (Delhivery, BlueDart, DTDC, Ecom Express, India Post, Shadowfax, Xpressbees), a tracking URL is auto-generated.",
+    ].join(" "),
+    {
+      shipment_id: z.string().uuid()
+        .describe("Shipment UUID from shipment_list."),
+    },
+    wrapTool(async (input) => {
+      const shipment = await client.shipment.get(input.shipment_id);
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(shipment, null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "shipment_create",
+    [
+      "Create a new shipment record for an invoice or party.",
+      "For known carriers (Delhivery, BlueDart, DTDC, Ecom Express, India Post, Shadowfax, Xpressbees), providing carrier + tracking_number auto-generates the tracking URL.",
+      "For custom carriers, provide tracking_url manually.",
+      "Cost is the shipping cost charged; weight is the parcel weight in kg.",
+    ].join(" "),
+    {
+      invoice_id: z.string().uuid().optional()
+        .describe("Link this shipment to an invoice UUID. Use shipment_list to avoid duplicates."),
+      party_id: z.string().uuid().optional()
+        .describe("Customer/party UUID for this shipment."),
+      carrier: z.string().max(100).optional()
+        .describe("Carrier name, e.g. 'Delhivery', 'BlueDart', 'DTDC'. Known carriers get auto-tracking URLs."),
+      mode: z.string().max(50).optional()
+        .describe("Delivery mode, e.g. 'surface', 'air', 'express'. Matches business custom shipping methods."),
+      tracking_number: z.string().max(200).optional()
+        .describe("AWB/tracking number from the carrier. Required for auto-generating tracking URL."),
+      tracking_url: z.string().max(500).optional()
+        .describe("Manual tracking URL if carrier is not in the pre-configured list."),
+      cost: z.string().regex(/^\d+(\.\d{1,2})?$/).optional()
+        .describe("Shipping cost as decimal string, e.g. '250.00'. Default '0'."),
+      weight: z.string().regex(/^\d+(\.\d{1,3})?$/).optional()
+        .describe("Parcel weight in kg as decimal string, e.g. '2.500'."),
+      shipping_address: z.string().optional()
+        .describe("Delivery address (street/flat/block)."),
+      shipping_city: z.string().optional()
+        .describe("Delivery city."),
+      shipping_pincode: z.string().optional()
+        .describe("Delivery PIN code."),
+      status: z.enum(SHIPMENT_STATUSES).optional()
+        .describe("Initial status. Default 'pending'. Set 'shipped' if already dispatched."),
+      shipment_date: z.string().datetime().optional()
+        .describe("Date the parcel was dispatched (ISO 8601). Defaults to today."),
+      estimated_delivery: z.string().datetime().optional()
+        .describe("Expected delivery date (ISO 8601)."),
+      notes: z.string().optional()
+        .describe("Internal notes about this shipment."),
+    },
+    wrapTool(async (input) => {
+      const shipment = await client.shipment.create({
+        invoiceId: input.invoice_id,
+        partyId: input.party_id,
+        carrier: input.carrier,
+        mode: input.mode,
+        trackingNumber: input.tracking_number,
+        trackingUrl: input.tracking_url,
+        cost: input.cost,
+        weight: input.weight,
+        shippingAddress: input.shipping_address,
+        shippingCity: input.shipping_city,
+        shippingPincode: input.shipping_pincode,
+        status: input.status,
+        shipmentDate: input.shipment_date,
+        estimatedDelivery: input.estimated_delivery,
+        notes: input.notes,
+      });
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(shipment, null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "shipment_update",
+    [
+      "Update a shipment's status, tracking information, or delivery dates.",
+      "Use this to mark a shipment as shipped (set status='shipped'), in transit, or delivered.",
+      "Setting status='delivered' automatically records the actual delivery date if not provided.",
+      "Update tracking_number to trigger re-generation of the carrier tracking URL.",
+    ].join(" "),
+    {
+      shipment_id: z.string().uuid()
+        .describe("Shipment UUID to update."),
+      carrier: z.string().max(100).optional()
+        .describe("Updated carrier name."),
+      mode: z.string().max(50).optional()
+        .describe("Updated delivery mode."),
+      tracking_number: z.string().max(200).optional()
+        .describe("Updated tracking/AWB number. Re-generates tracking URL for known carriers."),
+      tracking_url: z.string().max(500).optional()
+        .describe("Manual tracking URL override."),
+      cost: z.string().regex(/^\d+(\.\d{1,2})?$/).optional()
+        .describe("Updated shipping cost as decimal string."),
+      weight: z.string().regex(/^\d+(\.\d{1,3})?$/).optional()
+        .describe("Updated parcel weight in kg."),
+      status: z.enum(SHIPMENT_STATUSES).optional()
+        .describe("New status. 'shipped' = dispatched. 'in_transit' = en route. 'delivered' = received. 'returned' = sent back."),
+      shipment_date: z.string().datetime().optional()
+        .describe("Updated dispatch date (ISO 8601)."),
+      estimated_delivery: z.string().datetime().optional()
+        .describe("Updated estimated delivery date (ISO 8601)."),
+      actual_delivery: z.string().datetime().optional()
+        .describe("Actual delivery date (ISO 8601). Auto-set when status becomes 'delivered' if omitted."),
+      notes: z.string().optional()
+        .describe("Updated notes."),
+    },
+    wrapTool(async (input) => {
+      const shipment = await client.shipment.update({
+        id: input.shipment_id,
+        carrier: input.carrier,
+        mode: input.mode,
+        trackingNumber: input.tracking_number,
+        trackingUrl: input.tracking_url,
+        cost: input.cost,
+        weight: input.weight,
+        status: input.status,
+        shipmentDate: input.shipment_date,
+        estimatedDelivery: input.estimated_delivery,
+        actualDelivery: input.actual_delivery,
+        notes: input.notes,
+      });
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(shipment, null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "shipment_delete",
+    [
+      "Delete a shipment record. This is a hard delete — the shipment record is permanently removed.",
+      "Requires admin role. Use with caution; prefer updating status to 'returned' instead of deleting.",
+    ].join(" "),
+    {
+      shipment_id: z.string().uuid()
+        .describe("Shipment UUID to delete."),
+    },
+    wrapTool(async (input) => {
+      const result = await client.shipment.delete(input.shipment_id);
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(result, null, 2),
+        }],
+      };
+    })
+  );
+}

package/src/tools/store.ts

@@ -0,0 +1,177 @@
+/**
+ * Online store tools — manage the business's public storefront.
+ *
+ * Tools registered:
+ *   store_settings        — get current store configuration
+ *   store_update_settings — update store configuration
+ *   store_orders          — list customer orders from the store
+ *   store_order_get       — get full details of a store order
+ *   store_order_update    — update order status (preparing/ready/delivered)
+ */
+
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { HisaaboClient } from "../client.js";
+import { wrapTool } from "../lib/errors.js";
+import { MAX_PAGE_SIZE, withPaginationMeta } from "../lib/pagination.js";
+
+const ORDER_STATUSES = ["pending", "confirmed", "preparing", "ready", "delivered", "cancelled"] as const;
+
+export function registerStoreTools(server: McpServer, client: HisaaboClient) {
+
+  server.tool(
+    "store_settings",
+    [
+      "Get the current online store configuration for the active business.",
+      "Returns whether the store is enabled, the store URL slug, tagline, accent color, minimum order amount, and order prefix.",
+      "If storeEnabled=false, the public store is not accessible.",
+      "The store URL is: https://<storeSlug>.hisaabo.in (when enabled).",
+    ].join(" "),
+    {},
+    wrapTool(async (_input) => {
+      const settings = await client.store.getSettings();
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(settings, null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "store_update_settings",
+    [
+      "Update the online store configuration.",
+      "Enable/disable the store, change the URL slug, tagline, accent color, minimum order amount, etc.",
+      "store_slug must be unique across all businesses and match the pattern: lowercase letters, numbers, and hyphens.",
+      "Setting store_enabled=true activates the public storefront.",
+    ].join(" "),
+    {
+      store_enabled: z.boolean().optional()
+        .describe("Enable (true) or disable (false) the public storefront."),
+      store_slug: z.string().min(3).max(50).regex(/^[a-z0-9][a-z0-9-]*[a-z0-9]$/).optional().nullable()
+        .describe("URL slug for the store, e.g. 'acme-traders'. Must be lowercase alphanumeric with hyphens."),
+      store_tagline: z.string().max(200).optional().nullable()
+        .describe("Short tagline shown on the store homepage, e.g. 'Fresh groceries delivered daily'."),
+      store_accent_color: z.string().regex(/^#[0-9a-fA-F]{6}$/).optional().nullable()
+        .describe("Brand accent color as hex code, e.g. '#FF5722'."),
+      store_min_order_amount: z.string().regex(/^\d+(\.\d{1,2})?$/).optional().nullable()
+        .describe("Minimum order value as decimal string, e.g. '200.00'. Null to remove minimum."),
+      store_delivery_note: z.string().max(500).optional().nullable()
+        .describe("Note shown at checkout about delivery, e.g. 'Delivery within 2 hours in city limits'."),
+      store_whatsapp_number: z.string().max(15).optional().nullable()
+        .describe("WhatsApp number for order notifications (digits only)."),
+      store_allow_negative_stock: z.boolean().optional()
+        .describe("If true, orders can be placed even when stock is zero or negative."),
+      store_order_prefix: z.string().min(1).max(10).optional()
+        .describe("Prefix for store order numbers, e.g. 'ORD'. Default 'ORD'."),
+    },
+    wrapTool(async (input) => {
+      const settings = await client.store.updateSettings({
+        storeEnabled: input.store_enabled,
+        storeSlug: input.store_slug,
+        storeTagline: input.store_tagline,
+        storeAccentColor: input.store_accent_color,
+        storeMinOrderAmount: input.store_min_order_amount,
+        storeDeliveryNote: input.store_delivery_note,
+        storeWhatsappNumber: input.store_whatsapp_number,
+        storeAllowNegativeStock: input.store_allow_negative_stock,
+        storeOrderPrefix: input.store_order_prefix,
+      });
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(settings, null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "store_orders",
+    [
+      "List customer orders placed through the online store.",
+      "Orders progress through statuses: pending → confirmed → preparing → ready → delivered.",
+      "Use status='pending' to find new orders requiring attention.",
+      "Search by customer name, phone number, or order number.",
+    ].join(" "),
+    {
+      status: z.enum(ORDER_STATUSES).optional()
+        .describe("Filter by order status. 'pending' = new orders awaiting confirmation."),
+      from_date: z.string().datetime().optional()
+        .describe("Filter orders placed on or after this date (ISO 8601)."),
+      to_date: z.string().datetime().optional()
+        .describe("Filter orders placed on or before this date (ISO 8601)."),
+      search: z.string().max(200).optional()
+        .describe("Search by customer name, phone number, or order number."),
+      page: z.number().int().min(1).default(1)
+        .describe("Page number for pagination."),
+    },
+    wrapTool(async (input) => {
+      const result = await client.store.listOrders({
+        status: input.status,
+        fromDate: input.from_date,
+        toDate: input.to_date,
+        search: input.search,
+        page: input.page,
+        limit: MAX_PAGE_SIZE,
+      });
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(withPaginationMeta(result), null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "store_order_get",
+    [
+      "Get full details of a single store order, including line items and linked invoice.",
+      "If the order has been confirmed, it will have a linked invoice (invoiceId) in the response.",
+    ].join(" "),
+    {
+      order_id: z.string().uuid()
+        .describe("Store order UUID from store_orders."),
+    },
+    wrapTool(async (input) => {
+      const order = await client.store.getOrder(input.order_id);
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(order, null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "store_order_update",
+    [
+      "Update a confirmed store order's status to 'preparing', 'ready', or 'delivered'.",
+      "Orders must be confirmed first (status='confirmed') before they can be updated.",
+      "Use 'preparing' when the order is being packed, 'ready' when ready for pickup/delivery, 'delivered' when handed to customer.",
+      "To confirm a pending order or cancel an order, use the Hisaabo web app — those actions also update the linked invoice.",
+    ].join(" "),
+    {
+      order_id: z.string().uuid()
+        .describe("Store order UUID."),
+      status: z.enum(["preparing", "ready", "delivered"])
+        .describe("New status: 'preparing' (being packed), 'ready' (ready to deliver), 'delivered' (handed to customer)."),
+    },
+    wrapTool(async (input) => {
+      const result = await client.store.updateOrderStatus({
+        orderId: input.order_id,
+        status: input.status,
+      });
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(result, null, 2),
+        }],
+      };
+    })
+  );
+}