mercury_update_customer

Instructions

Implementation Reference

• src/tools/customers.ts:115-118 (handler)

  The handler function for the mercury_update_customer tool. It destructures customerId from the args and uses the rest as the body for a PATCH request to /ar/customers/{customerId}. Called via defineTool which wraps it with rate limiting, dry-run, and audit middleware.

  async ({ customerId, ...body }) => {
    const data = await client.patch(`/ar/customers/${customerId}`, body);
    return textResult(data);
  },

• src/tools/customers.ts:110-113 (schema)

  The Zod input schema for mercury_update_customer. Requires customerId (UUID), with optional name, email, and billing address fields.

  customerId: z.string().uuid().describe("Customer ID"),
  name: z.string().optional(),
  email: z.string().email().optional(),
  address: addressSchema.optional(),

• src/tools/customers.ts:95-119 (registration)

  Registration of mercury_update_customer via defineTool() inside registerCustomerTools(). The defineTool function wraps the handler with middleware (rate limit, dry-run, audit) and calls server.registerTool.

  defineTool(
    server,
    "mercury_update_customer",
    [
      "Update an existing Accounts Receivable customer. Pass only the fields you want to change.",
      "",
      "USE WHEN: amending a customer's contact details (name, email, billing address) after creation. Existing invoices are not retroactively modified.",
      "",
      "DO NOT USE: to delete a customer (use `mercury_delete_customer`). To change the customer of an existing invoice, cancel + recreate the invoice.",
      "",
      "SIDE EFFECTS: writes the new customer record to Mercury. Persistent. Only the fields you pass are changed — omitted fields keep their current value.",
      "",
      "RETURNS: `{ id, name, email, address, ... }` — the updated customer.",
    ].join("\n"),
    {
      customerId: z.string().uuid().describe("Customer ID"),
      name: z.string().optional(),
      email: z.string().email().optional(),
      address: addressSchema.optional(),
    },
    async ({ customerId, ...body }) => {
      const data = await client.patch(`/ar/customers/${customerId}`, body);
      return textResult(data);
    },
  );

• src/tools/customers.ts:18-38 (registration)

  The registerCustomerTools function is called from src/tools/index.ts (registerAllTools), which is called from src/server.ts (createServer), which is called from src/index.ts (main). All customer tools are registered together.

  export function registerCustomerTools(server: McpServer, client: MercuryClient): void {
    defineTool(
      server,
      "mercury_list_customers",
      [
        "List Accounts Receivable customers, with cursor-based pagination.",
        "",
        "USE WHEN: enumerating AR customers before creating an invoice (need a `customerId` for `mercury_create_invoice`), or for a customer-level audit. Use `startAfter` / `endBefore` for paging beyond the limit.",
        "",
        "DO NOT USE: for payment recipients (`mercury_list_recipients` is the bank-payment counterparty list, distinct from AR customers). For one customer whose ID is known, prefer `mercury_get_customer`.",
        "",
        "RETURNS: `{ customers: [{ id, name, email, address, ... }] }`.",
      ].join("\n"),
      {
        limit: z.number().int().min(1).max(1000).optional().describe("Max results (1-1000)"),
        order: z.enum(["asc", "desc"]).optional(),
        startAfter: z.string().uuid().optional().describe("Pagination cursor (forward)"),
        endBefore: z.string().uuid().optional().describe("Pagination cursor (reverse)"),
      },
      async (args) => {
        const query: Record<string, string | number | undefined> = {

• src/middleware.ts:49-51 (helper)

  Rate-limit bucket assignment for mercury_update_customer, mapping it to the 'customers_write' bucket with daily limit of 3 and monthly limit of 60 (line 73).

  mercury_update_customer: "customers_write",
  mercury_delete_customer: "customers_write",