bankmcp 0.1.0

package/src/enablebanking.ts

@@ -0,0 +1,171 @@
+// Thin typed client for the Enable Banking API. Every request carries an
+// RS256 JWT signed with the application's private key (see the quick start at
+// https://enablebanking.com/docs/api/quick-start/).
+import { createPrivateKey, createSign, type KeyObject } from "node:crypto";
+import { config, readPrivateKey } from "./config.ts";
+
+export interface Amount {
+  currency: string;
+  amount: string;
+}
+
+export interface Aspsp {
+  name: string;
+  country: string;
+  logo?: string;
+  psu_types?: string[];
+  maximum_consent_validity?: number;
+  sandbox?: boolean;
+  beta?: boolean;
+}
+
+export interface AccountResource {
+  uid: string;
+  account_id?: { iban?: string; other?: { identification?: string; scheme_name?: string } };
+  name?: string;
+  product?: string;
+  currency: string;
+  cash_account_type?: string;
+  identification_hash: string;
+}
+
+export interface Balance {
+  name?: string;
+  balance_amount: Amount;
+  balance_type: string;
+  reference_date?: string;
+  last_change_date_time?: string;
+}
+
+export interface Transaction {
+  entry_reference?: string;
+  transaction_id?: string;
+  transaction_amount: Amount;
+  credit_debit_indicator: "CRDT" | "DBIT";
+  status: string;
+  booking_date?: string;
+  value_date?: string;
+  transaction_date?: string;
+  creditor?: { name?: string };
+  debtor?: { name?: string };
+  remittance_information?: string[];
+  bank_transaction_code?: { code?: string; sub_code?: string; description?: string };
+  merchant_category_code?: string;
+  balance_after_transaction?: Amount;
+  note?: string;
+}
+
+export interface Session {
+  session_id: string;
+  accounts: AccountResource[];
+  aspsp: { name: string; country: string };
+  psu_type: string;
+  access: { valid_until: string };
+}
+
+export interface SessionStatus {
+  status: string;
+  accounts: string[];
+  aspsp: { name: string; country: string };
+  access: { valid_until: string };
+  created: string;
+  authorized?: string;
+  closed?: string;
+}
+
+export interface Application {
+  name: string;
+  kid: string;
+  environment: "SANDBOX" | "PRODUCTION";
+  redirect_urls: string[];
+  active: boolean;
+}
+
+export class EnableBankingError extends Error {
+  status: number;
+  body: string;
+  constructor(status: number, body: string) {
+    super(`Enable Banking API ${status}: ${body}`);
+    this.status = status;
+    this.body = body;
+  }
+  /** True when the bank consent behind this call is no longer usable. */
+  get consentGone(): boolean {
+    return this.status === 401 || this.status === 403 || this.status === 410 || /session|consent|expired|revoked/i.test(this.body);
+  }
+}
+
+// --- JWT ---
+
+let keyObject: KeyObject | undefined;
+let cachedToken: { value: string; exp: number } | undefined;
+
+/** Forget the loaded key and token, e.g. after the setup page stored a new key. */
+export function resetKeyCache(): void {
+  keyObject = undefined;
+  cachedToken = undefined;
+}
+
+const b64url = (input: Buffer | string) => Buffer.from(input).toString("base64url");
+
+export function makeJwt(now = Math.floor(Date.now() / 1000)): string {
+  if (cachedToken && cachedToken.exp - now > 300) return cachedToken.value;
+  keyObject ??= createPrivateKey(readPrivateKey());
+  const header = b64url(JSON.stringify({ typ: "JWT", alg: "RS256", kid: config.appId }));
+  const payload = b64url(JSON.stringify({ iss: "enablebanking.com", aud: "api.enablebanking.com", iat: now, exp: now + 3600 }));
+  const signature = createSign("RSA-SHA256").update(`${header}.${payload}`).sign(keyObject).toString("base64url");
+  cachedToken = { value: `${header}.${payload}.${signature}`, exp: now + 3600 };
+  return cachedToken.value;
+}
+
+// --- HTTP ---
+
+async function api<T>(method: string, path: string, body?: unknown, query?: Record<string, string | undefined>): Promise<T> {
+  const url = new URL(path, config.apiBase);
+  for (const [k, v] of Object.entries(query ?? {})) if (v !== undefined && v !== "") url.searchParams.set(k, v);
+  const res = await fetch(url, {
+    method,
+    headers: {
+      Authorization: `Bearer ${makeJwt()}`,
+      Accept: "application/json",
+      ...(body ? { "Content-Type": "application/json" } : {}),
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const text = await res.text();
+  if (!res.ok) throw new EnableBankingError(res.status, text);
+  return (text ? JSON.parse(text) : {}) as T;
+}
+
+export interface TransactionPage {
+  transactions: Transaction[];
+  continuation_key?: string;
+}
+
+export const eb = {
+  getApplication: () => api<Application>("GET", "/application"),
+
+  listAspsps: async (country: string) => (await api<{ aspsps: Aspsp[] }>("GET", "/aspsps", undefined, { country })).aspsps,
+
+  startAuthorization: (input: { aspsp: Aspsp; state: string; redirectUrl: string; validUntil: Date; psuType?: string }) =>
+    api<{ url: string; authorization_id: string; psu_id_hash: string }>("POST", "/auth", {
+      access: { valid_until: input.validUntil.toISOString() },
+      aspsp: { name: input.aspsp.name, country: input.aspsp.country },
+      state: input.state,
+      redirect_url: input.redirectUrl,
+      psu_type: input.psuType ?? "personal",
+    }),
+
+  createSession: (code: string) => api<Session>("POST", "/sessions", { code }),
+  getSession: (sessionId: string) => api<SessionStatus>("GET", `/sessions/${sessionId}`),
+  deleteSession: (sessionId: string) => api<unknown>("DELETE", `/sessions/${sessionId}`),
+
+  getBalances: async (accountUid: string) => (await api<{ balances: Balance[] }>("GET", `/accounts/${accountUid}/balances`)).balances,
+
+  getTransactionPage: (accountUid: string, opts: { dateFrom?: string; dateTo?: string; continuationKey?: string } = {}) =>
+    api<TransactionPage>("GET", `/accounts/${accountUid}/transactions`, undefined, {
+      date_from: opts.dateFrom,
+      date_to: opts.dateTo,
+      continuation_key: opts.continuationKey,
+    }),
+};

package/src/local.ts

@@ -0,0 +1,50 @@
+// Local mode helper: a small https server on localhost that serves the setup
+// page and receives the bank redirect. Enable Banking requires https redirect
+// URLs, so a self-signed certificate is created on first run.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createServer as createHttpsServer, type Server } from "node:https";
+import selfsigned from "selfsigned";
+import { config } from "./config.ts";
+import { createApp } from "./app.ts";
+
+let server: Server | undefined;
+let starting: Promise<string> | undefined;
+
+async function certificate(): Promise<{ cert: string; key: string }> {
+  const certPath = join(config.dataDir, "localhost-cert.pem");
+  const keyPath = join(config.dataDir, "localhost-key.pem");
+  if (existsSync(certPath) && existsSync(keyPath)) return { cert: readFileSync(certPath, "utf8"), key: readFileSync(keyPath, "utf8") };
+  const notAfterDate = new Date();
+  notAfterDate.setFullYear(notAfterDate.getFullYear() + 10);
+  const pems = await selfsigned.generate([{ name: "commonName", value: "localhost" }], {
+    keySize: 2048,
+    notAfterDate,
+    extensions: [{ name: "subjectAltName", altNames: [{ type: 2, value: "localhost" }, { type: 7, ip: "127.0.0.1" }] }],
+  });
+  mkdirSync(config.dataDir, { recursive: true });
+  writeFileSync(certPath, pems.cert, { mode: 0o600 });
+  writeFileSync(keyPath, pems.private, { mode: 0o600 });
+  return { cert: pems.cert, key: pems.private };
+}
+
+/** Starts the local https server if it is not running. Resolves to the base URL. */
+export function ensureLocalServer(): Promise<string> {
+  if (server) return Promise.resolve(config.baseUrl);
+  starting ??= new Promise(async (resolve, reject) => {
+    const app = createApp({ remote: false });
+    const s = createHttpsServer(await certificate(), app);
+    s.once("error", (err: NodeJS.ErrnoException) => {
+      if (err.code === "EADDRINUSE") {
+        // Another BankMCP process (or an earlier one) already serves this port; use it.
+        server = undefined; starting = undefined; resolve(config.baseUrl);
+      } else reject(err);
+    });
+    s.listen(config.port, "127.0.0.1", () => {
+      server = s;
+      console.error(`[bank] local server on ${config.baseUrl}`);
+      resolve(config.baseUrl);
+    });
+  });
+  return starting;
+}

package/src/mcp.ts

@@ -0,0 +1,23 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerTools } from "./tools.ts";
+import { registerPrompts } from "./prompts.ts";
+
+export const VERSION = "0.1.0";
+
+export function createServer(): McpServer {
+  const server = new McpServer(
+    { name: "bank", version: VERSION },
+    {
+      instructions: [
+        "Read-only access to the owner's own bank accounts via Enable Banking (PSD2). It has no payment tools.",
+        "Accounts can be referred to by uid or by their label. Call list_accounts first when unsure.",
+        "Transaction amounts are signed: negative is money out. Use the `booked` balance for totals and net worth; `available` may include credit lines.",
+        "Banks return a limited history (often 90 days, some up to 2 years). If a date range comes back empty, say so rather than assuming there were no transactions.",
+        "If a tool says a consent is no longer valid, use start_consent for that bank; nothing else is lost.",
+      ].join(" "),
+    },
+  );
+  registerTools(server);
+  registerPrompts(server);
+  return server;
+}

package/src/pages.ts

@@ -0,0 +1,182 @@
+// The few HTML pages this server shows a human: the OAuth sign-in, the
+// result of a bank connection, and a status page. No external assets.
+import { config } from "./config.ts";
+
+export const esc = (s: string) => s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]!);
+
+type Kind = "ok" | "error" | "neutral";
+
+const fmtDate = (iso: string) => {
+  const d = new Date(iso);
+  return Number.isNaN(d.getTime()) ? iso : d.toLocaleDateString("en-GB", { day: "numeric", month: "long", year: "numeric" });
+};
+
+export function shell(title: string, body: string, opts: { kind?: Kind; pill?: string } = {}): string {
+  const name = config.appName;
+  const tab = title === name ? name : `${title} · ${name}`;
+  const pill = opts.pill ? `<div class="pill ${opts.kind ?? "neutral"}">${esc(opts.pill)}</div>` : "";
+  return `<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="color-scheme" content="light dark"><title>${esc(tab)}</title>
+<style>
+  :root{--bg:#f4f3ef;--card:#fff;--ink:#141414;--muted:#6f6e69;--line:#e6e4dd;--ok:#1f7a4d;--err:#b3261e}
+  @media (prefers-color-scheme:dark){:root{--bg:#111110;--card:#1b1b1a;--ink:#f2f1ec;--muted:#9b9a94;--line:#2c2b29;--ok:#5cc08a;--err:#ff8a7a}}
+  *{box-sizing:border-box}
+  body{margin:0;font:16px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",Inter,system-ui,sans-serif;background:var(--bg);color:var(--ink);-webkit-font-smoothing:antialiased}
+  .wrap{max-width:460px;margin:0 auto;padding:12vh 20px 48px}
+  .brand{display:flex;align-items:center;gap:10px;margin:0 0 22px;font-weight:800;font-size:20px;letter-spacing:-.02em}
+  .brand .mark{width:28px;height:28px;border-radius:8px;background:var(--ink);color:var(--bg);display:grid;place-items:center;font-size:15px;font-weight:900}
+  .card{background:var(--card);border:1px solid var(--line);border-radius:18px;padding:28px 28px 26px;box-shadow:0 1px 2px rgba(0,0,0,.04)}
+  .pill{display:inline-flex;align-items:center;gap:8px;font-size:13px;font-weight:600;color:var(--muted);margin:0 0 12px}
+  .pill::before{content:"";width:8px;height:8px;border-radius:50%;background:var(--muted)}
+  .pill.ok{color:var(--ok)}.pill.ok::before{background:var(--ok)}
+  .pill.error{color:var(--err)}.pill.error::before{background:var(--err)}
+  h1{font-size:26px;line-height:1.2;letter-spacing:-.02em;margin:0 0 12px}
+  p{margin:0 0 12px}.muted{color:var(--muted)}.error{color:var(--err)}
+  ul.rows{list-style:none;padding:0;margin:18px 0 6px}
+  ul.rows li{display:flex;justify-content:space-between;gap:16px;padding:11px 0;border-top:1px solid var(--line)}
+  ul.rows li:last-child{border-bottom:1px solid var(--line)}
+  ul.rows .r{color:var(--muted);font-variant-numeric:tabular-nums;white-space:nowrap}
+  label{display:block;font-weight:600;font-size:14px;margin:18px 0 6px}
+  input,textarea{width:100%;font:inherit;padding:12px 14px;border:1px solid var(--line);border-radius:10px;background:var(--bg);color:var(--ink)}
+  textarea{font:12px ui-monospace,SFMono-Regular,Menlo,monospace;margin-top:8px;resize:vertical}
+  input[type=file]{padding:9px 12px;font-size:14px}
+  input:focus,textarea:focus{outline:2px solid var(--ink);outline-offset:1px;border-color:transparent}
+  button{width:100%;margin-top:14px;font:inherit;font-weight:700;padding:13px 16px;border:0;border-radius:10px;background:var(--ink);color:var(--bg);cursor:pointer}
+  button:hover{opacity:.92}
+  code{font:13px ui-monospace,SFMono-Regular,Menlo,monospace;background:var(--bg);border:1px solid var(--line);padding:6px 10px;border-radius:8px;display:inline-block;word-break:break-all}
+  .copy{margin:14px 0 0}.copy p{margin:0 0 4px}
+  .copyrow{display:flex;gap:8px;align-items:flex-start}.copyrow code{flex:1}
+  .copybtn{width:auto;margin:0;padding:6px 10px;font-size:13px;font-weight:600;border-radius:8px;background:transparent;color:var(--ink);border:1px solid var(--line);white-space:nowrap}
+  .copybtn:hover{background:var(--bg);opacity:1}
+  footer{margin-top:20px;font-size:12px;color:var(--muted)}
+  footer a{color:inherit}
+</style>
+<body><div class="wrap">
+  <div class="brand"><span class="mark">${esc(name.replace(/[™®]/g, "").trim().charAt(0).toUpperCase() || "B")}</span><span>${esc(name)}</span></div>
+  <div class="card">${pill}<h1>${esc(title)}</h1>${body}</div>
+  <footer>${esc(name)} · read-only · self-hosted · <a href="/privacy">privacy</a> · <a href="/terms">terms</a></footer>
+</div></body></html>`;
+}
+
+export function loginPage(opts: { requestId: string; clientName?: string; returnTo?: string; error?: string }): string {
+  const who = opts.clientName ? `<b>${esc(opts.clientName)}</b>` : "An app";
+  const back = opts.returnTo ? `<p class="muted">After signing in you are sent back to <b>${esc(opts.returnTo)}</b>. Stop if that is not where you came from.</p>` : "";
+  return shell(
+    "Allow access?",
+    `<p>${who} wants read-only access to your bank accounts through this server. It reads balances and transactions. It has no payment tools.</p>${back}
+     ${opts.error ? `<p class="error">${esc(opts.error)}</p>` : ""}
+     <form method="post" action="/login">
+       <input type="hidden" name="request" value="${esc(opts.requestId)}">
+       <label for="pw">Password</label>
+       <input id="pw" type="password" name="password" autofocus autocomplete="current-password" required>
+       <button type="submit">Allow access</button>
+     </form>`,
+    { kind: "neutral", pill: "Sign-in request" },
+  );
+}
+
+export function connectedPage(session: { aspsp: { name: string }; access: { valid_until: string }; accounts: Array<{ uid: string; name?: string; product?: string; currency: string }> }): string {
+  const n = session.accounts.length;
+  return shell(
+    `${session.aspsp.name} is linked`,
+    `<p>${n} account${n === 1 ? "" : "s"} shared, read-only.</p>
+     <ul class="rows">${session.accounts.map((a) => `<li><span>${esc([a.name, a.product].filter(Boolean).join(" · ") || a.uid)}</span><span class="r">${esc(a.currency)}</span></li>`).join("")}</ul>
+     <p class="muted">Consent valid until ${esc(fmtDate(session.access.valid_until))}. You can close this tab and go back to your assistant.</p>`,
+    { kind: "ok", pill: "Connected" },
+  );
+}
+
+export function failedPage(message: string): string {
+  return shell("Bank not connected", `<p class="error">${esc(message)}</p><p class="muted">Go back to your assistant and start again.</p>`, { kind: "error", pill: "Not connected" });
+}
+
+export function signInFailedPage(message: string): string {
+  return shell("Sign-in failed", `<p class="error">${esc(message)}</p>`, { kind: "error", pill: "Not signed in" });
+}
+
+export function statusPage(input: { problems: string[]; mcpUrl: string; callbackUrl: string }): string {
+  if (input.problems.length) {
+    return shell(
+      "Not configured yet",
+      `<ul class="rows">${input.problems.map((p) => `<li><span>${esc(p)}</span></li>`).join("")}</ul><p class="muted">Set the environment variables and restart. The README has the list.</p>`,
+      { kind: "error", pill: "Setup incomplete" },
+    );
+  }
+  // Deliberately says nothing about which banks or accounts are connected:
+  // this page is reachable without a password. Ask consent_status through the connector.
+  if (config.localMode) {
+    return shell(
+      config.appName,
+      `<p>Running on this machine. Your MCP client is connected to it over stdio.</p>
+       <p class="muted" style="margin-bottom:4px">Redirect URL for the application at Enable Banking</p><p><code>${esc(input.callbackUrl)}</code></p>
+       <p class="muted">To link a bank, ask your assistant to connect it. The browser opens for the bank login and returns here.</p>`,
+      { kind: "ok", pill: "Running locally" },
+    );
+  }
+  return shell(
+    config.appName,
+    `<p>Running. Two addresses to copy:</p>
+     <p class="muted" style="margin-bottom:4px">Redirect URL for the application at Enable Banking</p><p><code>${esc(input.callbackUrl)}</code></p>
+     <p class="muted" style="margin-bottom:4px">MCP connector URL for your assistant, Claude, ChatGPT, Cursor or another (sign in with the admin password)</p><p><code>${esc(input.mcpUrl)}</code></p>`,
+    { kind: "ok", pill: "Running" },
+  );
+}
+
+export const CONSENT_DESCRIPTION = `${config.appName} lets you ask your AI assistant about your own accounts. It reads balances and transactions. It has no payment tools, and only the holder of the password can use it. You can revoke access at your bank at any time.`;
+
+export function setupPage(opts: { error?: string; values?: { app_id?: string; country?: string }; baseUrl?: string } = {}): string {
+  const v = opts.values ?? {};
+  const base = (opts.baseUrl ?? config.baseUrl).replace(/\/+$/, "");
+  const row = (label: string, value: string) =>
+    `<div class="copy"><p class="muted">${esc(label)}</p><div class="copyrow"><code>${esc(value)}</code><button type="button" class="copybtn" data-copy="${esc(value)}">Copy</button></div></div>`;
+  return shell(
+    `Set up ${config.appName}`,
+    `<p>First register an application at <a href="https://enablebanking.com/cp/applications" target="_blank" rel="noopener">Enable Banking</a>. Its form asks for these values:</p>
+     ${row("Allowed redirect URL", `${base}/callback`)}
+     ${row("Application description", CONSENT_DESCRIPTION)}
+     ${row("Privacy URL", `${base}/privacy`)}
+     ${row("Terms URL", `${base}/terms`)}
+     <p class="muted" style="margin-top:18px">Environment: <b>Production</b> for your real accounts, <b>Sandbox</b> to try with test data. Keep <b>generate private key</b> selected; a <code style="padding:1px 6px">.pem</code> file downloads once when you save. That file and the application id shown after saving go here:</p>
+     ${opts.error ? `<p class="error">${esc(opts.error)}</p>` : ""}
+     <form method="post" action="/setup" id="setup">
+       <label for="app_id">Application id</label>
+       <input id="app_id" name="app_id" required autocomplete="off" spellcheck="false" placeholder="aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" value="${esc(v.app_id ?? "")}">
+       <label for="pemfile">Private key file (the .pem that downloaded when you registered)</label>
+       <input id="pemfile" type="file" accept=".pem,.key,.txt,application/x-pem-file">
+       <textarea id="pem" name="pem" rows="3" placeholder="…or paste the contents of the .pem file here" spellcheck="false"></textarea>
+       <label for="country">Country of your banks</label>
+       <input id="country" name="country" maxlength="2" placeholder="DK" value="${esc(v.country ?? "")}" style="width:6em;text-transform:uppercase">
+       ${config.localMode ? "" : `<label for="password">Password (12+ characters, used when connecting your assistant)</label>
+       <input id="password" type="password" name="password" required minlength="12" autocomplete="new-password">
+       <label for="password2">Repeat password</label>
+       <input id="password2" type="password" name="password2" required minlength="12" autocomplete="new-password">`}
+       <button type="submit">Finish setup</button>
+     </form>
+     <script>
+       for (const b of document.querySelectorAll(".copybtn")) b.addEventListener("click", async () => {
+         try { await navigator.clipboard.writeText(b.dataset.copy); b.textContent = "Copied"; setTimeout(() => (b.textContent = "Copy"), 1500); }
+         catch { b.textContent = "Select and copy"; }
+       });
+       document.getElementById("pemfile").addEventListener("change", (e) => {
+         const f = e.target.files[0]; if (!f) return;
+         const r = new FileReader(); r.onload = () => { document.getElementById("pem").value = r.result; }; r.readAsText(f);
+       });
+     </script>`,
+    { kind: "neutral", pill: "First run" },
+  );
+}
+
+export const privacyPage = () =>
+  shell(
+    "Privacy",
+    `<p>This server is operated by the person who deployed it, to access their own bank accounts. It is not offered as a service to anyone else.</p>
+     <p>Account identifiers and consent references from Enable Banking are stored on the server so the operator's assistant can fetch balances and transactions on request. Transactions and balances themselves are not stored. No data is shared with third parties and nothing is collected about visitors.</p>
+     <p>The software is open source. Its authors do not operate this server, receive no data from it, and are not affiliated with Enable Banking, Anthropic or any bank.</p>`,
+  );
+
+export const termsPage = () =>
+  shell(
+    "Terms",
+    `<p>Personal software run by the person who deployed it, for their own non-commercial use, under Enable Banking's terms for individual use of their production environment. The operator is solely responsible for this instance.</p>
+     <p>Use at your own risk. The software is provided as is, without warranty of any kind, under the MIT licence. Its authors accept no liability for its use and are not a party to the operator's agreements with Enable Banking or any bank.</p>`,
+  );

package/src/prompts.ts

@@ -0,0 +1,127 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { store } from "./store.ts";
+
+const text = (t: string) => ({ messages: [{ role: "user" as const, content: { type: "text" as const, text: t } }] });
+
+function accountsContext(): string {
+  const s = store();
+  const accounts = s.accounts();
+  if (!accounts.length) return "No bank accounts are linked yet.";
+  return (
+    "Linked accounts:\n" +
+    accounts
+      .map((a) => `- ${a.label ?? a.name ?? a.product ?? "account"} (uid ${a.uid}, ${a.currency}, ${s.data.sessions[a.session_id]?.bank.name ?? "?"})`)
+      .join("\n")
+  );
+}
+
+export function registerPrompts(server: McpServer): void {
+  server.registerPrompt(
+    "connect-bank",
+    {
+      title: "Connect a bank",
+      description: "Walk the account holder through linking a bank (or renewing an expired consent).",
+      argsSchema: { bank: z.string().optional().describe("Bank name, if known") },
+    },
+    ({ bank }) =>
+      text(
+        `Help me connect ${bank ? `my bank "${bank}"` : "a bank"} to this server.
+
+1. If the exact bank name is unclear, call list_banks (optionally with search) and let me pick.
+2. Call start_consent with the exact name. Show me the URL as a plain link and tell me to open it, log in at the bank and approve read-only access. Mention how long the consent lasts.
+3. When I say I am done, call consent_status and list_accounts. Summarise what got linked.
+4. Suggest a short label for each account based on its name and product, and offer to set them with set_account_label so I can refer to accounts by name.
+
+${accountsContext()}`,
+      ),
+  );
+
+  server.registerPrompt(
+    "monthly-summary",
+    {
+      title: "Monthly summary",
+      description: "Income, spending by category and the biggest items for one month, across all accounts.",
+      argsSchema: { month: z.string().optional().describe("YYYY-MM, default last full month") },
+    },
+    ({ month }) =>
+      text(
+        `Give me a monthly financial summary for ${month ?? "the last full calendar month"}.
+
+Steps:
+1. Call list_accounts. Skip loan and mortgage accounts for spending; note their balance separately.
+2. For every current account call get_transactions for the month (from the 1st to the last day). Follow continuation keys until you have everything.
+3. Identify transfers between my own accounts: same amount, opposite sign, within two days, across two of my accounts. Exclude both legs from income and spending.
+4. Categorise the rest. If a categorisation skill or rules file is available, use it; otherwise use sensible categories (housing, groceries, transport, eating out, subscriptions, shopping, health, kids, travel, income, other).
+5. Present: total income, total spending, net, savings rate; a table of spending by category with the share of total; the ten largest single expenses; recurring items you noticed. Amounts in the account currency, no decimals.
+6. Close with two or three observations worth acting on. Be concrete and short.
+
+${accountsContext()}`,
+      ),
+  );
+
+  server.registerPrompt(
+    "subscription-audit",
+    {
+      title: "Subscription audit",
+      description: "Find recurring charges, their yearly cost, price increases and anything new.",
+      argsSchema: { months: z.string().optional().describe("How many months to look back, default 6") },
+    },
+    ({ months }) =>
+      text(
+        `Audit my recurring charges over the last ${months ?? "6"} months.
+
+1. Call list_accounts, then get_transactions for each current account over the whole period (follow continuation keys).
+2. Find debits that repeat with a regular cadence (monthly, quarterly, yearly) from the same counterparty or with the same description. Card payments to the same merchant with slightly varying amounts still count.
+3. For each: name, cadence, latest amount, yearly cost, first seen, and whether the amount went up during the period.
+4. Flag: subscriptions that started in the last two months, price increases, duplicates (same service charged twice), and anything that looks unused or forgotten.
+5. Present a table sorted by yearly cost, the total per year, and a short list of candidates to cancel with the yearly saving for each.
+
+${accountsContext()}`,
+      ),
+  );
+
+  server.registerPrompt(
+    "unusual-transactions",
+    {
+      title: "Unusual transactions",
+      description: "Large, duplicated or first-time transactions in a recent window compared to the months before.",
+      argsSchema: { days: z.string().optional().describe("Window in days, default 30") },
+    },
+    ({ days }) =>
+      text(
+        `Look for unusual transactions in the last ${days ?? "30"} days.
+
+1. Call list_accounts, then for each current account get_transactions for the last ${days ?? "30"} days and, for comparison, the 90 days before that.
+2. Report: single debits far larger than that counterparty's usual amount or than my typical spending; possible duplicate charges (same counterparty, same amount, within three days); counterparties that never appeared in the comparison period; incoming payments that are not salary or transfers from my own accounts; pending transactions older than a week.
+3. For every item give date, account, counterparty, amount and a one-line reason it stood out. Skip anything that is clearly normal. If nothing is unusual, say so in one sentence.
+
+${accountsContext()}`,
+      ),
+  );
+  server.registerPrompt(
+    "build-budget",
+    {
+      title: "Build a budget",
+      description: "Turn the last months of real spending into a monthly budget per category, with a savings target and the levers that get there.",
+      argsSchema: {
+        months: z.string().optional().describe("Months of history to base it on, default 3"),
+        savings_target: z.string().optional().describe("Amount or percentage of income to save each month, optional"),
+      },
+    },
+    ({ months, savings_target }) =>
+      text(
+        `Build me a monthly budget from my real spending over the last ${months ?? "3"} full months${savings_target ? `, aiming to save ${savings_target} per month` : ""}.
+
+1. Call list_accounts. Use the current accounts; note loans and mortgages separately.
+2. Call get_transactions for each current account over the whole period (follow continuation keys). Exclude transfers between my own accounts (same amount, opposite sign, within two days, across two of my accounts).
+3. Work out monthly income (salary and other regular credits) and categorise spending. Use a categorisation skill or rules file if one is available; otherwise sensible categories (housing, utilities, groceries, eating out, transport, subscriptions, shopping, health, kids, travel, insurance, other).
+4. For each category give the monthly average and the range, and mark it fixed (rent, mortgage, insurance, subscriptions) or variable. Add a monthly reserve for bills that come quarterly or yearly.
+5. Propose the budget: fixed items at their actual level, variable items at a realistic target, and show what the total leaves for saving against income. If a savings target was given and the numbers do not reach it, say which two or three variable categories would have to move, and by how much.
+6. Present it as one table (category, average, proposed budget, fixed or variable), then the totals: income, budget, saving per month. Whole numbers in the account currency.
+7. Offer two follow-ups: create_watch on the everyday account with a balance floor, and turning the budget into an artifact page that I can check against each month.
+
+${accountsContext()}`,
+      ),
+  );
+}

package/src/server.ts

@@ -0,0 +1,16 @@
+// HTTP entry point for a hosted deployment: OAuth + /mcp + bank callback + status page.
+import { createServer as createHttpsServer } from "node:https";
+import { createServer as createHttpServer } from "node:http";
+import { config, setupProblems, tlsOptions } from "./config.ts";
+import { createApp } from "./app.ts";
+import { setupAvailable } from "./setup.ts";
+
+const app = createApp({ remote: true });
+const tls = tlsOptions();
+const httpServer = tls ? createHttpsServer(tls, app) : createHttpServer(app);
+httpServer.listen(config.port, () => {
+  console.log(`[bank ${new Date().toISOString()}] listening on ${tls ? "https" : "http"}://0.0.0.0:${config.port}, public URL ${config.baseUrl}`);
+  const problems = setupProblems();
+  if (problems.length) console.log(`[bank] ${setupAvailable() ? `not configured yet: open ${config.baseUrl} to finish setup` : "not configured:"}`, problems);
+  else app.startWatcherOnce();
+});

package/src/setup.ts

@@ -0,0 +1,46 @@
+// First-run setup: takes the application id, the key file and a password,
+// validates them and stores them in the data directory. Only reachable while
+// the server has no working configuration.
+import { createPrivateKey } from "node:crypto";
+import { config, looksLikeUuid, saveKeyFile, saveSettings } from "./config.ts";
+import { hashPassword } from "./auth.ts";
+import { resetKeyCache } from "./enablebanking.ts";
+
+export interface SetupInput {
+  app_id?: string;
+  pem?: string;
+  password?: string;
+  password2?: string;
+  country?: string;
+}
+
+export function setupAvailable(): boolean {
+  const hasPassword = config.localMode || Boolean(config.adminPasswordHash || config.adminPassword);
+  return !config.lockedByEnv && !(config.appId && (config.privateKey || config.privateKeyPath) && hasPassword);
+}
+
+/** Returns null on success, otherwise a message for the form. */
+export function applySetup(input: SetupInput): string | null {
+  const appId = (input.app_id ?? "").trim();
+  const pem = (input.pem ?? "").trim();
+  const password = input.password ?? "";
+  const country = (input.country ?? "").trim().toUpperCase();
+
+  if (!looksLikeUuid.test(appId)) return "The application id should be a UUID like 8d3f6c2a-1b4e-4f7a-9c2d-5e6f7a8b9c0d. It is shown on the application in the Enable Banking Control Panel.";
+  if (!pem.includes("PRIVATE KEY")) return "That does not look like the key file. Choose the .pem file that downloaded when you registered the application.";
+  try {
+    createPrivateKey(pem);
+  } catch {
+    return "The key file could not be read as a private key.";
+  }
+  if (!config.localMode) {
+    if (password.length < 12) return "Use a password of at least 12 characters. It is the only thing between the internet and your accounts.";
+    if (password !== input.password2) return "The two passwords do not match.";
+  }
+  if (country && !/^[A-Z]{2}$/.test(country)) return "Country should be a two-letter code such as DK.";
+
+  saveKeyFile(pem);
+  saveSettings({ app_id: appId, admin_password_hash: config.localMode ? undefined : hashPassword(password), country: country || undefined, setup_completed: new Date().toISOString() });
+  resetKeyCache();
+  return null;
+}

package/src/stdio.ts

@@ -0,0 +1,15 @@
+// Local entry point for Claude Desktop, Claude Code, Cursor and other stdio
+// MCP clients. No OAuth: whoever can run this process can already read the
+// data directory. Nothing may write to stdout except the transport.
+process.env.BANKMCP_LOCAL ??= "1";
+const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
+const { createServer } = await import("./mcp.ts");
+const { isConfigured } = await import("./config.ts");
+const { ensureLocalServer } = await import("./local.ts");
+
+// The browser-facing side (setup page, bank redirect) runs on localhost over
+// https and starts with the process, so the redirect URL is always reachable.
+ensureLocalServer().catch((err) => console.error("[bank] could not start the local server:", err.message));
+if (!isConfigured()) console.error("[bank] not configured yet: ask your assistant anything and it will point you to the setup page");
+
+await createServer().connect(new StdioServerTransport());