mercury_get_customer

Instructions

Implementation Reference

• src/tools/customers.ts:64-67 (handler)

  The actual handler function for 'mercury_get_customer'. It takes a customerId (UUID), performs a GET request to `/ar/customers/${customerId}` via the MercuryClient, and returns the sanitized JSON result.

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

• src/tools/customers.ts:62-63 (schema)

  Input schema for 'mercury_get_customer' — expects a single required 'customerId' field validated as a UUID string.

    customerId: z.string().uuid().describe("Customer ID"),
  },

• src/tools/customers.ts:49-68 (registration)

  The tool is registered via defineTool() inside registerCustomerTools() in src/tools/customers.ts, which calls server.registerTool under the hood (via _shared.ts).

  defineTool(
    server,
    "mercury_get_customer",
    [
      "Retrieve a specific Accounts Receivable customer by ID.",
      "",
      "USE WHEN: fetching the full detail of one customer whose ID is already known. Faster than relisting + filtering when you have the ID.",
      "",
      "DO NOT USE: to enumerate customers (use `mercury_list_customers`). For payment recipients use `mercury_list_recipients` (different surface).",
      "",
      "RETURNS: `{ id, name, email, address, ... }`.",
    ].join("\n"),
    {
      customerId: z.string().uuid().describe("Customer ID"),
    },
    async ({ customerId }) => {
      const data = await client.get(`/ar/customers/${customerId}`);
      return textResult(data);
    },
  );

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

  registerCustomerTools is called from src/tools/index.ts (line 34) to register all customer tools including mercury_get_customer on the MCP server.

  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/tools/_shared.ts:29-39 (helper)

  The defineTool helper wraps the handler with middleware (rate limiting, dry-run, audit) and registers it on the MCP server via server.registerTool.

  export function defineTool<S extends ZodRawShape>(
    server: McpServer,
    name: string,
    description: string,
    inputSchema: S,
    handler: (args: z.infer<z.ZodObject<S>>) => Promise<ToolResult>,
  ): void {
    const wrapped = wrapToolHandler(name, handler);
    const strictSchema = z.object(inputSchema).strict();
    server.registerTool(name, { description, inputSchema: strictSchema }, wrapped);
  }