Mortgage MCP Server

Mortgage MCP Server - lakáshitel igénylési folyamat

Node.js alapú MCP (Model Context Protocol) szerver, amely egy lakáshitel-ügyintézési folyamatot demonstrál UI widgetek és MCP toolok segítségével.

A projekt célja:

• lakáshitel adatok bekérése,
• banki ajánlatok megjelenítése,
• bankfiók kiválasztása,
• időpontfoglalás.

⚠️ A rendszer mock adatokkal működik, nem kapcsolódik valódi banki rendszerekhez.

Funkciók

• Lakáshitel űrlap (Mortgage Intake Form)
• Banki ajánlatok listázása
• Ajánlat kiválasztása
• Bankfiók kiválasztás település alapján
• Időpontfoglalás
• MCP-kompatibilis tool és resource API

Technológiai stack

• Node.js (ESM)
• Express
• @modelcontextprotocol/sdk
• Zod (schema validáció)
• HTML, CSS, Javascript frontend

Telepítés

npm install

Környezeti változók

.env fájl (opcionális):

PORT=3002
DOMAIN=localhost

Indítás

npm run start

MCP endpoint:

POST http://localhost:3002/mcp

Projekt struktúra

.
├── index.js
├── assets/
│   ├── mortgage-intake-form.html
│   └── branch-selector.html
├── mock_data/
│   ├── offers.js
│   ├── branches.js
│   └── appointments.js
└── README.md

UI Widgetek (MCP Resources)

Mortgage Intake Form

• Resource ID: mortgage-intake-form
• templateUri: ui://widget/mortgage-intake-form.html
• Mime type: text/html+skybridge
• Cél: felhasználó kitölti a hitel alapadatait, majd ajánlatokat kér le.

Branch Selector

• Resource ID: branch-selector
• templateUri: ui://widget/branch-selector.html
• Mime type: text/html+skybridge
• Cél: kiválasztott bankhoz bankfiókok listázása, majd időpontok lekérése és kiválasztása.

MCP Toolok

mortgage-intake-form

• Leírás: Megnyitja a lakáshitel űrlap widgetet.
• Input schema: data: record (GenericInputSchema)
• Output schema: { data: any | null } (MortgageIntakeOutputSchema)
• Megjegyzés: A form kitöltése után a felhasználó az "Ajánlatok megtekintése" gombra kattintva menti el a rögzített adatokat. A widget meghívja a mortgage-offer-list tool-t, ami alapján a talált hitelajánlatok megjelennek a form-ban.

loan-save-intake-data

• Leírás: A widgetből érkező űrlapadatokat “elmenti” és visszaadja a modellnek.
• Input: { data: intakeFormData | null }
• Output: { data: intakeFormData | null }

intakeFormData mezők (Zod):

• propertyValue?: number
• downPayment?: number
• loanAmount?: number
• maxMonthlyPayment?: number
• termYears?: number
• incomeType?: string | null
• netIncome?: number
• hasExistingLoans?: boolean
• existingLoansMonthly?: number
• purpose?: string

mortgage-offer-list

• Leírás: Ajánlatok szűrése/listázása a megadott paraméterek alapján.
• Input: intakeFormData | null (a fenti séma)
• Output: { offers: Offer[] }

Offer séma:

• bank: string
• rate: number (kamat %)
• thm: number (THM %)
• monthly: number (havi törlesztő, Ft, int, >=0)
• term: number (futamidő év, int, >0)

*Működés röviden:* Ha van termYears, akkor csak az adott futamidejű ajánlatokat adja,majd havi törlesztő szerint növekvőbe rendezi,a top 5 találtatot visszaadja. A felhasználó kiválasztja az egyik bank ajánlatát, amire egy sendFollowUpMessage üzenetben megkapja az llm a választott bank ajánlatának adatait. Az llm kiírja, hogy milyen adatokat kapott meg és kiírja a felhasználónak, hogy abban az esetben, ha tovább szeretne menni a bankválasztásra és időpontfoglalásra, írja meg, hogy melyik településen él, ezáltal a hozzá közel található bankfiókok fognak visszaérkezni.

branch-selector

• Leírás: A kiválasztott bank fiókjait listázza, és location alapján előre sorolja a településben szereplő címeket.

• Input:`

{ "data": { "selectedBank": "Példa Bank", "location": "Budapest" } } `

• Output: { branches: Branch[] }

Branch séma:

• bank: string
• address: string
• hours: string
• lat: number
• lng: number

*Rendezési logika (location):* Előre kerülnek azok a címek, amelyek address mezője tartalmazza a location szöveget (case-insensitive),utána jön a többi.

appointment-times

• Leírás: Elérhető időpontok listázása.
• Input:`{

"data": { "bank": "OTP Bank", "branchAddress": "1051 Budapest, Nádor utca 21." } }`

• Output: { appointments: Appointment[] }
• Appointment séma:

- date: string (pl. „2025. december 15. (hétfő)”) - time: string (pl. „09:30”)

Widget működés – felhasználói flow

A) Lakáshitel űrlap (mortgage-intake-form)

1. Lakáshitel adatok megadása

Felhasználó kitölti a mezőket (ingatlan érték, önerő, hitelösszeg, futamidő, jövedelmi adatok, stb.).

1. Ajánlatok megtekintése

Submit után a widget: meghívja loan-save-intake-data tool-t, majd meghívja mortgage-offer-list tool-t az elmentett adatokkal, és kirendereli az ajánlatkártyákat.

1. Bank ajánlatának kiválasztása

„Ezt választom” gomb: a widget follow-up üzenetet küld, ami a következő lépésként a bankfiók-választást kéri (branch-selector meghívására terelve).

B) Bankfiók + időpont (branch-selector)

1. Bankfiók kiválasztása

A tool outputjából megkapott branches listát a widget kártyákban megjeleníti.

1. Időpont kiválasztása

Bankfiók kiválasztása után a widget meghívja az appointment-times tool-t, és kirendereli az időpontokat.

1. Foglalás megerősítése

Időpont kiválasztásakor follow-up üzenetet küld a chatnek, hogy erősítse meg a foglalást és írja le a teendőket.

Mock adatok

• mock_data/offers.js – banki ajánlatok
• mock_data/branches.js – bankfiókok
• mock_data/appointments.js – időpontok