bank-mcp

Instructions

Implementation Reference

• src/tools/list-transactions.ts:42-100 (handler)

  Main handler function that implements the list_transactions tool logic. It resolves connections/accounts, applies caching, calls provider.listTransactions for each account, applies local filters, sorts results by date, and returns the final transaction list.

  export async function listTransactions(
    args: z.infer<typeof listTransactionsSchema>,
  ): Promise<Transaction[]> {
    const config = loadConfig();
    const dateFrom = args.dateFrom || defaultDateFrom(config.defaults.transactionDays);
    const dateTo = args.dateTo || today();
  
    const filter: TransactionFilter = {
      dateFrom,
      dateTo,
      amountMin: args.amountMin,
      amountMax: args.amountMax,
      type: args.type,
      limit: args.limit,
    };
  
    // Resolve which connections and accounts to query
    const connections = args.connectionId
      ? [getConnection(config, args.connectionId)]
      : getAllConnections(config);
  
    const allTx: Transaction[] = [];
  
    for (const conn of connections) {
      const provider = getProvider(conn.provider);
  
      // Get account list (may come from cache)
      let accountIds: string[];
      if (args.accountId) {
        accountIds = [args.accountId];
      } else {
        const accounts = await provider.listAccounts(conn.config);
        accountIds = accounts.map((a) => a.uid);
      }
  
      for (const accId of accountIds) {
        const cacheKey = `tx:${conn.id}:${accId}:${dateFrom}:${dateTo}`;
        const cached = cache.get<Transaction[]>(cacheKey);
  
        if (cached) {
          allTx.push(...applyLocalFilters(cached, filter));
          continue;
        }
  
        const transactions = await provider.listTransactions(
          conn.config,
          accId,
          { dateFrom, dateTo },
        );
        cache.set(cacheKey, transactions, TTL.TRANSACTIONS);
        allTx.push(...applyLocalFilters(transactions, filter));
      }
    }
  
    // Sort by date descending (most recent first)
    allTx.sort((a, b) => b.date.localeCompare(a.date));
  
    return args.limit ? allTx.slice(0, args.limit) : allTx;
  }

• src/tools/list-transactions.ts:7-40 (schema)

  Zod schema defining the input validation for list_transactions tool. Includes optional fields: connectionId, accountId, dateFrom, dateTo, amountMin, amountMax, type (debit/credit), and limit.

  export const listTransactionsSchema = z.object({
    connectionId: z
      .string()
      .optional()
      .describe("Connection ID. If omitted, queries all connections."),
    accountId: z
      .string()
      .optional()
      .describe("Account UID. If omitted, queries all accounts."),
    dateFrom: z
      .string()
      .optional()
      .describe('Start date (YYYY-MM-DD). Defaults to 90 days ago.'),
    dateTo: z
      .string()
      .optional()
      .describe('End date (YYYY-MM-DD). Defaults to today.'),
    amountMin: z
      .number()
      .optional()
      .describe("Minimum absolute amount."),
    amountMax: z
      .number()
      .optional()
      .describe("Maximum absolute amount."),
    type: z
      .enum(["debit", "credit"])
      .optional()
      .describe("Filter by transaction type."),
    limit: z
      .number()
      .optional()
      .describe("Maximum number of transactions to return."),
  });

• src/server.ts:32-36 (registration)

  Tool registration in TOOLS array defining the 'list_transactions' tool with its description and inputSchema reference.

    name: "list_transactions",
    description:
      "List bank transactions with optional filters. Defaults to last 90 days. Supports date range, amount range, and debit/credit type filtering.",
    inputSchema: z.toJSONSchema(listTransactionsSchema),
  },

• src/server.ts:61-62 (registration)

  Handler registration mapping the 'list_transactions' tool name to the listTransactions function with schema parsing.

  list_transactions: (args) =>
    listTransactions(listTransactionsSchema.parse(args)),

• src/tools/list-transactions.ts:102-127 (helper)

  Helper functions supporting the list_transactions handler: applyLocalFilters (filters by amount/type), defaultDateFrom (calculates start date from days), and today (returns current date string).

  function applyLocalFilters(
    txs: Transaction[],
    f: TransactionFilter,
  ): Transaction[] {
    let result = txs;
    if (f.amountMin !== undefined) {
      result = result.filter((t) => Math.abs(t.amount) >= f.amountMin!);
    }
    if (f.amountMax !== undefined) {
      result = result.filter((t) => Math.abs(t.amount) <= f.amountMax!);
    }
    if (f.type) {
      result = result.filter((t) => t.type === f.type);
    }
    return result;
  }
  
  function defaultDateFrom(days: number): string {
    const d = new Date();
    d.setDate(d.getDate() - days);
    return d.toISOString().slice(0, 10);
  }
  
  function today(): string {
    return new Date().toISOString().slice(0, 10);
  }