@hisaabo/mcp 0.1.0

package/src/tools/invoice.ts

@@ -0,0 +1,256 @@
+/**
+ * Invoice tools — the core of Hisaabo's invoicing workflow.
+ *
+ * Tools registered:
+ *   invoice_list          — search and filter invoices with pagination
+ *   invoice_create        — create a new sale invoice or purchase bill
+ *   invoice_get           — fetch full invoice details (line items, payments, balance)
+ *   invoice_update_status — change invoice status (mark sent, cancel, etc.)
+ *   invoice_pdf_url       — get a URL to download/view the PDF (A4 or thermal)
+ *   invoice_delete        — soft-delete an invoice (admin or seller_manager within 2 hours)
+ */
+
+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 INVOICE_STATUS = ["draft", "unfulfilled", "sent", "paid", "partial", "overdue", "cancelled"] as const;
+const DOCUMENT_TYPE = ["invoice", "quotation", "credit_note", "debit_note", "delivery_challan", "proforma", "sales_return", "purchase_return"] as const;
+
+export function registerInvoiceTools(server: McpServer, client: HisaaboClient) {
+
+  server.tool(
+    "invoice_list",
+    [
+      "List invoices for the active business. Returns up to 25 invoices per page with pagination metadata.",
+      "Use `page` to fetch subsequent pages when `hasMore` is true in the response.",
+      "Example: to find all unpaid invoices from a customer, set status='sent' or status='partial' and party_id=<uuid>.",
+      "To find overdue invoices across all customers, set status='overdue'.",
+    ].join(" "),
+    {
+      type: z.enum(["sale", "purchase"]).optional()
+        .describe("sale = customer invoices, purchase = supplier bills. Omit to return both."),
+      document_type: z.enum(DOCUMENT_TYPE).optional()
+        .describe("Filter by document type (default: invoice). Use 'quotation' for quotes, 'credit_note' for credits."),
+      status: z.enum(INVOICE_STATUS).optional()
+        .describe("Filter by status. Common values: 'sent' (awaiting payment), 'paid', 'overdue', 'draft'."),
+      party_id: z.string().uuid().optional()
+        .describe("UUID of a specific customer or supplier to filter by."),
+      from_date: z.string().datetime().optional()
+        .describe("Start of invoice date range (ISO 8601, e.g. '2024-04-01T00:00:00Z')."),
+      to_date: z.string().datetime().optional()
+        .describe("End of invoice date range (ISO 8601)."),
+      search: z.string().max(200).optional()
+        .describe("Search by invoice number or party name (partial match)."),
+      sort_by: z.enum(["date", "amount", "number"]).optional()
+        .describe("Sort field. Defaults to date descending."),
+      sort_dir: z.enum(["asc", "desc"]).optional()
+        .describe("Sort direction. Defaults to desc."),
+      page: z.number().int().min(1).default(1)
+        .describe("Page number (1-indexed). Use with hasMore in the response to paginate."),
+    },
+    wrapTool(async (input) => {
+      const result = await client.invoice.list({
+        type: input.type,
+        documentType: input.document_type,
+        status: input.status,
+        partyId: input.party_id,
+        fromDate: input.from_date,
+        toDate: input.to_date,
+        search: input.search,
+        sortBy: input.sort_by,
+        sortDir: input.sort_dir,
+        page: input.page,
+        limit: MAX_PAGE_SIZE,
+      });
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(withPaginationMeta(result), null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "invoice_create",
+    [
+      "Create a new invoice or bill for the active business. Returns the created invoice with its assigned invoice number.",
+      "For sale invoices (customer billing), set type='sale'. For purchase bills (supplier invoices), set type='purchase'.",
+      "Each line item requires a description, quantity (decimal string), and unit_price (decimal string, no currency symbol).",
+      "Monetary values are always decimal strings, e.g. '1500.00' not 1500.",
+      "If a line item corresponds to an inventory item, set item_id to link it and update stock automatically.",
+      "Example: { party_id: 'uuid', type: 'sale', line_items: [{ description: 'Web Design', quantity: '1.00', unit_price: '15000.00', tax_percent: '18.00' }] }",
+    ].join(" "),
+    {
+      party_id: z.string().uuid()
+        .describe("UUID of the customer (for sales) or supplier (for purchases). Use party_list to find UUIDs."),
+      type: z.enum(["sale", "purchase"])
+        .describe("'sale' for customer invoices (money coming in), 'purchase' for supplier bills (money going out)."),
+      document_type: z.enum(DOCUMENT_TYPE).optional()
+        .describe("Document type (default: 'invoice'). Use 'quotation' to create a quote instead of an invoice."),
+      line_items: z.array(z.object({
+        description: z.string().min(1).max(500)
+          .describe("Product or service name/description."),
+        quantity: z.string().regex(/^\d+(\.\d{1,3})?$/)
+          .describe("Quantity as decimal string, e.g. '1.000', '7.500', '100'."),
+        unit_price: z.string().regex(/^\d+(\.\d{1,2})?$/)
+          .describe("Price per unit as decimal string, e.g. '250.00', '15000.00'."),
+        tax_percent: z.string().regex(/^\d+(\.\d{1,2})?$/).default("0")
+          .describe("GST/tax rate percentage as decimal string: '0', '5.00', '12.00', '18.00', '28.00'."),
+        discount_percent: z.string().regex(/^\d+(\.\d{1,2})?$/).default("0")
+          .describe("Line-level discount percentage, e.g. '10.00' for 10% off."),
+        item_id: z.string().uuid().optional()
+          .describe("Link to an inventory item UUID to auto-fill price and update stock (optional)."),
+      })).min(1)
+        .describe("At least one line item is required."),
+      invoice_date: z.string().datetime().optional()
+        .describe("Invoice date (ISO 8601). Defaults to today if omitted."),
+      due_date: z.string().datetime().optional()
+        .describe("Payment due date (ISO 8601). Set to enforce credit terms."),
+      notes: z.string().max(2000).optional()
+        .describe("Notes visible on the printed invoice, e.g. bank account details or thank-you message."),
+      terms_and_conditions: z.string().max(2000).optional()
+        .describe("Terms and conditions text printed on the invoice."),
+      invoice_discount: z.string().regex(/^\d+(\.\d{1,2})?$/).optional()
+        .describe("Invoice-level discount. Interpretation depends on invoice_discount_type."),
+      invoice_discount_type: z.enum(["amount", "percent"]).optional()
+        .describe("Whether invoice_discount is a flat amount or percentage (default: 'amount')."),
+      round_off: z.string().regex(/^-?\d+(\.\d{1,2})?$/).optional()
+        .describe("Round-off adjustment for the total, e.g. '0.50' or '-0.25' (typically small). Default '0'."),
+      reference_document_id: z.string().uuid().optional()
+        .describe("UUID of a source document (e.g. quotation UUID when converting quote to invoice)."),
+    },
+    wrapTool(async (input) => {
+      const invoice = await client.invoice.create({
+        partyId: input.party_id,
+        type: input.type,
+        documentType: input.document_type,
+        invoiceDate: input.invoice_date,
+        dueDate: input.due_date,
+        notes: input.notes,
+        termsAndConditions: input.terms_and_conditions,
+        invoiceDiscount: input.invoice_discount,
+        invoiceDiscountType: input.invoice_discount_type,
+        roundOff: input.round_off,
+        referenceDocumentId: input.reference_document_id,
+        lineItems: input.line_items.map((li) => ({
+          description: li.description,
+          quantity: li.quantity,
+          unitPrice: li.unit_price,
+          taxPercent: li.tax_percent,
+          discountPercent: li.discount_percent,
+          itemId: li.item_id,
+        })),
+      });
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(invoice, null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "invoice_get",
+    [
+      "Get the full details of a single invoice, including all line items, payment history, and outstanding balance.",
+      "Use this after invoice_list to get complete details. The 'balanceDue' field shows how much is still owed.",
+      "Payments already applied to this invoice appear in the response.",
+    ].join(" "),
+    {
+      invoice_id: z.string().uuid()
+        .describe("Invoice UUID from invoice_list or invoice_create."),
+    },
+    wrapTool(async (input) => {
+      const invoice = await client.invoice.get(input.invoice_id);
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(invoice, null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "invoice_update_status",
+    [
+      "Change the status of an invoice.",
+      "Typical workflow: create (draft) → mark sent → payment received (handled by payment_create, which auto-updates status to 'paid' or 'partial').",
+      "Use this tool to manually set status to 'sent' (invoice delivered), 'cancelled' (void the invoice), or 'overdue' (mark past due).",
+      "Note: 'paid' and 'partial' status is normally set automatically when payments are recorded — prefer payment_create over forcing 'paid' here.",
+    ].join(" "),
+    {
+      invoice_id: z.string().uuid()
+        .describe("Invoice UUID."),
+      status: z.enum(INVOICE_STATUS)
+        .describe("New status. 'sent' = delivered to customer. 'cancelled' = voided. 'draft' = revert to draft."),
+    },
+    wrapTool(async (input) => {
+      const result = await client.invoice.updateStatus(input.invoice_id, input.status);
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(result, null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "invoice_delete",
+    [
+      "Soft-delete an invoice (marks it as cancelled and hides it from lists).",
+      "Admins can delete any invoice. Seller managers can only delete unpaid invoices created within the last 2 hours.",
+      "Paid invoices cannot be deleted — void them by recording a credit note instead.",
+      "This is a soft delete — the invoice is not physically removed from the database.",
+    ].join(" "),
+    {
+      invoice_id: z.string().uuid()
+        .describe("Invoice UUID to delete."),
+    },
+    wrapTool(async (input) => {
+      const result = await client.invoice.delete(input.invoice_id);
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(result, null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "invoice_pdf_url",
+    [
+      "Get the URL to download or view an invoice as a PDF.",
+      "The URL requires the HISAABO_API_KEY for authentication (pass as a Bearer token).",
+      "Use format='a4' for standard invoices and format='thermal' for 80mm receipt printing.",
+      "The URL is valid for as long as the session token is valid.",
+    ].join(" "),
+    {
+      invoice_id: z.string().uuid()
+        .describe("Invoice UUID."),
+      format: z.enum(["a4", "thermal"]).default("a4")
+        .describe("'a4' for standard A4 invoice PDF, 'thermal' for 80mm thermal receipt."),
+    },
+    wrapTool(async (input) => {
+      // The PDF endpoint is a Hono route, not tRPC — return the URL for the caller to use
+      const url = `${client.apiUrl}/api/invoice/${input.invoice_id}/pdf?format=${input.format}`;
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify({
+            url,
+            note: "Fetch this URL with the Authorization: Bearer <HISAABO_API_KEY> header to download the PDF.",
+            format: input.format,
+          }, null, 2),
+        }],
+      };
+    })
+  );
+}

package/src/tools/item.ts

@@ -0,0 +1,262 @@
+/**
+ * Item (inventory) tools.
+ *
+ * Tools registered:
+ *   item_list          — list/search inventory items
+ *   item_create        — create a new product or service item
+ *   item_get           — get full item details including variants and stock
+ *   item_adjust_stock  — record a stock-in or stock-out adjustment
+ *   item_update        — update an existing item's details or pricing
+ *   item_delete        — permanently delete an item
+ *   item_categories    — list all distinct item categories
+ */
+
+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";
+
+export function registerItemTools(server: McpServer, client: HisaaboClient) {
+
+  server.tool(
+    "item_list",
+    [
+      "List inventory items and services for the active business.",
+      "The 'stockQuantity' field shows current stock. Items with stock below 'lowStockAlert' are low-stock.",
+      "Use low_stock=true to find items that need restocking.",
+      "Use this to find item UUIDs before creating invoices (linking item_id speeds up invoice creation and updates stock).",
+    ].join(" "),
+    {
+      search: z.string().max(200).optional()
+        .describe("Search by item name, SKU, or HSN code."),
+      category: z.string().max(100).optional()
+        .describe("Filter by category."),
+      item_type: z.enum(["product", "service"]).optional()
+        .describe("'product' for physical goods with stock, 'service' for billable services (no stock tracking)."),
+      low_stock: z.boolean().optional()
+        .describe("If true, return only items where current stock is below the low-stock alert threshold."),
+      page: z.number().int().min(1).default(1)
+        .describe("Page number for pagination."),
+    },
+    wrapTool(async (input) => {
+      const result = await client.item.list({
+        search: input.search,
+        category: input.category,
+        itemType: input.item_type,
+        lowStock: input.low_stock,
+        page: input.page,
+        limit: MAX_PAGE_SIZE,
+      });
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(withPaginationMeta(result), null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "item_create",
+    [
+      "Create a new inventory item or service.",
+      "For physical products, set item_type='product' and provide initial stock_quantity.",
+      "For billable services (consulting, installation, etc.), set item_type='service' — stock is not tracked.",
+      "Monetary values (sale_price, purchase_price) are decimal strings without currency symbols: '250.00' not '₹250'.",
+      "Setting low_stock_alert triggers warnings when stock falls below that level.",
+    ].join(" "),
+    {
+      name: z.string().min(1).max(200)
+        .describe("Item name as it should appear on invoices."),
+      item_type: z.enum(["product", "service"]).default("product")
+        .describe("'product' for physical goods, 'service' for services (no stock)."),
+      unit: z.enum(["pcs", "kg", "g", "l", "ml", "m", "cm", "ft", "in", "box", "dozen", "pair", "set", "pkt", "bun", "pouch", "jar", "btl", "bag", "ton", "pack", "pet", "person", "other"]).optional()
+        .describe("Unit of measurement. Default 'pcs'. Use 'kg' for weight, 'l' for liquids, etc."),
+      sale_price: z.string().regex(/^\d+(\.\d{1,2})?$/).optional()
+        .describe("Default selling price per unit as decimal string, e.g. '250.00'."),
+      purchase_price: z.string().regex(/^\d+(\.\d{1,2})?$/).optional()
+        .describe("Default purchase/cost price per unit as decimal string."),
+      tax_percent: z.string().regex(/^\d+(\.\d{1,2})?$/).optional()
+        .describe("Default GST/tax rate percentage, e.g. '18.00'. Default '0'."),
+      stock_quantity: z.string().regex(/^-?\d+(\.\d{1,3})?$/).optional()
+        .describe("Opening stock quantity as decimal string, e.g. '100.000'. Default '0'."),
+      low_stock_alert: z.string().regex(/^\d+(\.\d{1,3})?$/).optional()
+        .describe("Alert threshold: warn when stock falls below this quantity."),
+      hsn: z.string().max(20).optional()
+        .describe("HSN (Harmonized System of Nomenclature) code for GST compliance."),
+      sku: z.string().max(50).optional()
+        .describe("SKU (Stock Keeping Unit) — your internal product code."),
+      description: z.string().max(1000).optional()
+        .describe("Internal description (not shown on invoices)."),
+      category: z.string().max(100).optional()
+        .describe("Category for grouping, e.g. 'Electronics', 'Raw Materials'."),
+    },
+    wrapTool(async (input) => {
+      const item = await client.item.create({
+        name: input.name,
+        itemType: input.item_type,
+        unit: input.unit,
+        salePrice: input.sale_price,
+        purchasePrice: input.purchase_price,
+        taxPercent: input.tax_percent,
+        stockQuantity: input.stock_quantity,
+        lowStockAlert: input.low_stock_alert,
+        hsn: input.hsn,
+        sku: input.sku,
+        description: input.description,
+        category: input.category,
+      });
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(item, null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "item_get",
+    [
+      "Get full details of a single inventory item, including current stock quantity and variant information.",
+      "Use this to check current stock levels or get the full item spec before creating invoices.",
+    ].join(" "),
+    {
+      item_id: z.string().uuid()
+        .describe("Item UUID from item_list."),
+    },
+    wrapTool(async (input) => {
+      const item = await client.item.get(input.item_id);
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(item, null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "item_update",
+    [
+      "Update an existing inventory item's details, pricing, or stock settings.",
+      "Only provide fields you want to change — all other fields remain unchanged.",
+      "Changing sale_price or purchase_price updates the default price for future invoices but does not retroactively change past invoice line items.",
+    ].join(" "),
+    {
+      item_id: z.string().uuid()
+        .describe("Item UUID to update."),
+      name: z.string().min(1).max(200).optional()
+        .describe("Updated item name."),
+      sale_price: z.string().regex(/^\d+(\.\d{1,2})?$/).optional()
+        .describe("Updated selling price per unit as decimal string."),
+      purchase_price: z.string().regex(/^\d+(\.\d{1,2})?$/).optional()
+        .describe("Updated purchase/cost price per unit as decimal string."),
+      tax_percent: z.string().regex(/^\d+(\.\d{1,2})?$/).optional()
+        .describe("Updated GST/tax rate percentage, e.g. '18.00'."),
+      low_stock_alert: z.string().regex(/^\d+(\.\d{1,3})?$/).optional()
+        .describe("Updated low-stock alert threshold."),
+      hsn: z.string().max(20).optional()
+        .describe("Updated HSN code."),
+      sku: z.string().max(50).optional()
+        .describe("Updated SKU."),
+      description: z.string().max(1000).optional()
+        .describe("Updated internal description."),
+      category: z.string().max(100).optional()
+        .describe("Updated category."),
+    },
+    wrapTool(async (input) => {
+      const { item_id, ...fields } = input;
+      const item = await client.item.update(item_id, {
+        name: fields.name,
+        salePrice: fields.sale_price,
+        purchasePrice: fields.purchase_price,
+        taxPercent: fields.tax_percent,
+        lowStockAlert: fields.low_stock_alert,
+        hsn: fields.hsn,
+        sku: fields.sku,
+        description: fields.description,
+        category: fields.category,
+      });
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(item, null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "item_delete",
+    [
+      "Permanently delete an inventory item. Requires admin role.",
+      "Warning: this is a hard delete — it removes the item record and its variants.",
+      "Existing invoice line items that reference this item are not deleted (they retain the data at time of invoicing).",
+      "Only delete if the item was created in error. For discontinued items, consider just setting them inactive.",
+    ].join(" "),
+    {
+      item_id: z.string().uuid()
+        .describe("Item UUID to delete."),
+    },
+    wrapTool(async (input) => {
+      const result = await client.item.delete(input.item_id);
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(result, null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "item_categories",
+    [
+      "Get a list of all distinct item categories used in the business.",
+      "Use this to discover valid category names before filtering item_list by category or creating items.",
+    ].join(" "),
+    {},
+    wrapTool(async (_input) => {
+      const categories = await client.item.categories();
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(categories, null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "item_adjust_stock",
+    [
+      "Record a manual stock adjustment for an inventory item.",
+      "Use a positive adjustment to add stock (e.g. '+50' for stock received) and a negative adjustment to remove stock (e.g. '-5' for damaged goods).",
+      "Every adjustment is recorded in the audit log — always provide a reason.",
+      "Example: to record receiving 100 units from a supplier, set adjustment='+100' and reason='Stock received from Supplier X'.",
+    ].join(" "),
+    {
+      item_id: z.string().uuid()
+        .describe("Item UUID from item_list."),
+      adjustment: z.string().regex(/^[+-]?\d+(\.\d{1,3})?$/)
+        .describe("Signed quantity change as decimal string. '+50' or '50' to add, '-10' to subtract."),
+      reason: z.string().max(500).optional()
+        .describe("Reason for the adjustment, e.g. 'Stock received from supplier', 'Damaged goods write-off'."),
+    },
+    wrapTool(async (input) => {
+      const result = await client.item.adjustStock({
+        itemId: input.item_id,
+        adjustment: input.adjustment,
+        reason: input.reason,
+      });
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(result, null, 2),
+        }],
+      };
+    })
+  );
+}