@rvanbaalen/ofxreader 1.2.0

package/src/mcp.ts

@@ -0,0 +1,259 @@
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+import { readOfxFile, parseOfx, OfxError } from "./parser.ts";
+import { buildDocument } from "./model.ts";
+import type { OfxDocument, Statement } from "./model.ts";
+import { summaries, uniqueAccounts, balances } from "./report.ts";
+import type { BalancePoint } from "./report.ts";
+import { filterTransactions } from "./query.ts";
+import type { TransactionFilters } from "./query.ts";
+import { resolveVendorQuery } from "./vendors/resolve.ts";
+import { load as loadVendors, save as saveVendors, learn as learnVendor, today } from "./vendors/store.ts";
+import { getVersion } from "./version.ts";
+
+type ToolResult = {
+  content: Array<{ type: "text"; text: string }>;
+  isError?: boolean;
+};
+
+function load(path: string): OfxDocument {
+  return buildDocument(parseOfx(readOfxFile(path)));
+}
+
+function ok(data: unknown): ToolResult {
+  return { content: [{ type: "text", text: JSON.stringify(data) }] };
+}
+
+function fail(err: unknown): ToolResult {
+  const code = err instanceof OfxError ? err.code : "INTERNAL";
+  const message = err instanceof Error ? err.message : String(err);
+  return {
+    content: [{ type: "text", text: JSON.stringify({ error: { code, message } }) }],
+    isError: true,
+  };
+}
+
+const PATH_FIELD = z
+  .string()
+  .describe("Path to an OFX 2.x (XML) file, e.g. /Users/me/statement.ofx");
+
+/** Build the ofxreader MCP server with one tool per CLI capability. */
+export function createServer(): McpServer {
+  const server = new McpServer({ name: "ofxreader", version: getVersion() });
+
+  server.registerTool(
+    "ofx_summary",
+    {
+      title: "Summarize OFX statements",
+      description:
+        "Summarize each statement in an OFX 2.x (XML) bank or credit-card file: account, " +
+        "currency, statement period, ledger & available balance, transaction counts, and " +
+        "totals (credits, debits, net). Use this for any .ofx file.",
+      inputSchema: { path: PATH_FIELD },
+    },
+    async ({ path }) => {
+      try {
+        return ok(summaries(load(path).statements));
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    "ofx_accounts",
+    {
+      title: "List OFX accounts",
+      description:
+        "List the accounts found in an OFX 2.x (XML) file: id, type (CHECKING, SAVINGS, " +
+        "CREDITCARD, ...), bankId, and branchId.",
+      inputSchema: { path: PATH_FIELD },
+    },
+    async ({ path }) => {
+      try {
+        return ok(uniqueAccounts(load(path).statements));
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    "ofx_transactions",
+    {
+      title: "Query OFX transactions",
+      description:
+        "Read transactions from an OFX 2.x (XML) file with optional filters: posted-date " +
+        "range, signed-amount range, debit/credit direction, case-insensitive text or regex " +
+        "search over name+memo+payee, single account, and a row limit. Returns " +
+        "{ total, count, transactions[] } where total is the match count and count is the " +
+        "number of rows returned. Use this to find or extract specific transactions. " +
+        "Pass `vendor` to resolve a learned vendor alias: results are restricted to " +
+        "confirmed matches and the response also includes `vendorCandidates` (fuzzy, " +
+        "unconfirmed descriptors) to propose to the user and persist via ofx_vendor_learn.",
+      inputSchema: {
+        path: PATH_FIELD,
+        from: z
+          .string()
+          .regex(/^\d{4}-\d{2}-\d{2}$/)
+          .optional()
+          .describe("Inclusive start date, YYYY-MM-DD"),
+        to: z
+          .string()
+          .regex(/^\d{4}-\d{2}-\d{2}$/)
+          .optional()
+          .describe("Inclusive end date, YYYY-MM-DD"),
+        min: z.number().optional().describe("Minimum signed amount (negative = money out)"),
+        max: z.number().optional().describe("Maximum signed amount"),
+        type: z
+          .enum(["debit", "credit"])
+          .optional()
+          .describe("debit = amount < 0 (money out); credit = amount > 0 (money in)"),
+        search: z
+          .string()
+          .optional()
+          .describe("Case-insensitive match over name + memo + payee"),
+        regex: z
+          .boolean()
+          .optional()
+          .describe("Treat search as a JavaScript regular expression"),
+        account: z.string().optional().describe("Restrict to a single account id"),
+        limit: z
+          .number()
+          .int()
+          .nonnegative()
+          .optional()
+          .describe("Maximum rows to return (total still reports all matches)"),
+        vendor: z
+          .string()
+          .optional()
+          .describe(
+            "Canonical vendor name to resolve via the learned alias store. Restricts " +
+              "results to confirmed matches and returns vendorCandidates to learn from.",
+          ),
+      },
+    },
+    async ({ path, regex, search, from, to, min, max, type, account, limit, vendor }) => {
+      try {
+        if (regex && search == null) {
+          return fail(new OfxError("USAGE", "regex requires search."));
+        }
+        const filters: TransactionFilters = {
+          from,
+          to,
+          min,
+          max,
+          type,
+          account,
+          limit,
+          search,
+          regex,
+        };
+        const { statements } = load(path);
+        if (vendor != null) {
+          return ok(resolveVendorQuery(loadVendors(), statements, vendor, filters));
+        }
+        const all = statements.flatMap((s) => s.transactions);
+        return ok(filterTransactions(all, filters));
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    "ofx_vendor_learn",
+    {
+      title: "Learn a vendor alias",
+      description:
+        "Persist that the given raw OFX descriptors belong to a vendor. Descriptors are " +
+        "normalized into signatures so future ofx_transactions(vendor) queries match them " +
+        "deterministically. Use after the user confirms candidate descriptors.",
+      inputSchema: {
+        vendor: z.string().describe('Canonical vendor name, e.g. "Jason\'s Carousel"'),
+        descriptors: z
+          .array(z.string())
+          .min(1)
+          .describe("Confirmed raw descriptors (transaction name/memo/payee) for this vendor"),
+      },
+    },
+    async ({ vendor, descriptors }) => {
+      try {
+        const store = loadVendors();
+        const entry = learnVendor(store, vendor, descriptors, today());
+        saveVendors(store);
+        return ok({ vendor, ...entry });
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    "ofx_vendors",
+    {
+      title: "List learned vendors",
+      description:
+        "List the learned vendor aliases (canonical name -> signatures + raw descriptors).",
+      inputSchema: {},
+    },
+    async () => {
+      try {
+        return ok(loadVendors().vendors);
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+
+  // Resource: statement balances for an OFX file, each stated with its as-of date.
+  // Read URI: ofx:/absolute/path/to/file.ofx
+  server.registerResource(
+    "ofx-balances",
+    new ResourceTemplate("ofx:{+path}", { list: undefined }),
+    {
+      title: "OFX statement balances",
+      description:
+        "Ledger and available balances for each account in an OFX 2.x file, each stated " +
+        'with its as-of date (e.g. "Balance at 2024-03-31 is 4327.87 USD"). ' +
+        "Read it with the URI ofx:/absolute/path/to/file.ofx",
+      mimeType: "text/plain",
+    },
+    async (uri, variables) => {
+      const rawPath = Array.isArray(variables.path) ? variables.path[0] : variables.path;
+      const path = decodeURIComponent(rawPath ?? "");
+      const doc = load(path); // throws OfxError -> surfaced as a read error
+      return {
+        contents: [{ uri: uri.href, mimeType: "text/plain", text: formatBalances(doc.statements) }],
+      };
+    },
+  );
+
+  return server;
+}
+
+/** Human-readable balance report: one block per statement, each balance dated. */
+function formatBalances(statements: Statement[]): string {
+  const accounts = balances(statements);
+  if (accounts.length === 0) return "No statements found in this OFX file.";
+
+  return accounts
+    .map((a) => {
+      const cur = a.currency ? ` ${a.currency}` : "";
+      const header = `Account ${a.account} — ${a.accountType}${a.currency ? ` (${a.currency})` : ""}`;
+      const lines = [header];
+      if (a.ledger) lines.push(`  ${balanceLine("Balance", a.ledger, cur)}`);
+      if (a.available) lines.push(`  ${balanceLine("Available balance", a.available, cur)}`);
+      if (!a.ledger && !a.available) lines.push("  No balance reported.");
+      return lines.join("\n");
+    })
+    .join("\n\n");
+}
+
+function balanceLine(label: string, point: BalancePoint, currency: string): string {
+  const amount = Number.isFinite(point.amount) ? point.amount.toFixed(2) : "unknown";
+  return point.date != null
+    ? `${label} at ${point.date} is ${amount}${currency}`
+    : `${label} is ${amount}${currency} (as-of date unknown)`;
+}

package/src/model.ts

@@ -0,0 +1,137 @@
+import { ofxToIso } from "./dates.ts";
+
+export type Account = {
+  id: string;
+  type: string; // CHECKING | SAVINGS | CREDITCARD | MONEYMRKT | ...
+  bankId: string | null;
+  branchId: string | null;
+};
+
+export type Money = {
+  amount: number;
+  asOf: string | null; // ISO 8601
+};
+
+export type Transaction = {
+  account: string; // owning ACCTID
+  id: string; // FITID
+  date: string | null; // ISO 8601 (from DTPOSTED)
+  amount: number; // signed (TRNAMT); negative = outflow
+  trnType: string; // raw OFX TRNTYPE (DEBIT, CREDIT, CHECK, POS, FEE, ...)
+  name: string;
+  memo: string | null;
+  payee: string | null;
+  checkNumber: string | null;
+};
+
+export type Statement = {
+  account: Account;
+  currency: string | null;
+  period: { start: string | null; end: string | null };
+  balance: Money | null; // LEDGERBAL
+  available: Money | null; // AVAILBAL
+  transactions: Transaction[];
+};
+
+export type OfxDocument = {
+  statements: Statement[];
+};
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+type Raw = any;
+
+function toArray<T>(x: T | T[] | null | undefined): T[] {
+  if (x == null) return [];
+  return Array.isArray(x) ? x : [x];
+}
+
+/** Coerce a parsed node value to a trimmed string, or null when empty/absent. */
+function str(v: unknown): string | null {
+  if (v == null || typeof v === "object") return null;
+  const s = String(v).trim();
+  return s === "" ? null : s;
+}
+
+/** Coerce a parsed node value to a number; NaN when absent or non-numeric. */
+function num(v: unknown): number {
+  const s = str(v);
+  return s == null ? NaN : Number(s);
+}
+
+/** Normalize a raw parsed OFX object into the canonical document model. */
+export function buildDocument(raw: Raw): OfxDocument {
+  const ofx: Raw = raw?.OFX ?? {};
+  const statements: Statement[] = [];
+
+  for (const trnrs of toArray<Raw>(ofx.BANKMSGSRSV1?.STMTTRNRS)) {
+    for (const stmt of toArray<Raw>(trnrs?.STMTRS)) {
+      statements.push(bankStatement(stmt));
+    }
+  }
+  for (const trnrs of toArray<Raw>(ofx.CREDITCARDMSGSRSV1?.CCSTMTTRNRS)) {
+    for (const stmt of toArray<Raw>(trnrs?.CCSTMTRS)) {
+      statements.push(creditCardStatement(stmt));
+    }
+  }
+
+  return { statements };
+}
+
+function bankStatement(stmt: Raw): Statement {
+  const acct: Raw = stmt?.BANKACCTFROM ?? {};
+  const account: Account = {
+    id: str(acct.ACCTID) ?? "",
+    type: str(acct.ACCTTYPE) ?? "UNKNOWN",
+    bankId: str(acct.BANKID),
+    branchId: str(acct.BRANCHID),
+  };
+  return assemble(stmt, account);
+}
+
+function creditCardStatement(stmt: Raw): Statement {
+  const acct: Raw = stmt?.CCACCTFROM ?? {};
+  const account: Account = {
+    id: str(acct.ACCTID) ?? "",
+    type: "CREDITCARD",
+    bankId: null,
+    branchId: null,
+  };
+  return assemble(stmt, account);
+}
+
+function assemble(stmt: Raw, account: Account): Statement {
+  const tranlist: Raw = stmt?.BANKTRANLIST ?? {};
+  const transactions = toArray<Raw>(tranlist.STMTTRN).map((t) => transaction(t, account.id));
+  return {
+    account,
+    currency: str(stmt?.CURDEF),
+    period: {
+      start: ofxToIso(str(tranlist.DTSTART)),
+      end: ofxToIso(str(tranlist.DTEND)),
+    },
+    balance: balance(stmt?.LEDGERBAL),
+    available: balance(stmt?.AVAILBAL),
+    transactions,
+  };
+}
+
+function balance(node: Raw): Money | null {
+  if (node == null) return null;
+  return { amount: num(node.BALAMT), asOf: ofxToIso(str(node.DTASOF)) };
+}
+
+function transaction(t: Raw, accountId: string): Transaction {
+  const payee =
+    t?.PAYEE != null && typeof t.PAYEE === "object" ? str(t.PAYEE.NAME) : str(t?.PAYEE);
+  return {
+    account: accountId,
+    id: str(t?.FITID) ?? "",
+    date: ofxToIso(str(t?.DTPOSTED)),
+    amount: num(t?.TRNAMT),
+    trnType: str(t?.TRNTYPE) ?? "OTHER",
+    name: str(t?.NAME) ?? "",
+    memo: str(t?.MEMO),
+    payee,
+    checkNumber: str(t?.CHECKNUM),
+  };
+}

package/src/output.ts

@@ -0,0 +1,9 @@
+/** Write a successful result as JSON to stdout. */
+export function emit(data: unknown, pretty: boolean): void {
+  process.stdout.write(JSON.stringify(data, null, pretty ? 2 : 0) + "\n");
+}
+
+/** Write a structured error as JSON to stderr. */
+export function emitError(code: string, message: string): void {
+  process.stderr.write(JSON.stringify({ error: { code, message } }) + "\n");
+}

package/src/parser.ts

@@ -0,0 +1,85 @@
+import { readFileSync } from "node:fs";
+import { XMLParser } from "fast-xml-parser";
+
+/** Structured error carrying a machine-readable code for the CLI's JSON output. */
+export class OfxError extends Error {
+  code: string;
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = "OfxError";
+    this.code = code;
+  }
+}
+
+const HEADER_SCAN_LEN = 1024;
+
+/**
+ * Sniff which OFX generation a file is.
+ *   "2"  -> OFX 2.x (XML)            (supported)
+ *   "1"  -> OFX 1.x (SGML)           (rejected)
+ *   null -> not recognizable as OFX
+ */
+export function detectOfxVersion(text: string): "1" | "2" | null {
+  const head = text.slice(0, HEADER_SCAN_LEN);
+  // OFX 2.x carries an XML processing instruction: <?OFX OFXHEADER="200" ...?>
+  if (/<\?OFX[^>]*OFXHEADER\s*=\s*"\s*2\d*\s*"/i.test(head)) return "2";
+  // Some 2.x exports drop the <?OFX?> PI but are still XML with an <OFX> root.
+  if (/<\?xml[\s?]/i.test(head) && /<OFX[\s>]/i.test(text)) return "2";
+  // OFX 1.x uses a colon-delimited SGML header: OFXHEADER:100
+  if (/OFXHEADER\s*:\s*\d+/i.test(head)) return "1";
+  return null;
+}
+
+/** Read a file from disk, mapping fs errors to OfxError codes. */
+export function readOfxFile(path: string): string {
+  try {
+    return readFileSync(path, "utf8");
+  } catch (err) {
+    const e = err as NodeJS.ErrnoException;
+    if (e.code === "ENOENT") {
+      throw new OfxError("FILE_NOT_FOUND", `File not found: ${path}`);
+    }
+    if (e.code === "EISDIR") {
+      throw new OfxError("READ_ERROR", `Path is a directory, not a file: ${path}`);
+    }
+    throw new OfxError("READ_ERROR", `Could not read file ${path}: ${e.message}`);
+  }
+}
+
+/** Parse OFX 2.x text into a raw nested object. Throws OfxError on any problem. */
+export function parseOfx(text: string): unknown {
+  const version = detectOfxVersion(text);
+  if (version === "1") {
+    throw new OfxError(
+      "NOT_OFX2",
+      "File looks like OFX 1.x (SGML). This tool only supports OFX 2.x (XML).",
+    );
+  }
+  if (version == null) {
+    throw new OfxError("NOT_OFX2", "File is not recognizable as OFX 2.x (XML).");
+  }
+
+  // Strip every processing instruction (<?xml?>, <?OFX?>) so the parser only
+  // ever sees the <OFX> element tree.
+  const cleaned = text.replace(/<\?[\s\S]*?\?>/g, "");
+
+  const parser = new XMLParser({
+    ignoreAttributes: true,
+    ignoreDeclaration: true,
+    parseTagValue: false, // keep amounts/dates/ids as raw strings; we normalize ourselves
+    trimValues: true,
+    processEntities: true,
+  });
+
+  let raw: unknown;
+  try {
+    raw = parser.parse(cleaned);
+  } catch (err) {
+    throw new OfxError("PARSE_ERROR", `Failed to parse OFX XML: ${(err as Error).message}`);
+  }
+
+  if (raw == null || typeof raw !== "object" || !("OFX" in (raw as object))) {
+    throw new OfxError("PARSE_ERROR", "Parsed file has no <OFX> root element.");
+  }
+  return raw;
+}

package/src/query.ts

@@ -0,0 +1,61 @@
+import type { Transaction } from "./model.ts";
+
+export type TransactionFilters = {
+  from?: string; // YYYY-MM-DD inclusive lower bound on posted date
+  to?: string; // YYYY-MM-DD inclusive upper bound
+  min?: number; // signed amount >=
+  max?: number; // signed amount <=
+  type?: "debit" | "credit"; // debit: amount < 0, credit: amount > 0
+  search?: string; // matched against name + memo + payee
+  regex?: boolean; // treat search as a RegExp
+  account?: string; // restrict to one ACCTID
+  limit?: number; // cap returned rows (matches still counted in `total`)
+};
+
+export type QueryResult = {
+  total: number; // matches before --limit
+  count: number; // rows returned after --limit
+  transactions: Transaction[];
+};
+
+export function filterTransactions(
+  txns: Transaction[],
+  filters: TransactionFilters,
+): QueryResult {
+  const matcher = buildMatcher(filters);
+
+  const matched = txns.filter((t) => {
+    if (filters.account != null && t.account !== filters.account) return false;
+
+    const date = t.date == null ? null : t.date.slice(0, 10);
+    if (filters.from != null && (date == null || date < filters.from)) return false;
+    if (filters.to != null && (date == null || date > filters.to)) return false;
+
+    if (filters.min != null && !(t.amount >= filters.min)) return false;
+    if (filters.max != null && !(t.amount <= filters.max)) return false;
+
+    if (filters.type === "debit" && !(t.amount < 0)) return false;
+    if (filters.type === "credit" && !(t.amount > 0)) return false;
+
+    if (matcher != null) {
+      const haystack = `${t.name} ${t.memo ?? ""} ${t.payee ?? ""}`;
+      if (!matcher.test(haystack)) return false;
+    }
+    return true;
+  });
+
+  const transactions =
+    filters.limit != null ? matched.slice(0, filters.limit) : matched;
+
+  return { total: matched.length, count: transactions.length, transactions };
+}
+
+function buildMatcher(filters: TransactionFilters): RegExp | null {
+  if (filters.search == null || filters.search === "") return null;
+  const source = filters.regex ? filters.search : escapeRegExp(filters.search);
+  return new RegExp(source, "i");
+}
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/src/report.ts

@@ -0,0 +1,90 @@
+import type { Account, Money, Statement } from "./model.ts";
+
+export type Summary = {
+  account: Account;
+  currency: string | null;
+  period: { start: string | null; end: string | null };
+  balance: Money | null;
+  available: Money | null;
+  counts: { transactions: number; credits: number; debits: number };
+  totals: { credits: number; debits: number; net: number };
+};
+
+/** One summary object per statement. */
+export function summaries(statements: Statement[]): Summary[] {
+  return statements.map(summarize);
+}
+
+/** Accounts across all statements, deduplicated by type + id. */
+export function uniqueAccounts(statements: Statement[]): Account[] {
+  const seen = new Map<string, Account>();
+  for (const s of statements) {
+    const key = `${s.account.type}:${s.account.id}`;
+    if (!seen.has(key)) seen.set(key, s.account);
+  }
+  return [...seen.values()];
+}
+
+function summarize(stmt: Statement): Summary {
+  let credits = 0;
+  let debits = 0;
+  let creditSum = 0;
+  let debitSum = 0;
+  for (const t of stmt.transactions) {
+    if (t.amount > 0) {
+      credits++;
+      creditSum += t.amount;
+    } else if (t.amount < 0) {
+      debits++;
+      debitSum += t.amount;
+    }
+  }
+  return {
+    account: stmt.account,
+    currency: stmt.currency,
+    period: stmt.period,
+    balance: stmt.balance,
+    available: stmt.available,
+    counts: { transactions: stmt.transactions.length, credits, debits },
+    totals: {
+      credits: round2(creditSum),
+      debits: round2(debitSum),
+      net: round2(creditSum + debitSum),
+    },
+  };
+}
+
+function round2(n: number): number {
+  if (!Number.isFinite(n)) return 0;
+  return Math.round((n + Number.EPSILON) * 100) / 100;
+}
+
+export type BalancePoint = {
+  amount: number;
+  asOf: string | null; // full ISO 8601 timestamp from DTASOF
+  date: string | null; // the as-of date only (YYYY-MM-DD)
+};
+
+export type AccountBalances = {
+  account: string;
+  accountType: string;
+  currency: string | null;
+  ledger: BalancePoint | null; // LEDGERBAL
+  available: BalancePoint | null; // AVAILBAL
+};
+
+/** Ledger and available balances per statement, each carrying its as-of date. */
+export function balances(statements: Statement[]): AccountBalances[] {
+  return statements.map((s) => ({
+    account: s.account.id,
+    accountType: s.account.type,
+    currency: s.currency,
+    ledger: toPoint(s.balance),
+    available: toPoint(s.available),
+  }));
+}
+
+function toPoint(b: Money | null): BalancePoint | null {
+  if (b == null) return null;
+  return { amount: b.amount, asOf: b.asOf, date: b.asOf == null ? null : b.asOf.slice(0, 10) };
+}