@hisaabo/mcp 0.1.0

package/src/tools/party.ts

@@ -0,0 +1,266 @@
+/**
+ * Party tools — manage customers and suppliers.
+ *
+ * Tools registered:
+ *   party_list    — search parties with filter/sort options
+ *   party_create  — create a new customer or supplier
+ *   party_get     — get party details including outstanding balance
+ *   party_ledger  — get full transaction ledger for a party
+ *   party_update  — update an existing party's details
+ *   party_delete  — delete a party 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";
+
+export function registerPartyTools(server: McpServer, client: HisaaboClient) {
+
+  server.tool(
+    "party_list",
+    [
+      "List customers and suppliers (parties) for the active business.",
+      "The 'balance' field in each result shows the outstanding amount: positive = they owe you (receivable), negative = you owe them (payable).",
+      "Use filter='outstanding' to find parties with unpaid balances. Use filter='overdue' for parties with overdue invoices.",
+      "Use this tool to find party UUIDs before calling invoice_create or payment_create.",
+    ].join(" "),
+    {
+      type: z.enum(["customer", "supplier"]).optional()
+        .describe("'customer' for buyers, 'supplier' for vendors. Omit to return both."),
+      filter: z.enum(["all", "customer", "supplier", "outstanding", "overdue"]).optional()
+        .describe("'outstanding' = parties with unpaid balance, 'overdue' = parties with overdue invoices."),
+      search: z.string().max(200).optional()
+        .describe("Search by party name, phone, email, or GSTIN (partial match)."),
+      category: z.string().max(100).optional()
+        .describe("Filter by party category tag."),
+      sort_by: z.enum(["name", "balance"]).optional()
+        .describe("Sort by name (alphabetical) or balance (largest first)."),
+      sort_dir: z.enum(["asc", "desc"]).optional()
+        .describe("Sort direction."),
+      page: z.number().int().min(1).default(1)
+        .describe("Page number for pagination."),
+    },
+    wrapTool(async (input) => {
+      const result = await client.party.list({
+        type: input.type,
+        filter: input.filter,
+        search: input.search,
+        category: input.category,
+        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(
+    "party_create",
+    [
+      "Create a new customer or supplier party.",
+      "Minimum required: type ('customer' or 'supplier') and name.",
+      "For GST-registered parties, provide gstin (format: 22AAAAA0000A1Z5). For unregistered, omit it.",
+      "opening_balance sets their starting account balance: positive = they owe you, negative = you owe them.",
+    ].join(" "),
+    {
+      type: z.enum(["customer", "supplier"])
+        .describe("'customer' for buyers/clients, 'supplier' for vendors/sellers."),
+      name: z.string().min(1).max(200)
+        .describe("Full name of the customer or business."),
+      phone: z.string().max(15).optional()
+        .describe("Phone number (digits only, no country code prefix required)."),
+      email: z.string().email().optional()
+        .describe("Email address for sending invoices."),
+      gstin: z.string().regex(/^[0-9]{2}[A-Z]{5}[0-9]{4}[A-Z]{1}[1-9A-Z]{1}Z[0-9A-Z]{1}$/).optional()
+        .describe("GST Identification Number (15 characters), e.g. '22AAAAA0000A1Z5'. Omit if unregistered."),
+      pan: z.string().optional()
+        .describe("PAN (Permanent Account Number), 10 characters."),
+      billing_address: z.string().max(500).optional()
+        .describe("Full billing address."),
+      city: z.string().max(100).optional(),
+      state: z.string().max(100).optional(),
+      pincode: z.string().max(10).optional(),
+      opening_balance: z.string().regex(/^-?\d+(\.\d{1,2})?$/).optional()
+        .describe("Starting balance as decimal string. Positive = they owe you, negative = you owe them. Default '0'."),
+      category: z.string().max(100).optional()
+        .describe("Category tag for grouping parties, e.g. 'retail', 'wholesale', 'government'."),
+      credit_period_days: z.number().int().min(0).max(365).optional()
+        .describe("Number of days before payment is due (e.g. 30 for net-30 terms)."),
+      credit_limit: z.string().regex(/^\d+(\.\d{1,2})?$/).optional()
+        .describe("Maximum credit amount as decimal string."),
+    },
+    wrapTool(async (input) => {
+      const party = await client.party.create({
+        type: input.type,
+        name: input.name,
+        phone: input.phone,
+        email: input.email,
+        gstin: input.gstin,
+        pan: input.pan,
+        billingAddress: input.billing_address,
+        city: input.city,
+        state: input.state,
+        pincode: input.pincode,
+        openingBalance: input.opening_balance,
+        category: input.category,
+        creditPeriodDays: input.credit_period_days,
+        creditLimit: input.credit_limit,
+      });
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(party, null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "party_get",
+    [
+      "Get full details of a single customer or supplier, including their current outstanding balance.",
+      "'balance' shows net amount: positive = they owe you, negative = you owe them.",
+      "Use this to answer questions like 'What does Acme Corp owe us?' or 'What is our balance with Supplier X?'",
+    ].join(" "),
+    {
+      party_id: z.string().uuid()
+        .describe("Party UUID from party_list."),
+    },
+    wrapTool(async (input) => {
+      const party = await client.party.get(input.party_id);
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(party, null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "party_update",
+    [
+      "Update an existing customer or supplier's details.",
+      "Only provide fields you want to change — all other fields remain unchanged.",
+      "Note: 'type' (customer/supplier) cannot be changed after creation.",
+    ].join(" "),
+    {
+      party_id: z.string().uuid()
+        .describe("Party UUID to update."),
+      name: z.string().min(1).max(200).optional()
+        .describe("Updated name."),
+      phone: z.string().max(15).optional()
+        .describe("Updated phone number."),
+      email: z.string().email().optional()
+        .describe("Updated email address."),
+      gstin: z.string().regex(/^[0-9]{2}[A-Z]{5}[0-9]{4}[A-Z]{1}[1-9A-Z]{1}Z[0-9A-Z]{1}$/).optional()
+        .describe("Updated GSTIN (15 characters)."),
+      billing_address: z.string().max(500).optional()
+        .describe("Updated billing address."),
+      shipping_address: z.string().max(500).optional()
+        .describe("Updated shipping address."),
+      city: z.string().max(100).optional()
+        .describe("Updated city."),
+      state: z.string().max(100).optional()
+        .describe("Updated state."),
+      pincode: z.string().max(10).optional()
+        .describe("Updated PIN code."),
+      category: z.string().max(100).optional()
+        .describe("Updated category tag."),
+      credit_period_days: z.number().int().min(0).max(365).optional()
+        .describe("Updated credit period in days."),
+      credit_limit: z.string().regex(/^\d+(\.\d{1,2})?$/).optional()
+        .describe("Updated credit limit as decimal string."),
+      contact_person_name: z.string().max(200).optional()
+        .describe("Updated contact person name."),
+    },
+    wrapTool(async (input) => {
+      const { party_id, ...fields } = input;
+      const party = await client.party.update(party_id, {
+        name: fields.name,
+        phone: fields.phone,
+        email: fields.email,
+        gstin: fields.gstin,
+        billingAddress: fields.billing_address,
+        shippingAddress: fields.shipping_address,
+        city: fields.city,
+        state: fields.state,
+        pincode: fields.pincode,
+        category: fields.category,
+        creditPeriodDays: fields.credit_period_days,
+        creditLimit: fields.credit_limit,
+        contactPersonName: fields.contact_person_name,
+      });
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(party, null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "party_delete",
+    [
+      "Permanently delete a customer or supplier. Requires admin role.",
+      "Warning: this is a hard delete. Associated invoices and payments are not deleted, but the party reference will be broken.",
+      "Consider deactivating or archiving instead — only delete if the party was created in error.",
+    ].join(" "),
+    {
+      party_id: z.string().uuid()
+        .describe("Party UUID to delete."),
+    },
+    wrapTool(async (input) => {
+      const result = await client.party.delete(input.party_id);
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(result, null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "party_ledger",
+    [
+      "Get the full transaction ledger (account statement) for a customer or supplier.",
+      "Shows all invoices, payments, and credit notes in chronological order with running balance.",
+      "Use this to answer 'Show me all transactions with Customer X' or 'What is the payment history for this supplier?'",
+      "The closing_balance field is the current net balance for the party.",
+    ].join(" "),
+    {
+      party_id: z.string().uuid()
+        .describe("Party UUID."),
+      from_date: z.string().datetime().optional()
+        .describe("Start date for ledger entries (ISO 8601). Omit for all-time."),
+      to_date: z.string().datetime().optional()
+        .describe("End date for ledger entries (ISO 8601)."),
+      page: z.number().int().min(1).default(1)
+        .describe("Page number for pagination."),
+    },
+    wrapTool(async (input) => {
+      const ledger = await client.party.ledger(input.party_id, {
+        fromDate: input.from_date,
+        toDate: input.to_date,
+        page: input.page,
+        limit: MAX_PAGE_SIZE,
+      });
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(ledger, null, 2),
+        }],
+      };
+    })
+  );
+}

package/src/tools/payment.ts

@@ -0,0 +1,222 @@
+/**
+ * Payment tools — record and query payments.
+ *
+ * Tools registered:
+ *   payment_create  — record a payment received from a customer or made to a supplier
+ *   payment_list    — list payments with filtering
+ *   payment_get     — get full payment details including linked invoices
+ *   payment_update  — update an existing payment record
+ *   payment_delete  — soft-delete a payment
+ */
+
+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 PAYMENT_MODES = ["cash", "bank", "upi", "cheque", "other"] as const;
+
+export function registerPaymentTools(server: McpServer, client: HisaaboClient) {
+
+  server.tool(
+    "payment_create",
+    [
+      "Record a payment received from a customer or made to a supplier.",
+      "If the payment is for a specific invoice, set invoice_id — the invoice status will update automatically to 'paid' or 'partial'.",
+      "If the payment is not tied to a specific invoice (advance payment or bulk payment), omit invoice_id — it applies to the party's account balance.",
+      "To split a payment across multiple invoices, use the allocations array instead of invoice_id.",
+      "Example: customer paid invoice INV-001 by UPI: { party_id: '<uuid>', amount: '5000.00', mode: 'upi', invoice_id: '<uuid>' }",
+    ].join(" "),
+    {
+      party_id: z.string().uuid()
+        .describe("UUID of the customer (payment received) or supplier (payment made)."),
+      amount: z.string().regex(/^\d+(\.\d{1,2})?$/)
+        .describe("Payment amount as decimal string, e.g. '5000.00'."),
+      mode: z.enum(PAYMENT_MODES)
+        .describe("Payment method: 'cash', 'bank' (bank transfer/NEFT/RTGS), 'upi', 'cheque', or 'other'."),
+      invoice_id: z.string().uuid().optional()
+        .describe("Link this payment to a specific invoice UUID. The invoice status updates automatically. Omit for advance payments."),
+      discount: z.string().regex(/^\d+(\.\d{1,2})?$/).optional()
+        .describe("Discount or write-off amount applied alongside this payment, e.g. '100.00'. Default '0'."),
+      reference_number: z.string().max(100).optional()
+        .describe("Transaction reference, UTR number, cheque number, or any payment identifier."),
+      payment_date: z.string().datetime().optional()
+        .describe("Date the payment was received/made (ISO 8601). Defaults to today."),
+      notes: z.string().max(500).optional()
+        .describe("Internal notes about this payment."),
+      bank_account_id: z.string().uuid().optional()
+        .describe("Bank/cash account UUID to record this transaction against (for cash flow tracking)."),
+      allocations: z.array(z.object({
+        invoice_id: z.string().uuid()
+          .describe("Invoice UUID to allocate part of this payment to."),
+        amount: z.string().regex(/^\d+(\.\d{1,2})?$/)
+          .describe("Amount to allocate to this invoice."),
+      })).optional()
+        .describe("Allocate a single payment across multiple invoices. Use instead of invoice_id when splitting a payment."),
+    },
+    wrapTool(async (input) => {
+      const payment = await client.payment.create({
+        partyId: input.party_id,
+        amount: input.amount,
+        mode: input.mode,
+        invoiceId: input.invoice_id,
+        discount: input.discount,
+        referenceNumber: input.reference_number,
+        paymentDate: input.payment_date,
+        notes: input.notes,
+        bankAccountId: input.bank_account_id,
+        allocations: input.allocations?.map((a) => ({
+          invoiceId: a.invoice_id,
+          amount: a.amount,
+        })),
+      });
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(payment, null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "payment_get",
+    [
+      "Get full details of a single payment, including the invoices it was applied to.",
+      "The 'linkedInvoices' field shows which invoices received allocations from this payment.",
+    ].join(" "),
+    {
+      payment_id: z.string().uuid()
+        .describe("Payment UUID from payment_list."),
+    },
+    wrapTool(async (input) => {
+      const payment = await client.payment.getById(input.payment_id);
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(payment, null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "payment_update",
+    [
+      "Update an existing payment record. This reverses the old allocation and re-applies the new one.",
+      "The linked invoice's amountPaid and status are recalculated automatically.",
+      "Only provide fields you want to change.",
+      "Warning: updating a payment recalculates invoice statuses — ensure the new amount/allocation is correct.",
+    ].join(" "),
+    {
+      payment_id: z.string().uuid()
+        .describe("Payment UUID to update."),
+      amount: z.string().regex(/^\d+(\.\d{1,2})?$/).optional()
+        .describe("New payment amount as decimal string."),
+      mode: z.enum(PAYMENT_MODES).optional()
+        .describe("Updated payment mode."),
+      discount: z.string().regex(/^\d+(\.\d{1,2})?$/).optional()
+        .describe("Updated discount/write-off amount."),
+      reference_number: z.string().max(100).optional().nullable()
+        .describe("Updated transaction reference number."),
+      payment_date: z.string().datetime().optional()
+        .describe("Updated payment date (ISO 8601)."),
+      notes: z.string().max(500).optional().nullable()
+        .describe("Updated internal notes."),
+      bank_account_id: z.string().uuid().optional().nullable()
+        .describe("Updated bank account UUID. Null to unlink from any account."),
+      allocations: z.array(z.object({
+        invoice_id: z.string().uuid()
+          .describe("Invoice UUID to allocate part of this payment to."),
+        amount: z.string().regex(/^\d+(\.\d{1,2})?$/)
+          .describe("Amount to allocate."),
+      })).optional()
+        .describe("Updated invoice allocations. Replaces all existing allocations."),
+    },
+    wrapTool(async (input) => {
+      const payment = await client.payment.update({
+        id: input.payment_id,
+        amount: input.amount,
+        mode: input.mode,
+        discount: input.discount,
+        referenceNumber: input.reference_number,
+        paymentDate: input.payment_date,
+        notes: input.notes,
+        bankAccountId: input.bank_account_id,
+        allocations: input.allocations?.map((a) => ({
+          invoiceId: a.invoice_id,
+          amount: a.amount,
+        })),
+      });
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(payment, null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "payment_delete",
+    [
+      "Soft-delete a payment record. Requires admin role.",
+      "Deleting a payment reverses the invoice allocation: the linked invoice's amountPaid is reduced and its status is recalculated.",
+      "The bank account balance is also reversed if the payment was recorded against an account.",
+    ].join(" "),
+    {
+      payment_id: z.string().uuid()
+        .describe("Payment UUID to delete."),
+    },
+    wrapTool(async (input) => {
+      const result = await client.payment.delete(input.payment_id);
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(result, null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "payment_list",
+    [
+      "List payments for the active business, filtered by party, invoice, or date range.",
+      "Use party_id to see all payments from/to a specific customer or supplier.",
+      "Use invoice_id to see all payments applied to a specific invoice.",
+    ].join(" "),
+    {
+      party_id: z.string().uuid().optional()
+        .describe("Filter by customer or supplier UUID."),
+      invoice_id: z.string().uuid().optional()
+        .describe("Filter payments linked to a specific invoice."),
+      from_date: z.string().datetime().optional()
+        .describe("Start date (ISO 8601)."),
+      to_date: z.string().datetime().optional()
+        .describe("End date (ISO 8601)."),
+      search: z.string().max(200).optional()
+        .describe("Search by payment number, party name, or reference number."),
+      page: z.number().int().min(1).default(1)
+        .describe("Page number for pagination."),
+    },
+    wrapTool(async (input) => {
+      const result = await client.payment.list({
+        partyId: input.party_id,
+        invoiceId: input.invoice_id,
+        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),
+        }],
+      };
+    })
+  );
+}