mcp-hypotheken-berekenen

Instructions

Implementation Reference

• src/index.ts:713-764 (handler)

  The primary handler function for the 'opzet_hypotheek_uitgebreid' tool. It normalizes and validates input arguments, constructs the payload for the external Replit API, makes the API call, logs success, and formats the response using formatResponse.
  async function handleOpzetUitgebreid(request: any): Promise<ToolResponse> { const rawArgs = requireArguments<OpzetUitgebreidArguments>(request); const normalizedArgs = rawArgs.is_doorstromer ? (normalizeOpzetDoorstromerArgs(rawArgs) as OpzetUitgebreidArguments) : (normalizeOpzetAanvragerShape(rawArgs) as OpzetUitgebreidArguments); const logger = createLogger(normalizedArgs.session_id); const aanvrager = requireOpzetAanvrager(normalizedArgs); validateOpzetAanvrager(aanvrager); if (normalizedArgs.is_doorstromer && normalizedArgs.bestaande_hypotheek) { validateBestaandeHypotheek(normalizedArgs.bestaande_hypotheek); } enforceRateLimit(normalizedArgs.session_id); const payload: any = { aanvrager: mapOpzetAanvrager(aanvrager), nieuwe_woning: { waarde_woning: normalizedArgs.nieuwe_woning.waarde_woning, bedrag_verbouwen: normalizedArgs.nieuwe_woning.bedrag_verbouwen ?? 0, bedrag_verduurzamen: normalizedArgs.nieuwe_woning.bedrag_verduurzamen ?? 0, kosten_percentage: normalizedArgs.nieuwe_woning.kosten_percentage ?? 0.05, energielabel: normalizeEnergielabel(normalizedArgs.nieuwe_woning.energielabel || ''), }, }; if (normalizedArgs.is_doorstromer && normalizedArgs.waarde_huidige_woning && normalizedArgs.bestaande_hypotheek) { payload.bestaande_hypotheek = { waarde_huidige_woning: normalizedArgs.waarde_huidige_woning, leningdelen: normalizedArgs.bestaande_hypotheek.leningdelen, }; } const maatwerk = (normalizedArgs as any).nieuwe_hypotheek ?? (normalizedArgs as any).nieuwe_lening; const nieuweLening = buildNieuweLeningPayload(maatwerk); if (nieuweLening) { payload.nieuwe_lening = nieuweLening; } if (normalizedArgs.session_id) { payload.session_id = normalizedArgs.session_id; } const apiClient = getApiClient(); const { data } = await apiClient.post( REPLIT_API_URL_OPZET, payload, { correlationId: normalizedArgs.session_id } ); logger.info('Toolcall succesvol', { tool: 'opzet_hypotheek_uitgebreid' }); return successResponse(formatResponse(data, "opzet_hypotheek_uitgebreid")); }
• src/index.ts:766-774 (registration)

  Registration of the tool handler in the TOOL_HANDLERS object, mapping 'opzet_hypotheek_uitgebreid' to its handler function.
  const TOOL_HANDLERS: Record<string, ToolHandler> = { bereken_hypotheek_starter: handleBerekenStarter, bereken_hypotheek_doorstromer: handleBerekenDoorstromer, bereken_hypotheek_uitgebreid: handleBerekenUitgebreid, haal_actuele_rentes_op: handleActueleRentes, opzet_hypotheek_starter: handleOpzetStarter, opzet_hypotheek_doorstromer: handleOpzetDoorstromer, opzet_hypotheek_uitgebreid: handleOpzetUitgebreid, };
• src/index.ts:940-1097 (schema)

  The tool definition including name, description, and detailed inputSchema (JSON Schema) for validation and documentation in the MCP tools list.
  { name: "opzet_hypotheek_uitgebreid", description: `GEAVANCEERDE opzet hypotheek berekening met VOLLEDIGE controle over alle parameters. Gebruik deze variant alleen wanneer er een concrete woning is én de gebruiker/adviseur expliciet scenario’s wil tweaken (andere rentes, looptijden, specifieke nieuwe leningdelen). Voor snelle beantwoording zonder maatwerk blijft u bij opzet_hypotheek_starter of opzet_hypotheek_doorstromer. **Output bevat alles van de starter/doorstromer tools, plus:** - Mogelijkheid om elk leningdeel handmatig te definiëren - Custom rentepercentages, looptijden en rentevast periodes - NHG, energielabel en verbouwing/duurzaamheidsbudget in één scenario - Volledige balans check en praktische toelichtingen Gebruik deze tool alleen wanneer afwijkende parameters nodig zijn; anders de specifieke starter/doorstromer varianten gebruiken. **Doorstromer invoerbeleid:** - Vraag óók hier: "Wilt u een snelle globale berekening (met een samenvatting van uw hypotheek) of een detailberekening waarbij u alle leningdelen invoert?" - Snelle route → één samenvattend leningdeel (totale schuld, gemiddelde rente/looptijd, optionele maandlast). - Detailroute → volledige lijst leningdelen met de exacte waarden per deel. Kopieer deze rechtstreeks in de leningdelen array.`, inputSchema: { type: "object", properties: { aanvrager: aanvragerSchema, is_doorstromer: { type: "boolean", description: "Is dit een doorstromer met bestaande woning en hypotheek?", }, waarde_huidige_woning: { type: "number", description: "OPTIONEEL - Alleen voor doorstromers: huidige woningwaarde in euro's", }, bestaande_hypotheek: { type: "object", description: "OPTIONEEL - Alleen voor doorstromers: gegevens van de bestaande hypotheek.", properties: { leningdelen: { type: "array", items: { type: "object", properties: { huidige_schuld: { type: "number", description: "Restschuld in euro's", }, huidige_rente: { type: "number", description: "Rente als decimaal (bijv. 0.041 voor 4.1%)", }, resterende_looptijd_in_maanden: { type: "number", description: "Resterende looptijd in MAANDEN", }, rentevasteperiode_maanden: { type: "number", description: "Resterende rentevaste periode in MAANDEN", }, hypotheekvorm: { type: "string", description: "Type hypotheek", enum: ["annuiteit", "lineair", "aflossingsvrij"], }, }, required: ["huidige_schuld", "huidige_rente", "resterende_looptijd_in_maanden", "rentevasteperiode_maanden", "hypotheekvorm"], }, }, }, required: ["leningdelen"], }, nieuwe_woning: { type: "object", description: "Gegevens van de nieuwe woning die gekocht wordt", properties: { waarde_woning: { type: "number", description: "Koopsom van de nieuwe woning in euro's", }, bedrag_verbouwen: { type: "number", description: "OPTIONEEL - Geschatte kosten voor verbouwing/meerwerk in euro's.", default: 0, }, bedrag_verduurzamen: { type: "number", description: "OPTIONEEL - Geschatte kosten voor verduurzaming in euro's.", default: 0, }, kosten_percentage: { type: "number", description: "OPTIONEEL - Koperkosten als decimaal (bijv. 0.05 voor 5%). Standaard: 0.05", default: 0.05, }, energielabel: { type: "string", description: "OPTIONEEL - Energielabel van de nieuwe woning.", enum: ["A++++ (met garantie)", "A++++", "A+++", "A++", "A+", "A", "B", "C", "D", "E", "F", "G"], }, }, required: ["waarde_woning"], }, nieuwe_lening: { type: "object", description: "OPTIONEEL - Specifieke parameters voor de nieuwe lening. Gebruik deze sectie om looptijd, rentevast periode, NHG of renteklassen aan te passen.", properties: { looptijd_jaren: { type: "number", description: "Looptijd van de hypotheek in JAREN. Standaard: 30 jaar. Voorbeelden: 20, 25, 30", default: 30, }, rentevast_periode_jaren: { type: "number", description: "Rentevaste periode in JAREN. Standaard: 10 jaar. Voorbeelden: 5, 10, 15, 20", default: 10, }, nhg: { type: "boolean", description: "Nationale Hypotheek Garantie aanvragen? Standaard: false", default: false, }, renteklassen: { type: "array", description: "OPTIONEEL - Custom renteklassen met specifieke LTV-grenzen en rentepercentages. Alleen invullen als je specifieke renteklassen wilt definiëren.", items: { type: "object", properties: { naam: { type: "string", description: "Naam van de renteklasse (bijv. 'NHG 0-200', 'Niet-NHG 75-90')", }, lowerbound_ltv_pct: { type: "number", description: "Ondergrens LTV in procenten (bijv. 0.0, 75.0)", }, higherbound_ltv_pct: { type: "number", description: "Bovengrens LTV in procenten (bijv. 75.0, 200.0)", }, nhg: { type: "boolean", description: "Is dit een NHG renteklasse?", }, rente_jaarlijks_pct: { type: "number", description: "Rentepercentage als getal (bijv. 3.2 voor 3.2%, 4.0 voor 4.0%)", }, }, required: ["naam", "lowerbound_ltv_pct", "higherbound_ltv_pct", "nhg", "rente_jaarlijks_pct"], }, }, }, }, session_id: { type: "string", description: "OPTIONEEL - Sessie ID voor het traceren van de conversatie. Haal deze waarde uit de n8n chat trigger: 'When chat message received' -> sessionId variabele.", }, }, required: [ "aanvrager", "nieuwe_woning", ], }, },
• src/index.ts:777-1100 (registration)

  MCP server registration of the tool in the listTools endpoint, exposing it to clients with schema and description.
  server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ // Tool 1: Starters - Simpele berekening { name: "bereken_hypotheek_starter", description: `Maximale hypotheek voor starters ZONDER concrete woning. Gebruik deze tool alleen wanneer de gebruiker zich oriënteert ("Wat kan ik lenen?") en er nog geen koopsom/adres bekend is. Zodra de gebruiker een specifiek huis of biedprijs noemt moet u overschakelen naar de opzet-hypotheek tools.`, inputSchema: { type: "object", description: `Gebruik basisintakevelden; zie ${OPZET_GUIDE_URI} voor detaildefinities.`, properties: { ...baseIntakeProperties, session_id: { type: "string", description: "Optioneel sessie-ID vanuit n8n (voor logging).", }, }, required: baseIntakeRequired, }, }, // Tool 2: Doorstromers - Met bestaande hypotheek { name: "bereken_hypotheek_doorstromer", description: `Maximale hypotheek voor doorstromers ZONDER concrete woning. Gebruik dit wanneer de gebruiker wil weten hoeveel ruimte er is om straks te verhuizen maar er nog geen koopsom of specifieke woning op tafel ligt. Zodra een concreet huis ter sprake komt schakelt u over op de opzet-hypotheek tools. Alle regels uit het doorstromerbeleid gelden ook voor de uitgebreide tool: ${DOORSTROMER_OUTPUT_GUIDANCE}`, inputSchema: { type: "object", description: `Gebruik basisintakevelden plus huidige woninginformatie; zie ${OPZET_GUIDE_URI} voor detaildefinities.`, properties: { ...baseIntakeProperties, waarde_huidige_woning: { type: "number", description: "Huidige marktwaarde van de bestaande woning.", }, bestaande_hypotheek: { ...bestaandeHypotheekSchema, }, session_id: { type: "string", description: "Optioneel sessie-ID vanuit n8n (voor logging).", }, }, required: [ ...baseIntakeRequired, "waarde_huidige_woning", "bestaande_hypotheek", ], }, }, // Tool 3: Uitgebreid - Alle parameters configureerbaar { name: "bereken_hypotheek_uitgebreid", description: `Maximale hypotheek – uitgebreide variant. Gebruik dit alleen wanneer er nog GEEN concrete woning is, maar de gebruiker/adviseur expliciet met parameters wil spelen (bijv. andere rentevast-periodes, custom renteklassen, scenariovergelijkingen). Voor een concrete woning altijd de opzet-tools gebruiken. Zodra u dit tool voor een doorstromer inzet (is_doorstromer=true of bestaande_hypotheek ingevuld), gelden dezelfde regels als bij de standaard doorstromer-tool: ${DOORSTROMER_OUTPUT_GUIDANCE}`, inputSchema: { type: "object", description: `Alle velden zijn optioneel bovenop de basisintake; zie ${OPZET_GUIDE_URI} voor velduitleg en defaults.`, properties: { ...baseIntakeProperties, is_doorstromer: { type: "boolean", description: "Geeft aan of de aanvrager een doorstromer is.", }, waarde_huidige_woning: { type: "number", description: "Optionele huidige woningwaarde in euro's.", }, bestaande_hypotheek: { ...bestaandeHypotheekSchema, }, nieuwe_woning: { ...nieuweWoningSchema, }, nieuwe_hypotheek: { type: "object", description: `Optionele maatwerk leningparameters (looptijd, rentevast, rente). Detailuitleg: ${OPZET_GUIDE_URI}.`, }, nieuwe_lening: { type: "object", description: `Optionele structuur voor looptijd/rentevast/NHG en renteklassen (detailuitleg: ${OPZET_GUIDE_URI}).`, }, session_id: { type: "string", description: "Optioneel sessie-ID vanuit n8n (voor logging).", }, }, required: baseIntakeRequired, }, }, // Tool 4: Actuele rentes ophalen { name: "haal_actuele_rentes_op", description: "Haalt actuele hypotheekrentes op per rentevaste periode. Output: overzicht met NHG- en niet-NHG-tarieven.", inputSchema: { type: "object", properties: {}, required: [], }, }, // Tool 5: Opzet hypotheek - Starters { name: "opzet_hypotheek_starter", description: `Opzet-berekening voor starters met een CONCRETE woning. Gebruik dit zodra de gebruiker een huis/koopprijs noemt en wil weten “kan ik deze woning kopen, hoe ziet de financiering eruit?”. Voor louter oriëntatie zonder woning blijft u bij de maximale-hypotheek tools. Dit is de standaardvariant; kies opzet_hypotheek_uitgebreid wanneer de gebruiker expliciet scenario’s/leningdelen wil tweaken.`, inputSchema: { type: "object", description: `Gebruik basisintake plus woninginfo; zie ${OPZET_GUIDE_URI} voor detailvelden en defaults.`, properties: { aanvrager: aanvragerSchema, nieuwe_woning: { ...nieuweWoningSchema, }, session_id: { type: "string", description: "Optioneel sessie-ID vanuit n8n (voor logging).", }, }, required: [ "aanvrager", "nieuwe_woning", ], }, }, // Tool 6: Opzet hypotheek - Doorstromers { name: "opzet_hypotheek_doorstromer", description: `Opzet-berekening voor doorstromers met een CONCRETE nieuwe woning. Gebruik dit zodra er een koopprijs/verbouwing bekend is; hiermee ziet de gebruiker exact hoe bestaand en nieuw samenkomen. Voor algemene verhuis-oriëntatie zonder specifieke woning gebruikt u de maximale-hypotheek tools. **Invoerbeleid bestaande hypotheek (verplicht expliciet vragen):** - Stel altijd de vraag: "Wilt u een snelle globale berekening (met een samenvatting van uw hypotheek) of een detailberekening waarbij u alle leningdelen invoert?" - Bij snelle globale berekening: laat de gebruiker één samenvattende set waarden geven (totale schuld, gemiddelde rente, resterende looptijd, optioneel huidige maandlast) en vul hiermee één leningdeel. - Bij detailberekening: laat de gebruiker alle leningdelen kopiëren/plakken (hoofdsom, rente, looptijd, rentevast, hypotheekvorm) en vul de leningdelen-array één-op-één.`, inputSchema: { type: "object", description: `Gebruik basisintake, huidige woning en bestaande leningdelen; zie ${OPZET_GUIDE_URI} voor detailvelden en defaults.`, properties: { aanvrager: aanvragerSchema, waarde_huidige_woning: { type: "number", description: "Marktwaarde van de huidige woning.", }, bestaande_hypotheek: { ...bestaandeHypotheekSchema, }, nieuwe_woning: { ...nieuweWoningSchema, }, session_id: { type: "string", description: "Optioneel sessie-ID vanuit n8n (voor logging).", }, }, required: [ "aanvrager", "waarde_huidige_woning", "bestaande_hypotheek", "nieuwe_woning", ], }, }, // Tool 7: Opzet hypotheek - Uitgebreid { name: "opzet_hypotheek_uitgebreid", description: `GEAVANCEERDE opzet hypotheek berekening met VOLLEDIGE controle over alle parameters. Gebruik deze variant alleen wanneer er een concrete woning is én de gebruiker/adviseur expliciet scenario’s wil tweaken (andere rentes, looptijden, specifieke nieuwe leningdelen). Voor snelle beantwoording zonder maatwerk blijft u bij opzet_hypotheek_starter of opzet_hypotheek_doorstromer. **Output bevat alles van de starter/doorstromer tools, plus:** - Mogelijkheid om elk leningdeel handmatig te definiëren - Custom rentepercentages, looptijden en rentevast periodes - NHG, energielabel en verbouwing/duurzaamheidsbudget in één scenario - Volledige balans check en praktische toelichtingen Gebruik deze tool alleen wanneer afwijkende parameters nodig zijn; anders de specifieke starter/doorstromer varianten gebruiken. **Doorstromer invoerbeleid:** - Vraag óók hier: "Wilt u een snelle globale berekening (met een samenvatting van uw hypotheek) of een detailberekening waarbij u alle leningdelen invoert?" - Snelle route → één samenvattend leningdeel (totale schuld, gemiddelde rente/looptijd, optionele maandlast). - Detailroute → volledige lijst leningdelen met de exacte waarden per deel. Kopieer deze rechtstreeks in de leningdelen array.`, inputSchema: { type: "object", properties: { aanvrager: aanvragerSchema, is_doorstromer: { type: "boolean", description: "Is dit een doorstromer met bestaande woning en hypotheek?", }, waarde_huidige_woning: { type: "number", description: "OPTIONEEL - Alleen voor doorstromers: huidige woningwaarde in euro's", }, bestaande_hypotheek: { type: "object", description: "OPTIONEEL - Alleen voor doorstromers: gegevens van de bestaande hypotheek.", properties: { leningdelen: { type: "array", items: { type: "object", properties: { huidige_schuld: { type: "number", description: "Restschuld in euro's", }, huidige_rente: { type: "number", description: "Rente als decimaal (bijv. 0.041 voor 4.1%)", }, resterende_looptijd_in_maanden: { type: "number", description: "Resterende looptijd in MAANDEN", }, rentevasteperiode_maanden: { type: "number", description: "Resterende rentevaste periode in MAANDEN", }, hypotheekvorm: { type: "string", description: "Type hypotheek", enum: ["annuiteit", "lineair", "aflossingsvrij"], }, }, required: ["huidige_schuld", "huidige_rente", "resterende_looptijd_in_maanden", "rentevasteperiode_maanden", "hypotheekvorm"], }, }, }, required: ["leningdelen"], }, nieuwe_woning: { type: "object", description: "Gegevens van de nieuwe woning die gekocht wordt", properties: { waarde_woning: { type: "number", description: "Koopsom van de nieuwe woning in euro's", }, bedrag_verbouwen: { type: "number", description: "OPTIONEEL - Geschatte kosten voor verbouwing/meerwerk in euro's.", default: 0, }, bedrag_verduurzamen: { type: "number", description: "OPTIONEEL - Geschatte kosten voor verduurzaming in euro's.", default: 0, }, kosten_percentage: { type: "number", description: "OPTIONEEL - Koperkosten als decimaal (bijv. 0.05 voor 5%). Standaard: 0.05", default: 0.05, }, energielabel: { type: "string", description: "OPTIONEEL - Energielabel van de nieuwe woning.", enum: ["A++++ (met garantie)", "A++++", "A+++", "A++", "A+", "A", "B", "C", "D", "E", "F", "G"], }, }, required: ["waarde_woning"], }, nieuwe_lening: { type: "object", description: "OPTIONEEL - Specifieke parameters voor de nieuwe lening. Gebruik deze sectie om looptijd, rentevast periode, NHG of renteklassen aan te passen.", properties: { looptijd_jaren: { type: "number", description: "Looptijd van de hypotheek in JAREN. Standaard: 30 jaar. Voorbeelden: 20, 25, 30", default: 30, }, rentevast_periode_jaren: { type: "number", description: "Rentevaste periode in JAREN. Standaard: 10 jaar. Voorbeelden: 5, 10, 15, 20", default: 10, }, nhg: { type: "boolean", description: "Nationale Hypotheek Garantie aanvragen? Standaard: false", default: false, }, renteklassen: { type: "array", description: "OPTIONEEL - Custom renteklassen met specifieke LTV-grenzen en rentepercentages. Alleen invullen als je specifieke renteklassen wilt definiëren.", items: { type: "object", properties: { naam: { type: "string", description: "Naam van de renteklasse (bijv. 'NHG 0-200', 'Niet-NHG 75-90')", }, lowerbound_ltv_pct: { type: "number", description: "Ondergrens LTV in procenten (bijv. 0.0, 75.0)", }, higherbound_ltv_pct: { type: "number", description: "Bovengrens LTV in procenten (bijv. 75.0, 200.0)", }, nhg: { type: "boolean", description: "Is dit een NHG renteklasse?", }, rente_jaarlijks_pct: { type: "number", description: "Rentepercentage als getal (bijv. 3.2 voor 3.2%, 4.0 voor 4.0%)", }, }, required: ["naam", "lowerbound_ltv_pct", "higherbound_ltv_pct", "nhg", "rente_jaarlijks_pct"], }, }, }, }, session_id: { type: "string", description: "OPTIONEEL - Sessie ID voor het traceren van de conversatie. Haal deze waarde uit de n8n chat trigger: 'When chat message received' -> sessionId variabele.", }, }, required: [ "aanvrager", "nieuwe_woning", ], }, }, ], }; });
• src/index.ts:465-522 (helper)

  Helper function used in the handler to construct the 'nieuwe_lening' payload from optional custom parameters like looptijd, rentevast, nhg, and renteklassen.
  function buildNieuweLeningPayload(raw: any): any | undefined { if (!raw || typeof raw !== 'object') { return undefined; } const payload: Record<string, unknown> = {}; const looptijdMaanden = raw.looptijd_maanden ?? (typeof raw.looptijd_jaren === 'number' ? raw.looptijd_jaren * 12 : undefined); if (looptijdMaanden) { payload.looptijd_maanden = looptijdMaanden; } const rentevastMaanden = raw.rentevaste_periode_maanden ?? (typeof raw.rentevast_periode_jaren === 'number' ? raw.rentevast_periode_jaren * 12 : undefined); if (rentevastMaanden) { payload.rentevaste_periode_maanden = rentevastMaanden; } if (raw.rente !== undefined) { payload.rente = raw.rente; } if (raw.hypotheekvorm) { payload.hypotheekvorm = raw.hypotheekvorm; } else if (raw.type) { payload.hypotheekvorm = raw.type; } if (raw.energielabel) { payload.energielabel = normalizeEnergielabel(raw.energielabel); } if (raw.nhg !== undefined) { payload.nhg = raw.nhg; } if (raw.ltv !== undefined) { let ltvValue: number | undefined; if (typeof raw.ltv === 'string') { const parsed = parseFloat(raw.ltv.replace('%', '')); ltvValue = Number.isFinite(parsed) ? parsed / 100 : undefined; } else if (typeof raw.ltv === 'number') { ltvValue = raw.ltv; } if (ltvValue !== undefined) { payload.ltv = ltvValue; } } if (Array.isArray(raw.renteklassen) && raw.renteklassen.length > 0) { payload.renteklassen = raw.renteklassen; } return Object.keys(payload).length > 0 ? payload : undefined; }