mercury_update_recipient

Instructions

Implementation Reference

• src/tools/recipients.ts:52-55 (handler)

  The handler function for mercury_update_recipient. It extracts recipientId from args, sends a POST request to /recipient/{recipientId} (singular form), and returns the sanitized result.

  async ({ recipientId, ...body }) => {
    const data = await client.post(`/recipient/${recipientId}`, body);
    return textResult(data);
  },

• src/tools/recipients.ts:42-51 (schema)

  Zod schema defining the input parameters for mercury_update_recipient: required recipientId (UUID), optional name, nickname, contactEmail, emails array, and defaultPaymentMethod enum.

  {
    recipientId: z.uuid().describe("The recipient ID"),
    name: z.string().optional().describe("Recipient legal name"),
    nickname: z.string().optional().describe("Internal nickname"),
    contactEmail: z.email().optional().describe("Primary contact email"),
    emails: z.array(z.email()).optional().describe("List of email addresses"),
    defaultPaymentMethod: z
      .enum(["domesticAch", "internationalWire", "domesticWire", "check"])
      .optional(),
  },

• src/tools/recipients.ts:28-57 (registration)

  Registration of the tool via defineTool() call inside registerRecipientTools(), mapping name 'mercury_update_recipient' to its schema, handler, and annotations.

  defineTool(
    server,
    "mercury_update_recipient",
    [
      "Update an existing payment recipient (legal name, nickname, contact emails, default payment method).",
      "",
      "USE WHEN: amending a recipient's contact info or default payment method after creation. Useful for re-routing future payments to a recipient via a different method (e.g. ACH → wire) without recreating it.",
      "",
      "DO NOT USE: to change the bank account number / routing number — that requires a fresh recipient (security policy on Mercury's side). Use `mercury_add_recipient` for the new banking info.",
      "",
      "SIDE EFFECTS: writes the recipient record on Mercury. Persistent. Only the fields you pass are changed. Mercury endpoint is `POST /recipient/{id}` (SINGULAR — not the plural `/recipients/{id}`).",
      "",
      "RETURNS: `{ id, name, nickname, defaultPaymentMethod, ... }` — the updated recipient.",
    ].join("\n"),
    {
      recipientId: z.uuid().describe("The recipient ID"),
      name: z.string().optional().describe("Recipient legal name"),
      nickname: z.string().optional().describe("Internal nickname"),
      contactEmail: z.email().optional().describe("Primary contact email"),
      emails: z.array(z.email()).optional().describe("List of email addresses"),
      defaultPaymentMethod: z
        .enum(["domesticAch", "internationalWire", "domesticWire", "check"])
        .optional(),
    },
    async ({ recipientId, ...body }) => {
      const data = await client.post(`/recipient/${recipientId}`, body);
      return textResult(data);
    },
    { title: "Update Recipient", destructiveHint: false, openWorldHint: true },
  );

• src/middleware.ts:64-64 (registration)

  Rate-limit bucket mapping: mercury_update_recipient is mapped to the 'recipients_update' bucket, which has a daily limit of 2 and monthly limit of 15.

  mercury_update_recipient: "recipients_update",

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

  The defineTool helper used to register all tools. It wraps the handler with middleware (rate-limiting, dry-run, audit) via wrapToolHandler, then registers on the MCP server.

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