mercury_list_invoice_attachments

Instructions

Implementation Reference

• src/tools/invoices.ts:237-239 (handler)

  The handler function that executes the tool logic: calls client.get on /ar/invoices/{invoiceId}/attachments and returns the result via textResult.

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

• src/tools/invoices.ts:234-236 (schema)

  Input schema requiring invoiceId (UUID) as the only parameter.

  {
    invoiceId: z.uuid().describe("Invoice ID"),
  },

• src/tools/invoices.ts:222-242 (registration)

  Registration of the tool via defineTool, which calls server.registerTool internally. The tool is registered with the name 'mercury_list_invoice_attachments'.

  defineTool(
    server,
    "mercury_list_invoice_attachments",
    [
      "List attachments associated with an invoice (PDF copies, supporting documents).",
      "",
      "USE WHEN: discovering which files were attached to an invoice — for archival, audit, or to share with a customer. The download URL is short-lived; refetch shortly before download.",
      "",
      "DO NOT USE: to upload an attachment — this MCP currently exposes only the read side. Mercury's API does support attachment upload (`POST /ar/invoices/{id}/attachments`); a write tool can be added if needed.",
      "",
      "RETURNS: `{ attachments: [{ id, filename, downloadUrl, ... }] }`.",
    ].join("\n"),
    {
      invoiceId: z.uuid().describe("Invoice ID"),
    },
    async ({ invoiceId }) => {
      const data = await client.get(`/ar/invoices/${invoiceId}/attachments`);
      return textResult(data);
    },
    { title: "List Invoice Attachments", readOnlyHint: true, openWorldHint: true },
  );

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

  registerInvoiceTools is called in registerAllTools, which registers all invoice-related tools including mercury_list_invoice_attachments on the MCP server.

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

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

  The defineTool helper wraps the handler with middleware and registers the tool on the MCP server. It is used by the mercury_list_invoice_attachments registration.

  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,
    );
  }