@hisaabo/mcp 0.1.0

package/src/index.ts

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+/**
+ * Hisaabo MCP Server
+ *
+ * Exposes Hisaabo invoicing data and operations as MCP tools and resources.
+ * Designed for use with Claude Desktop, OpenClaw, and any MCP-compatible host.
+ *
+ * Required environment variables:
+ *   HISAABO_API_URL     — Base URL of the Hisaabo API (default: http://localhost:3000)
+ *   HISAABO_API_KEY       — Session ID obtained from `hisaabo login` (Bearer token)
+ *   HISAABO_TENANT_ID   — Tenant (organization) UUID
+ *   HISAABO_BUSINESS_ID — Active business UUID
+ *
+ * Usage in Claude Desktop claude_desktop_config.json:
+ *   {
+ *     "mcpServers": {
+ *       "hisaabo": {
+ *         "command": "npx",
+ *         "args": ["@hisaabo/mcp"],
+ *         "env": {
+ *           "HISAABO_API_URL": "http://localhost:3000",
+ *           "HISAABO_API_KEY": "<session-id-from-hisaabo-login>",
+ *           "HISAABO_TENANT_ID": "<tenant-uuid>",
+ *           "HISAABO_BUSINESS_ID": "<business-uuid>"
+ *         }
+ *       }
+ *     }
+ *   }
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { HisaaboClient } from "./client.js";
+import { registerTools } from "./server.js";
+
+function requireEnv(name: string): string {
+  const val = process.env[name];
+  if (!val) {
+    process.stderr.write(
+      `[hisaabo-mcp] Error: Required environment variable "${name}" is not set.\n` +
+      `[hisaabo-mcp] Run "hisaabo whoami --json" to get all required values.\n`
+    );
+    process.exit(1);
+  }
+  return val;
+}
+
+const config = {
+  apiUrl: process.env.HISAABO_API_URL ?? "http://localhost:3000",
+  token: requireEnv("HISAABO_API_KEY"),
+  tenantId: requireEnv("HISAABO_TENANT_ID"),
+  businessId: requireEnv("HISAABO_BUSINESS_ID"),
+};
+
+const client = new HisaaboClient(config);
+const server = new McpServer({
+  name: "hisaabo",
+  version: "0.1.0",
+});
+
+registerTools(server, client);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/lib/errors.ts

@@ -0,0 +1,49 @@
+/**
+ * MCP tool error normalization.
+ *
+ * All tool handlers are wrapped with wrapTool() to ensure errors are returned
+ * as structured MCP content rather than thrown exceptions. The MCP SDK itself
+ * handles uncaught exceptions, but we want to give the AI agent a useful, plain
+ * English message rather than a raw JSON error envelope.
+ */
+
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { HisaaboApiError, formatHisaaboError, type HisaaboError } from "../client.js";
+
+type ToolHandler<T> = (input: T) => Promise<CallToolResult>;
+
+/**
+ * Wrap a tool handler in error normalization.
+ *
+ * - Successful calls pass through unchanged.
+ * - HisaaboApiError is translated to a structured, agent-readable error message.
+ * - Any other thrown error is collapsed to a safe api_error (no stack traces exposed).
+ */
+export function wrapTool<T>(handler: ToolHandler<T>): ToolHandler<T> {
+  return async (input: T): Promise<CallToolResult> => {
+    try {
+      return await handler(input);
+    } catch (err) {
+      const hisaaboErr = toHisaaboError(err);
+      return {
+        isError: true,
+        content: [
+          {
+            type: "text" as const,
+            text: formatHisaaboError(hisaaboErr),
+          },
+        ],
+      };
+    }
+  };
+}
+
+function toHisaaboError(err: unknown): HisaaboError {
+  if (err instanceof HisaaboApiError) {
+    return err.hisaaboError;
+  }
+  // Network or unexpected error — collapse to api_error, never surface stack traces
+  const message =
+    err instanceof Error ? err.message : "An unexpected error occurred. Check server logs.";
+  return { code: "api_error", message };
+}

package/src/lib/pagination.ts

@@ -0,0 +1,35 @@
+/**
+ * Pagination helpers for MCP tool responses.
+ *
+ * AI agents process the full result set returned by a tool call, so list tools
+ * enforce a hard cap per page to keep context window usage bounded. See ADR-005.
+ *
+ * The default cap is 25 records. Operators may raise it (max 50) via the
+ * HISAABO_MCP_PAGE_SIZE environment variable.
+ */
+
+const envCap = parseInt(process.env.HISAABO_MCP_PAGE_SIZE ?? "25", 10);
+
+/** Maximum records per tool call response. */
+export const MAX_PAGE_SIZE = Math.min(Math.max(isNaN(envCap) ? 25 : envCap, 1), 50);
+
+/**
+ * Add pagination metadata to a list result so agents know whether to
+ * call the tool again with a higher page number.
+ */
+export function withPaginationMeta<T>(
+  result: { data: T[]; total: number; page: number; limit: number },
+): { data: T[]; total: number; page: number; limit: number; hasMore: boolean } {
+  return {
+    ...result,
+    hasMore: result.total > result.page * result.limit,
+  };
+}
+
+/**
+ * Build the input for a list call with the enforced page size.
+ * Agents pass page (1-indexed); this returns the full input object.
+ */
+export function pageInput(page: number): { page: number; limit: number } {
+  return { page, limit: MAX_PAGE_SIZE };
+}

package/src/resources/index.ts

@@ -0,0 +1,211 @@
+/**
+ * MCP Resource registrations.
+ *
+ * Resources are read-only data snapshots that MCP hosts (e.g. Claude Desktop)
+ * can load into the agent's context window without the agent explicitly calling
+ * a tool. They are fetched on demand, not pushed proactively.
+ *
+ * Resources registered:
+ *   business://current          — Active business profile (name, GSTIN, currency, etc.)
+ *   parties://customers         — Top 50 customers by name (for quick lookup)
+ *   parties://suppliers         — Top 50 suppliers by name
+ *   items://inventory           — All inventory items with current stock
+ *   invoices://recent           — Last 10 invoices (quick status overview)
+ *   dashboard://summary         — Current FY financial summary
+ *   bank://accounts             — Bank account list with current balances
+ *   shipments://recent          — Last 10 shipments
+ *   targets://active            — Active sales targets with progress
+ *
+ * Cache guidance:
+ *   - business://current: long cache — changes rarely
+ *   - parties/*: medium cache — new parties added occasionally
+ *   - items://inventory: short cache — stock changes with every invoice
+ *   - invoices://recent: short cache — changes with every new invoice
+ *   - dashboard://summary: no-cache — changes with every transaction
+ *   - bank://accounts: short cache — balance changes with every payment
+ *   - shipments://recent: short cache — changes with every new shipment
+ *   - targets://active: medium cache — progress changes with every sale
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { HisaaboClient } from "../client.js";
+
+export function registerResources(server: McpServer, client: HisaaboClient) {
+
+  // ── business://current ──────────────────────────────────────────────────
+  // Active business profile. Load this to understand the business context:
+  // name, GSTIN, GST registration type, currency, financial year start, etc.
+  server.resource(
+    "business_current",
+    "business://current",
+    async (_uri) => {
+      const biz = await client.business.get();
+      return {
+        contents: [{
+          uri: "business://current",
+          text: JSON.stringify(biz, null, 2),
+          mimeType: "application/json",
+        }],
+      };
+    }
+  );
+
+  // ── parties://customers ─────────────────────────────────────────────────
+  // Top 50 customers sorted by name. Includes id, name, phone, balance.
+  // Useful for seeding context before invoice creation or payment recording.
+  server.resource(
+    "parties_customers",
+    "parties://customers",
+    async (_uri) => {
+      const result = await client.party.list({
+        type: "customer",
+        sortBy: "name",
+        sortDir: "asc",
+        limit: 50,
+        page: 1,
+      });
+      return {
+        contents: [{
+          uri: "parties://customers",
+          text: JSON.stringify(result.data, null, 2),
+          mimeType: "application/json",
+        }],
+      };
+    }
+  );
+
+  // ── parties://suppliers ─────────────────────────────────────────────────
+  // Top 50 suppliers sorted by name. Includes id, name, phone, balance.
+  server.resource(
+    "parties_suppliers",
+    "parties://suppliers",
+    async (_uri) => {
+      const result = await client.party.list({
+        type: "supplier",
+        sortBy: "name",
+        sortDir: "asc",
+        limit: 50,
+        page: 1,
+      });
+      return {
+        contents: [{
+          uri: "parties://suppliers",
+          text: JSON.stringify(result.data, null, 2),
+          mimeType: "application/json",
+        }],
+      };
+    }
+  );
+
+  // ── items://inventory ───────────────────────────────────────────────────
+  // Inventory items with current stock. Load this to check what products are
+  // available, their prices, and which are low on stock.
+  server.resource(
+    "items_inventory",
+    "items://inventory",
+    async (_uri) => {
+      // Fetch up to 100 items — for context seeding, not exhaustive listing
+      const result = await client.item.list({ limit: 100, page: 1 });
+      return {
+        contents: [{
+          uri: "items://inventory",
+          text: JSON.stringify(result.data, null, 2),
+          mimeType: "application/json",
+        }],
+      };
+    }
+  );
+
+  // ── invoices://recent ───────────────────────────────────────────────────
+  // The 10 most recent sale invoices. Load this for a quick status overview.
+  server.resource(
+    "invoices_recent",
+    "invoices://recent",
+    async (_uri) => {
+      const result = await client.invoice.list({
+        type: "sale",
+        limit: 10,
+        page: 1,
+      });
+      return {
+        contents: [{
+          uri: "invoices://recent",
+          text: JSON.stringify(result.data, null, 2),
+          mimeType: "application/json",
+        }],
+      };
+    }
+  );
+
+  // ── dashboard://summary ─────────────────────────────────────────────────
+  // Current financial year summary: total sales, receivables, payables, cash.
+  // This is the same data as dashboard_summary tool with period='this-fy'.
+  server.resource(
+    "dashboard_summary",
+    "dashboard://summary",
+    async (_uri) => {
+      // No date range = API defaults to current financial year
+      const summary = await client.dashboard.summary();
+      return {
+        contents: [{
+          uri: "dashboard://summary",
+          text: JSON.stringify(summary, null, 2),
+          mimeType: "application/json",
+        }],
+      };
+    }
+  );
+
+  // ── bank://accounts ──────────────────────────────────────────────────────
+  // All bank and cash accounts with current balances. Load this to see the
+  // business's financial position across all accounts.
+  server.resource(
+    "bank_accounts",
+    "bank://accounts",
+    async (_uri) => {
+      const accounts = await client.bankAccount.list();
+      return {
+        contents: [{
+          uri: "bank://accounts",
+          text: JSON.stringify(accounts, null, 2),
+          mimeType: "application/json",
+        }],
+      };
+    }
+  );
+
+  // ── shipments://recent ───────────────────────────────────────────────────
+  // The 10 most recent shipments. Load this for a quick logistics overview.
+  server.resource(
+    "shipments_recent",
+    "shipments://recent",
+    async (_uri) => {
+      const result = await client.shipment.list({ page: 1, limit: 10 });
+      return {
+        contents: [{
+          uri: "shipments://recent",
+          text: JSON.stringify(result.data, null, 2),
+          mimeType: "application/json",
+        }],
+      };
+    }
+  );
+
+  // ── targets://active ────────────────────────────────────────────────────
+  // Active sales targets (whose period includes today) with real-time progress.
+  // Load this to understand team sales goals and performance at a glance.
+  server.resource(
+    "targets_active",
+    "targets://active",
+    async (_uri) => {
+      const targets = await client.target.list({ active: true, withProgress: true });
+      return {
+        contents: [{
+          uri: "targets://active",
+          text: JSON.stringify(targets, null, 2),
+          mimeType: "application/json",
+        }],
+      };
+    }
+  );
+}

package/src/server.ts

@@ -0,0 +1,55 @@
+/**
+ * Tool and resource registration aggregator.
+ *
+ * All tool and resource registrations flow through here so that index.ts
+ * stays minimal and individual tool files stay focused on their domain.
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { HisaaboClient } from "./client.js";
+import { registerInvoiceTools } from "./tools/invoice.js";
+import { registerPartyTools } from "./tools/party.js";
+import { registerItemTools } from "./tools/item.js";
+import { registerPaymentTools } from "./tools/payment.js";
+import { registerExpenseTools } from "./tools/expense.js";
+import { registerDashboardTools } from "./tools/dashboard.js";
+import { registerGstTools } from "./tools/gst.js";
+import { registerShipmentTools } from "./tools/shipment.js";
+import { registerBankAccountTools } from "./tools/bankAccount.js";
+import { registerReportTools } from "./tools/reports.js";
+import { registerStoreTools } from "./tools/store.js";
+import { registerTargetTools } from "./tools/target.js";
+import { registerImportTools } from "./tools/import.js";
+import { registerResources } from "./resources/index.js";
+
+export function registerTools(server: McpServer, client: HisaaboClient): void {
+  // Core business operations
+  registerInvoiceTools(server, client);
+  registerPartyTools(server, client);
+  registerItemTools(server, client);
+  registerPaymentTools(server, client);
+  registerExpenseTools(server, client);
+
+  // Analytics and reporting
+  registerDashboardTools(server, client);
+  registerGstTools(server, client);
+  registerReportTools(server, client);
+
+  // Logistics
+  registerShipmentTools(server, client);
+
+  // Financial accounts
+  registerBankAccountTools(server, client);
+
+  // Online store
+  registerStoreTools(server, client);
+
+  // Sales targets
+  registerTargetTools(server, client);
+
+  // Data import
+  registerImportTools(server, client);
+
+  // Read-only context resources
+  registerResources(server, client);
+}

package/src/tools/bankAccount.ts

@@ -0,0 +1,200 @@
+/**
+ * Bank account tools — manage bank/cash accounts and transactions.
+ *
+ * Tools registered:
+ *   bank_account_list         — list all bank and cash accounts with balances
+ *   bank_account_get          — get account details with recent transactions
+ *   bank_account_create       — create a new bank or cash account
+ *   bank_account_transfer     — transfer funds between two accounts
+ *   bank_account_transactions — list transactions for an account
+ *   bank_account_summary      — get total balance across all accounts
+ */
+
+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 ACCOUNT_TYPES = ["savings", "current", "cash", "credit", "other"] as const;
+
+export function registerBankAccountTools(server: McpServer, client: HisaaboClient) {
+
+  server.tool(
+    "bank_account_list",
+    [
+      "List all bank and cash accounts for the active business, including current balances.",
+      "Use this to find account UUIDs before recording payments or transfers.",
+      "The 'currentBalance' field reflects the running balance after all recorded transactions.",
+      "The default account (isDefault=true) is used automatically when no account is specified in payment_create.",
+    ].join(" "),
+    {},
+    wrapTool(async (_input) => {
+      const accounts = await client.bankAccount.list();
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(accounts, null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "bank_account_get",
+    [
+      "Get details of a single bank account including its 20 most recent transactions.",
+      "Use this to check an account's running balance and recent activity.",
+    ].join(" "),
+    {
+      account_id: z.string().uuid()
+        .describe("Bank account UUID from bank_account_list."),
+    },
+    wrapTool(async (input) => {
+      const account = await client.bankAccount.get(input.account_id);
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(account, null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "bank_account_create",
+    [
+      "Create a new bank account or cash account for the business.",
+      "Use account_type='cash' for a physical cash register/petty cash account.",
+      "Use account_type='savings' or 'current' for bank accounts.",
+      "opening_balance sets the starting balance (e.g. the balance when you started using Hisaabo).",
+      "Set is_default=true to make this the default account for payment recording.",
+    ].join(" "),
+    {
+      account_name: z.string().min(1).max(200)
+        .describe("Display name, e.g. 'HDFC Current Account' or 'Petty Cash'."),
+      account_type: z.enum(ACCOUNT_TYPES)
+        .describe("'savings', 'current', 'cash' (petty cash/physical cash), 'credit', or 'other'."),
+      account_number: z.string().max(34).optional()
+        .describe("Bank account number (not required for cash accounts)."),
+      ifsc: z.string().max(11).optional()
+        .describe("IFSC code, e.g. 'HDFC0001234'. Required for bank transfers."),
+      bank_name: z.string().max(200).optional()
+        .describe("Bank name, e.g. 'HDFC Bank', 'State Bank of India'."),
+      opening_balance: z.string().regex(/^-?\d+(\.\d{1,2})?$/).optional()
+        .describe("Opening balance as decimal string. Default '0'. Use the current account balance when onboarding."),
+      is_default: z.boolean().optional()
+        .describe("If true, this becomes the default account. Any previous default is cleared."),
+    },
+    wrapTool(async (input) => {
+      const account = await client.bankAccount.create({
+        accountName: input.account_name,
+        accountType: input.account_type,
+        accountNumber: input.account_number,
+        ifsc: input.ifsc,
+        bankName: input.bank_name,
+        openingBalance: input.opening_balance,
+        isDefault: input.is_default,
+      });
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(account, null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "bank_account_transfer",
+    [
+      "Transfer funds between two of the business's bank/cash accounts.",
+      "Creates a withdrawal transaction on the source account and a deposit on the destination.",
+      "Use this to record moving cash to the bank, or inter-account transfers.",
+      "Example: transfer from 'Petty Cash' to 'HDFC Current Account' to replenish cash.",
+    ].join(" "),
+    {
+      from_account_id: z.string().uuid()
+        .describe("UUID of the source account (funds leave this account)."),
+      to_account_id: z.string().uuid()
+        .describe("UUID of the destination account (funds arrive here). Must differ from from_account_id."),
+      amount: z.string().regex(/^\d+(\.\d{1,2})?$/)
+        .describe("Transfer amount as decimal string, e.g. '5000.00'."),
+      description: z.string().max(500).optional()
+        .describe("Description of the transfer, e.g. 'Monthly cash deposit to bank'."),
+      transaction_date: z.string().datetime().optional()
+        .describe("Date of the transfer (ISO 8601). Defaults to today."),
+    },
+    wrapTool(async (input) => {
+      const result = await client.bankAccount.transfer({
+        fromAccountId: input.from_account_id,
+        toAccountId: input.to_account_id,
+        amount: input.amount,
+        description: input.description,
+        transactionDate: input.transaction_date,
+      });
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(result, null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "bank_account_transactions",
+    [
+      "List transactions for a specific bank or cash account with date and type filters.",
+      "Each transaction includes a 'balanceAfter' field showing the running balance.",
+      "Use type='deposit' to see only incoming funds, 'withdrawal' for outgoing, 'transfer' for inter-account moves.",
+    ].join(" "),
+    {
+      account_id: z.string().uuid()
+        .describe("Bank account UUID from bank_account_list."),
+      from_date: z.string().datetime().optional()
+        .describe("Start date (ISO 8601)."),
+      to_date: z.string().datetime().optional()
+        .describe("End date (ISO 8601)."),
+      type: z.enum(["deposit", "withdrawal", "transfer"]).optional()
+        .describe("Filter by transaction type."),
+      page: z.number().int().min(1).default(1)
+        .describe("Page number for pagination."),
+    },
+    wrapTool(async (input) => {
+      const result = await client.bankAccount.listTransactions({
+        bankAccountId: input.account_id,
+        fromDate: input.from_date,
+        toDate: input.to_date,
+        type: input.type,
+        page: input.page,
+        limit: MAX_PAGE_SIZE,
+      });
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(withPaginationMeta(result), null, 2),
+        }],
+      };
+    })
+  );
+
+  server.tool(
+    "bank_account_summary",
+    [
+      "Get a summary of total funds across all bank and cash accounts.",
+      "Returns totalBalance (all accounts), cashInHand (cash-type accounts only), bankBalance (non-cash accounts), and account count.",
+      "Use this to quickly answer 'How much money do we have in total?' or 'What is our cash in hand?'",
+    ].join(" "),
+    {},
+    wrapTool(async (_input) => {
+      const summary = await client.bankAccount.summary();
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify(summary, null, 2),
+        }],
+      };
+    })
+  );
+}