mercury_update_transaction

Instructions

Implementation Reference

• src/tools/transactions.ts:107-141 (handler)

  The core handler for mercury_update_transaction. Defines the tool with defineTool(), accepts transactionId (UUID), optional note (nullable string), and optional categoryId (nullable UUID). The handler makes a PATCH request to /transaction/{transactionId} with the provided body.

  defineTool(
    server,
    "mercury_update_transaction",
    [
      "Update a transaction's internal note or category (no money movement).",
      "",
      "USE WHEN: tagging a transaction with a category for bookkeeping, or attaching an internal memo. Send `null` to clear a field, omit the key to keep the current value.",
      "",
      "DO NOT USE: to change the amount, counterparty, or status — those are immutable post-execution. Mercury endpoint is `PATCH /transaction/{id}` (no `accountId` in the path).",
      "",
      "SIDE EFFECTS: overwrites the note / category on Mercury's side. Persistent. Audit log on Mercury records the change. No effect on the booked transaction itself or on the counterparty.",
      "",
      "RETURNS: `{ id, note, categoryId, ... }` — the updated transaction.",
    ].join("\n"),
    {
      transactionId: z.uuid().describe("The transaction ID"),
      note: z
        .string()
        .nullable()
        .optional()
        .describe("Internal note (send null to clear, omit to keep current)"),
      categoryId: z
        .uuid()
        .nullable()
        .optional()
        .describe(
          "Category ID (UUID, see mercury_list_categories). Send null to clear, omit to keep current.",
        ),
    },
    async ({ transactionId, ...body }) => {
      const data = await client.patch(`/transaction/${transactionId}`, body);
      return textResult(data);
    },
    { title: "Update Transaction", destructiveHint: false, openWorldHint: true },
  );

• src/tools/transactions.ts:121-135 (schema)

  Input schema for mercury_update_transaction. Uses Zod validation: transactionId (z.uuid()), note (z.string().nullable().optional()), categoryId (z.uuid().nullable().optional()).

  {
    transactionId: z.uuid().describe("The transaction ID"),
    note: z
      .string()
      .nullable()
      .optional()
      .describe("Internal note (send null to clear, omit to keep current)"),
    categoryId: z
      .uuid()
      .nullable()
      .optional()
      .describe(
        "Category ID (UUID, see mercury_list_categories). Send null to clear, omit to keep current.",
      ),
  },

• src/tools/index.ts:20-25 (registration)

  Registration entrypoint: registerAllTools() calls registerTransactionTools(server, client) which registers mercury_update_transaction on the MCP server.

  export function registerAllTools(server: McpServer, client: MercuryClient): void {
    // Banking
    registerAccountTools(server, client);
    registerCardTools(server, client);
    registerCreditTools(server, client);
    registerTransactionTools(server, client);

• src/tools/transactions.ts:7-7 (registration)

  registerTransactionTools function definition — the function that registers mercury_update_transaction (and other transaction tools) on the MCP server.

  export function registerTransactionTools(server: McpServer, client: MercuryClient): void {

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

  defineTool helper used by mercury_update_transaction. Calls wrapToolHandler() for rate limiting/dry-run/audit middleware, then registers the tool on the MCP server with strict schema validation.

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