mercury_get_transaction

Instructions

Implementation Reference

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

  Tool registration for 'mercury_get_transaction' via defineTool() with description, input schema (accountId, transactionId), and readOnly+openWorld annotations.

  defineTool(
    server,
    "mercury_get_transaction",
    [
      "Retrieve a specific transaction by ID for a Mercury deposit account.",
      "",
      "USE WHEN: fetching the full detail of one transaction whose ID is already known (typically from `mercury_list_transactions`). Faster than relisting + filtering.",
      "",
      "DO NOT USE: to enumerate transactions (use `mercury_list_transactions`). For IO Credit transactions, use `mercury_list_credit_transactions` and filter by id client-side.",
      "",
      "RETURNS: `{ id, amount, status, postedAt, counterpartyName, memo, ... }`.",
    ].join("\n"),
    {
      accountId: z.uuid().describe("The Mercury account ID"),
      transactionId: z.uuid().describe("The transaction ID"),
    },
    async ({ accountId, transactionId }) => {
      const data = await client.get(`/account/${accountId}/transaction/${transactionId}`);
      return textResult(data);
    },
    { title: "Get Transaction", readOnlyHint: true, openWorldHint: true },
  );

• src/tools/transactions.ts:61-66 (handler)

  Handler function that calls client.get('/account/${accountId}/transaction/${transactionId}') and returns textResult(data).

    async ({ accountId, transactionId }) => {
      const data = await client.get(`/account/${accountId}/transaction/${transactionId}`);
      return textResult(data);
    },
    { title: "Get Transaction", readOnlyHint: true, openWorldHint: true },
  );

• src/tools/transactions.ts:57-60 (schema)

  Input schema defining accountId (uuid) and transactionId (uuid) as required parameters for the tool.

  {
    accountId: z.uuid().describe("The Mercury account ID"),
    transactionId: z.uuid().describe("The transaction ID"),
  },

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

  The defineTool() helper that registers the tool on the MCP server with wrapped handler and strict schema.

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

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

  Calls registerTransactionTools(server, client) to register all transaction tools including mercury_get_transaction.

    registerTransactionTools(server, client);
    registerRecipientTools(server, client);
    registerStatementTools(server, client);
    registerTreasuryTools(server, client);
    registerCategoryTools(server, client);
    registerOrganizationTools(server, client);
  
    // Accounts Receivable (Invoicing) — requires Mercury Plus
    registerInvoiceTools(server, client);
    registerCustomerTools(server, client);
  
    // Webhooks
    registerWebhookTools(server, client);
  }