get_statement

Instructions

Implementation Reference

• src/index.ts:64-115 (handler)

  The 'get_statement' tool handler registered with the MCP server. It accepts an 'account' (string), 'from' (ISO date), and optional 'to' (ISO date), validates dates, fetches bank statements from Monobank API, parses and formats the response.

  server.tool(
      "get_statement",
      "Get Monobank statement for the time from {from} to {to} time in seconds in Unix time format. The maximum time for which it is posssible to obtain a statement is 31 days + 1 hour (2682000 seconds). The statement can be retrieved not more than once per 60 seconds, otherwise an error will be thrown.",
      {
          input: z.object({
              account: z
                  .string()
                  .nonempty()
                  .describe(
                      "A unique indentificator of the Monobank account or a jar from the Statement list. If not provided, then a defaukt account is used, which is equal to '0'.",
                  ),
              from: z
                  .string()
                  .nonempty()
                  .describe("A date in ISO 8601 YYYY-MM-DD format."),
              to: z
                  .string()
                  .optional()
                  .describe("A date in ISO 8601 YYYY-MM-DD format."),
          }),
      },
      async ({ input }) => {
          try {
              const { account, from, to } = input;
  
              const dateValidation = validateStatementDates(from, to);
              if ("content" in dateValidation) {
                  return dateValidation;
              }
  
              const { fromInSeconds, toInSeconds } = dateValidation;
              const { baseUrl, monobankApiToken } = getConfig();
  
              const response = await fetchWithErrorHandling(
                  `${baseUrl}/personal/statement/${account}/${fromInSeconds}/${toInSeconds}`,
                  {
                      headers: {
                          "X-Token": monobankApiToken,
                      },
                  },
              );
  
              const data = await parseJsonResponse<StatementItem[]>(response);
              const statement = z.array(StatementItemSchema).parse(data);
              const formattedStatement = formatStatementItems(statement);
  
              return createSuccessResponse(formattedStatement);
          } catch (error) {
              return formatErrorAsToolResponse(error, "fetch statement");
          }
      },
  );

• src/index.ts:67-84 (schema)

  Zod input schema for 'get_statement' tool: account (non-empty string), from (non-empty ISO date string), and optional to (ISO date string).

  {
      input: z.object({
          account: z
              .string()
              .nonempty()
              .describe(
                  "A unique indentificator of the Monobank account or a jar from the Statement list. If not provided, then a defaukt account is used, which is equal to '0'.",
              ),
          from: z
              .string()
              .nonempty()
              .describe("A date in ISO 8601 YYYY-MM-DD format."),
          to: z
              .string()
              .optional()
              .describe("A date in ISO 8601 YYYY-MM-DD format."),
      }),
  },

• src/schemas.ts:14-33 (schema)

  StatementItemSchema: Zod schema defining the structure of a statement item returned from the API, used to validate API response data.

  export const StatementItemSchema = z.object({
      id: z.string(),
      time: z.number(),
      description: z.string(),
      mcc: z.number(),
      originalMcc: z.number(),
      hold: z.boolean(),
      amount: z.number().describe("Amount in cents, multiply by 100"),
      operationAmount: z.number().describe("Amount in cents, multiply by 100"),
      currencyCode: z.number(),
      commissionRate: z.number(),
      cashbackAmount: z.number().describe("Amount in cents, multiply by 100"),
      balance: z.number().describe("Amount in cents, multiply by 100"),
      comment: z.string().optional(),
      receiptId: z.string().optional(),
      invoiceId: z.string().optional(),
      counterEdrpou: z.string().optional(),
      counterIban: z.string().optional(),
      counterName: z.string().optional(),
  });

• src/helpers.ts:98-124 (helper)

  validateStatementDates helper: Validates ISO date strings, converts them to Unix timestamps (seconds), and enforces the maximum 31-day+1-hour range constraint.

  export function validateStatementDates(
      from: string,
      to?: string,
  ): DateValidationResult | ToolResponse {
      const fromDate = new Date(from);
      const toDate = to ? new Date(to) : new Date();
  
      if (isNaN(fromDate.getTime())) {
          return createErrorResponse(`Invalid 'from' date format: ${from}`);
      }
  
      if (to && isNaN(toDate.getTime())) {
          return createErrorResponse(`Invalid 'to' date format: ${to}`);
      }
  
      const fromInSeconds = Math.floor(fromDate.getTime() / 1000);
      const toInSeconds = Math.floor(toDate.getTime() / 1000);
  
      // Validate time range (max 31 days + 1 hour = 2682000 seconds)
      if (toInSeconds - fromInSeconds > 2682000) {
          return createErrorResponse(
              "Time range exceeds maximum allowed (31 days + 1 hour). Please use a smaller date range.",
          );
      }
  
      return { fromInSeconds, toInSeconds };
  }

• src/helpers.ts:126-134 (helper)

  formatStatementItems helper: Converts monetary amounts from cents to whole units by dividing amount, operationAmount, cashbackAmount, and balance by 100.

  export function formatStatementItems(items: StatementItem[]) {
      return items.map((item) => ({
          ...item,
          amount: item.amount / 100,
          operationAmount: item.operationAmount / 100,
          cashbackAmount: item.cashbackAmount / 100,
          balance: item.balance / 100,
      }));
  }