使用说明
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
| Változó | Leírás | Alapértelmezett |
|---|---|---|
| PORT | MCP szerver port | 3002 |
| DOMAIN | Widgetek domain engedélyezése | nincs |
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)
-
Lakáshitel adatok megadása Felhasználó kitölti a mezőket (ingatlan érték, önerő, hitelösszeg, futamidő, jövedelmi adatok, stb.).
-
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.
-
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)
-
Bankfiók kiválasztása A tool outputjából megkapott branches listát a widget kártyákban megjeleníti.
-
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.
-
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
