mercury_get_invoice

Instructions

Implementation Reference

• src/tools/invoices.ts:72-75 (handler)

  The actual handler function for mercury_get_invoice. Makes a GET request to /ar/invoices/{invoiceId} via the MercuryClient, passing the UUID invoice ID from the validated args, then returns the result via textResult.

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

• src/tools/invoices.ts:69-71 (schema)

  Input schema for mercury_get_invoice: a single 'invoiceId' parameter validated as a UUID via Zod's z.uuid().

  {
    invoiceId: z.uuid().describe("The invoice ID (UUID)"),
  },

• src/tools/invoices.ts:57-77 (registration)

  Registration of mercury_get_invoice via defineTool(). This calls server.registerTool under the hood, passing the tool name, description, input schema, handler, and annotations (readOnlyHint: true). The tool is registered inside registerInvoiceTools() which gets called from registerAllTools() in src/tools/index.ts.

  defineTool(
    server,
    "mercury_get_invoice",
    [
      "Retrieve a specific invoice by ID, including line items, status, and the payment URL.",
      "",
      "USE WHEN: fetching the full detail of one invoice (line items, current status, balance due, payment URL) whose ID is already known.",
      "",
      "DO NOT USE: to enumerate invoices (use `mercury_list_invoices`). For attachments use `mercury_list_invoice_attachments`.",
      "",
      "RETURNS: `{ id, status, amount, customerId, lineItems, paymentUrl, dueDate, ... }`.",
    ].join("\n"),
    {
      invoiceId: z.uuid().describe("The invoice ID (UUID)"),
    },
    async ({ invoiceId }) => {
      const data = await client.get(`/ar/invoices/${invoiceId}`);
      return textResult(data);
    },
    { title: "Get Invoice", readOnlyHint: true, openWorldHint: true },
  );

• src/tools/index.ts:33-38 (registration)

  Top-level registration entry point: registerInvoiceTools(server, client) is called from registerAllTools(), which wires up all invoice tools including mercury_get_invoice.

    registerInvoiceTools(server, client);
    registerCustomerTools(server, client);
  
    // Webhooks
    registerWebhookTools(server, client);
  }

• src/tools/_shared.ts:28-54 (helper)

  The defineTool helper used to register mercury_get_invoice. It wraps the handler with middleware (rate limiting, dry-run, audit) via wrapToolHandler, creates a strict Zod schema, and calls server.registerTool with the tool name, description, schema, and wrapped handler.

  export function defineTool<S extends ZodRawShape>(
    server: McpServer,
    name: string,
    description: string,
    inputSchema: S,
    handler: (args: z.infer<z.ZodObject<S>>) => Promise<ToolResult>,
    annotations: ToolAnnotations,
  ): void {
    const wrapped = wrapToolHandler(name, handler);
    const strictSchema = z.object(inputSchema).strict();
    // MCP behavioral annotations (readOnlyHint / destructiveHint /
    // idempotentHint / openWorldHint) — declared machine-readable so
    // hosts and rubrics (TDQS / Glama Behavior dimension) can detect
    // tool semantics without scraping the prose description. Required
    // (not optional) so every new tool ships with explicit semantics —
    // forgetting the annotation now fails typecheck instead of
    // silently shipping a tool with no hint set.
    // The MCP SDK overloads `registerTool` with shape narrowing the runtime
    // strict-schema and the wrapped callback can't satisfy through generics.
    // Both casts are runtime-safe — the signatures only diverge at the type
    // level. Asserted by the existing tool-registration tests.
    (server.registerTool as unknown as (...a: unknown[]) => unknown)(
      name,
      { description, inputSchema: strictSchema, annotations },
      wrapped,
    );
  }