get_next_payment_date
Read-onlyIdempotent
Calculate next valid payment date for European countries, skipping weekends and public holidays. Supports rules like last working day of month for salary payments.
Instructions
Calculates the next valid payment date based on a reference date and a payment rule for a given European country, skipping weekends and national public holidays. Supports rules: 'last_working_day_of_month' (salary payment), 'first_working_day_of_month', 'nth_working_day' (e.g. 5th working day), 'next_working_day' (next business day after reference). Returns { country, reference_date, rule, result_date, notes }. Use when scheduling salary payments, invoice due dates, or any automated payment workflow that must avoid non-working days.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| country_code | Yes | Two-letter ISO country code. Example: 'PT', 'DE', 'FR' | |
| reference_date | Yes | Reference date in YYYY-MM-DD format. Example: '2026-01-31' | |
| rule | Yes | Payment rule to apply. | |
| n | No | For nth_working_day rule: which working day of the month. Example: 5 for 5th working day. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| country | No | ||
| reference_date | No | ||
| rule | No | ||
| result_date | No | ||
| error | No |
Implementation Reference
- index.js:762-773 (registration)Registration of the 'get_next_payment_date' tool using server.registerTool(), defining its description, inputSchema (country_code, reference_date, rule, optional n), outputSchema, and annotations.
// ── 24. Get Next Payment Date ── server.registerTool("get_next_payment_date", { description: "Calculates the next valid payment date based on a reference date and a payment rule for a given European country, skipping weekends and national public holidays. Supports rules: 'last_working_day_of_month' (salary payment), 'first_working_day_of_month', 'nth_working_day' (e.g. 5th working day), 'next_working_day' (next business day after reference). Returns { country, reference_date, rule, result_date, notes }. Use when scheduling salary payments, invoice due dates, or any automated payment workflow that must avoid non-working days.", inputSchema: { country_code: z.string().describe("Two-letter ISO country code. Example: 'PT', 'DE', 'FR'"), reference_date: z.string().describe("Reference date in YYYY-MM-DD format. Example: '2026-01-31'"), rule: z.enum(["last_working_day_of_month", "first_working_day_of_month", "next_working_day", "nth_working_day"]).describe("Payment rule to apply."), n: z.number().optional().describe("For nth_working_day rule: which working day of the month. Example: 5 for 5th working day.") }, outputSchema: { country: z.string().optional(), reference_date: z.string().optional(), rule: z.string().optional(), result_date: z.string().optional(), error: z.string().optional() }, annotations: { title: "Get Next Payment Date", readOnlyHint: true, idempotentHint: true, openWorldHint: false } }, async ({ country_code, reference_date, rule, n }) => { - index.js:773-830 (handler)Handler function for get_next_payment_date. Implements four payment rules: last_working_day_of_month, first_working_day_of_month, next_working_day, and nth_working_day, skipping weekends and national holidays for the given European country.
}, async ({ country_code, reference_date, rule, n }) => { const holidaysByCountry = { PT: ["01-01","04-25","05-01","06-10","08-15","10-05","11-01","12-01","12-08","12-25"], ES: ["01-01","01-06","05-01","08-15","10-12","11-01","12-06","12-08","12-25"], FR: ["01-01","05-01","05-08","07-14","08-15","11-01","11-11","12-25"], DE: ["01-01","05-01","10-03","12-25","12-26"], IT: ["01-01","01-06","04-25","05-01","06-02","08-15","11-01","12-08","12-25","12-26"], NL: ["01-01","04-27","05-05","12-25","12-26"], BE: ["01-01","05-01","07-21","08-15","11-01","11-11","12-25"], UK: ["01-01","12-25","12-26"], }; const code = country_code.toUpperCase(); const fixedHolidays = holidaysByCountry[code] || []; const isWorkingDay = (date) => { const dow = date.getDay(); const mmdd = `${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`; return dow !== 0 && dow !== 6 && !fixedHolidays.includes(mmdd); }; const ref = new Date(reference_date); if (isNaN(ref)) return { content: [{ type: "text", text: JSON.stringify({ error: "Invalid date format. Use YYYY-MM-DD" }) }] }; let resultDate; if (rule === "next_working_day") { const d = new Date(ref); d.setDate(d.getDate() + 1); while (!isWorkingDay(d)) d.setDate(d.getDate() + 1); resultDate = d.toISOString().split("T")[0]; } if (rule === "last_working_day_of_month") { const d = new Date(ref.getFullYear(), ref.getMonth() + 1, 0); // last day of month while (!isWorkingDay(d)) d.setDate(d.getDate() - 1); resultDate = d.toISOString().split("T")[0]; } if (rule === "first_working_day_of_month") { const d = new Date(ref.getFullYear(), ref.getMonth(), 1); while (!isWorkingDay(d)) d.setDate(d.getDate() + 1); resultDate = d.toISOString().split("T")[0]; } if (rule === "nth_working_day") { if (!n || n < 1) return { content: [{ type: "text", text: JSON.stringify({ error: "For nth_working_day rule, provide n >= 1" }) }] }; const d = new Date(ref.getFullYear(), ref.getMonth(), 1); let count = 0; while (count < n) { if (isWorkingDay(d)) count++; if (count < n) d.setDate(d.getDate() + 1); } resultDate = d.toISOString().split("T")[0]; } return { content: [{ type: "text", text: JSON.stringify({ country: code, reference_date, rule, n: n || null, result_date: resultDate }) }] }; }); - index.js:774-783 (helper)Helper data structure holidaysByCountry mapping country codes to arrays of fixed national public holidays (MM-DD format) for PT, ES, FR, DE, IT, NL, BE, UK.
const holidaysByCountry = { PT: ["01-01","04-25","05-01","06-10","08-15","10-05","11-01","12-01","12-08","12-25"], ES: ["01-01","01-06","05-01","08-15","10-12","11-01","12-06","12-08","12-25"], FR: ["01-01","05-01","05-08","07-14","08-15","11-01","11-11","12-25"], DE: ["01-01","05-01","10-03","12-25","12-26"], IT: ["01-01","01-06","04-25","05-01","06-02","08-15","11-01","12-08","12-25","12-26"], NL: ["01-01","04-27","05-05","12-25","12-26"], BE: ["01-01","05-01","07-21","08-15","11-01","11-11","12-25"], UK: ["01-01","12-25","12-26"], }; - index.js:788-792 (helper)Helper function isWorkingDay(date) that checks if a date is a working day (not Saturday/Sunday and not a fixed holiday) for the selected country.
const isWorkingDay = (date) => { const dow = date.getDay(); const mmdd = `${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`; return dow !== 0 && dow !== 6 && !fixedHolidays.includes(mmdd); }; - index.js:765-771 (schema)Input schema definition for get_next_payment_date using Zod: country_code (string), reference_date (string YYYY-MM-DD), rule (enum with four values), and optional n (number for nth_working_day rule).
inputSchema: { country_code: z.string().describe("Two-letter ISO country code. Example: 'PT', 'DE', 'FR'"), reference_date: z.string().describe("Reference date in YYYY-MM-DD format. Example: '2026-01-31'"), rule: z.enum(["last_working_day_of_month", "first_working_day_of_month", "next_working_day", "nth_working_day"]).describe("Payment rule to apply."), n: z.number().optional().describe("For nth_working_day rule: which working day of the month. Example: 5 for 5th working day.") }, outputSchema: { country: z.string().optional(), reference_date: z.string().optional(), rule: z.string().optional(), result_date: z.string().optional(), error: z.string().optional() },