nager-mcp 1.0.0 → 1.0.1

package/README.md

@@ -1,13 +1,41 @@
 # nager-mcp
 
-Fetch Nager.Date public holidays (keyless): countries, yearly holidays, upcoming holidays.
+Worldwide public holidays and long weekends - no API key.
 
 ## Tools
 
-- `list_countries` — Supported country codes.
-- `get_holidays` — Holidays for a year and country.
-- `next_holidays` — Next holidays for a country.
+- `list_countries` — Every country the public holiday API covers, with its two-letter code.
+- `country_info` — Official name, region and land borders for a country.
+- `get_holidays` — All public holidays for a country and year, with local and English names.
+- `next_holidays` — The next public holidays for a country, starting from today.
+- `worldwide_holidays` — The next public holidays around the world - useful for planning around other countries' closures.
+- `long_weekends` — Long weekends in a country and year, and whether a bridge day off is needed to get them.
+- `is_today_holiday` — Whether today is a public holiday in a country.
+- `regional_holidays` — Holidays that actually apply in one subdivision (US-CA, DE-BE, CA-ON): national days plus local ones.
+- `holiday_on_date` — Is one specific date a public holiday? Answers yes or no, with the previous and next holiday.
+- `compare_countries` — Shared, and country-specific, public holidays for two countries in one year.
 
-## Source
+## Setup
 
-[nager-mcp](https://github.com/mrfentmen/premium-mcps/tree/main/servers/nager-mcp)
+No setup. Holiday data comes from the public Nager.Date API.
+
+Part of [awesome-mcps](https://github.com/mrfentmen/awesome-mcps).
+
+<!-- paywall -->
+## Premium tools
+
+These tools need a license key:
+
+* `working_day_calendar`
+* `holiday_observance_audit`
+
+Buy a key at https://mcp-marketplace.io/server/io-github-mrfentmen-nager-mcp and set it in your MCP client config:
+
+```json
+"env": { "MCP_LICENSE_KEY": "mcp_live_..." }
+```
+
+The key is checked against MCP Marketplace, cached for 24 hours, and keeps
+working offline once one check has succeeded. Every other tool on this server
+stays free.
+<!-- /paywall -->

package/dist/api.d.ts

@@ -1,7 +1,70 @@
+/**
+ * Nager.Date public holiday API client, keyless.
+ * Covers 100+ countries: holidays, next holidays, long weekends.
+ */
 export declare class NagerError extends Error {
     constructor(message: string);
 }
 export declare function errorMessage(e: unknown): string;
-export declare function listCountries(): Promise<string>;
-export declare function getHolidays(year: string, country: string): Promise<string>;
-export declare function nextHolidays(country: string): Promise<string>;
+export interface Country {
+    countryCode: string;
+    name: string;
+}
+export interface Holiday {
+    date: string;
+    localName: string;
+    name: string;
+    countryCode: string;
+    global?: boolean;
+    counties?: string[] | null;
+    types?: string[];
+}
+export interface CountryInfo {
+    commonName: string;
+    officialName: string;
+    countryCode: string;
+    region: string;
+    borders?: Array<{
+        commonName: string;
+        officialName: string;
+        countryCode: string;
+    }> | null;
+}
+export interface LongWeekend {
+    startDate: string;
+    endDate: string;
+    dayCount: number;
+    needBridgeDay: boolean;
+    bridgeDays?: string[];
+}
+export declare function countries(): Promise<Country[]>;
+export declare function countryInfo(country: string): Promise<CountryInfo>;
+export declare function holidays(year: string, country: string): Promise<Holiday[]>;
+export declare function nextHolidays(country: string): Promise<Holiday[]>;
+export declare function worldwideHolidays(): Promise<Holiday[]>;
+export declare function longWeekends(year: string, country: string): Promise<LongWeekend[]>;
+export type TodayResult = {
+    isHoliday: true;
+    holiday: Holiday;
+} | {
+    isHoliday: false;
+};
+export declare function isTodayHoliday(country: string): Promise<TodayResult>;
+export declare function normaliseCountry(country: string): string;
+export declare function formatHoliday(h: Holiday): string;
+export declare function formatHolidays(list: Holiday[], title: string): string;
+export declare function formatCountryInfo(info: CountryInfo): string;
+export declare function formatLongWeekends(list: LongWeekend[], title: string): string;
+export declare function regionalHolidays(year: string, country: string, county: string): Promise<string>;
+export declare function holidayOnDate(date: string, country: string): Promise<string>;
+export declare function compareCountries(year: string, countryA: string, countryB: string): Promise<string>;
+/** Month by month working-day arithmetic for one country and year. */
+export declare function workingDayCalendar(args: {
+    country: string;
+    year: string;
+}): Promise<string>;
+/** Where each holiday lands, and what it does to the working week around it. */
+export declare function holidayObservanceAudit(args: {
+    country: string;
+    year: string;
+}): Promise<string>;

package/dist/api.js

@@ -1,3 +1,7 @@
+/**
+ * Nager.Date public holiday API client, keyless.
+ * Covers 100+ countries: holidays, next holidays, long weekends.
+ */
 export class NagerError extends Error {
     constructor(message) {
         super(message);
@@ -7,30 +11,364 @@ export class NagerError extends Error {
 export function errorMessage(e) {
     return e instanceof Error ? e.message : String(e);
 }
-const UA = { "User-Agent": "awesome-mcps/1.0" };
-async function get(path) {
+const UA = "mrfentmen-nager-mcp/1.0";
+const BASE = "https://date.nager.at/api/v3";
+let countriesCache = null;
+async function call(path) {
     let res;
     try {
-        res = await fetch("https://date.nager.at/api/v3" + path, {
-            headers: { ...UA, Accept: "application/json" },
-            signal: AbortSignal.timeout(25000),
+        res = await fetch(BASE + path, {
+            headers: { "User-Agent": UA, Accept: "application/json" },
+            signal: AbortSignal.timeout(20000),
         });
     }
     catch (e) {
-        throw new NagerError(`Network error: ${e.message}`);
+        throw new NagerError(`Could not reach date.nager.at: ${errorMessage(e)}`);
     }
+    const body = (await res.text()).slice(0, 200000);
+    if (res.status === 204 || res.status === 404)
+        return { status: res.status, body };
     if (!res.ok) {
-        const body = (await res.text()).slice(0, 300);
-        throw new NagerError(`HTTP ${res.status}: ${body}`);
+        throw new NagerError(`date.nager.at returned HTTP ${res.status}: ${body.slice(0, 200)}`);
     }
-    return (await res.text()).slice(0, 12000);
+    return { status: res.status, body };
 }
-export function listCountries() {
-    return get("/AvailableCountries");
+async function getJson(path) {
+    const { body } = await call(path);
+    if (!body)
+        throw new NagerError("date.nager.at returned an empty response.");
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        throw new NagerError("date.nager.at returned a non-JSON response.");
+    }
+}
+export async function countries() {
+    if (countriesCache)
+        return countriesCache;
+    countriesCache = await getJson("/AvailableCountries");
+    return countriesCache;
+}
+export async function countryInfo(country) {
+    const code = normaliseCountry(country);
+    return getJson(`/CountryInfo/${encodeURIComponent(code)}`);
+}
+export async function holidays(year, country) {
+    const y = normaliseYear(year);
+    const code = normaliseCountry(country);
+    return getJson(`/PublicHolidays/${y}/${encodeURIComponent(code)}`);
+}
+export async function nextHolidays(country) {
+    const code = normaliseCountry(country);
+    return getJson(`/NextPublicHolidays/${encodeURIComponent(code)}`);
+}
+export async function worldwideHolidays() {
+    return getJson("/NextPublicHolidaysWorldwide");
+}
+export async function longWeekends(year, country) {
+    const y = normaliseYear(year);
+    const code = normaliseCountry(country);
+    return getJson(`/LongWeekend/${y}/${encodeURIComponent(code)}`);
+}
+export async function isTodayHoliday(country) {
+    const code = normaliseCountry(country);
+    const { status, body } = await call(`/IsTodayPublicHoliday/${encodeURIComponent(code)}`);
+    if (status === 204)
+        return { isHoliday: false };
+    if (!body)
+        return { isHoliday: false };
+    try {
+        const parsed = JSON.parse(body);
+        const holiday = Array.isArray(parsed) ? parsed[0] : parsed;
+        return holiday && holiday.name ? { isHoliday: true, holiday } : { isHoliday: false };
+    }
+    catch {
+        return { isHoliday: false };
+    }
+}
+function normaliseYear(year) {
+    const y = year.trim();
+    if (!/^\d{4}$/.test(y))
+        throw new NagerError(`"${year}" is not a four-digit year.`);
+    const n = Number(y);
+    if (n < 1975 || n > 2100)
+        throw new NagerError(`Year ${n} is outside the supported range 1975-2100.`);
+    return y;
+}
+export function normaliseCountry(country) {
+    const c = country.trim().toUpperCase();
+    if (!/^[A-Z]{2}$/.test(c)) {
+        throw new NagerError(`"${country}" is not a two-letter country code - call list_countries for the list.`);
+    }
+    return c;
+}
+export function formatHoliday(h) {
+    const types = (h.types ?? []).join("/");
+    const scope = h.global === false ? "regional" : "national";
+    return `  ${h.date}  ${h.localName}${h.name !== h.localName ? ` (${h.name})` : ""} - ${types || scope}`;
 }
-export function getHolidays(year, country) {
-    return get(`/PublicHolidays/${encodeURIComponent(year)}/${encodeURIComponent(country)}`);
+export function formatHolidays(list, title) {
+    if (list.length === 0)
+        return `No holidays found for ${title}.`;
+    const sorted = [...list].sort((a, b) => a.date.localeCompare(b.date));
+    return `${title} (${sorted.length}):\n\n${sorted.map(formatHoliday).join("\n")}`;
 }
-export function nextHolidays(country) {
-    return get(`/NextPublicHolidays/${encodeURIComponent(country)}`);
+export function formatCountryInfo(info) {
+    const borders = (info.borders ?? []).map((b) => `${b.commonName} (${b.countryCode})`);
+    return [
+        `${info.commonName} (${info.countryCode})`,
+        `  official name  ${info.officialName}`,
+        `  region         ${info.region}`,
+        `  borders        ${borders.length ? borders.join(", ") : "none - island or no land border"}`,
+    ].join("\n");
+}
+export function formatLongWeekends(list, title) {
+    if (list.length === 0)
+        return `No long weekends found for ${title}.`;
+    const lines = list.map((w) => `  ${w.startDate} -> ${w.endDate}  ${w.dayCount} day(s)${w.needBridgeDay ? `  needs bridge day: ${(w.bridgeDays ?? []).join(", ")}` : "  no bridge day needed"}`);
+    return `${title} (${list.length}):\n\n${lines.join("\n")}`;
+}
+// ---- batch-4 tools: regional holidays, date lookup and country diff (2026-09-27) ----
+export async function regionalHolidays(year, country, county) {
+    const y = normaliseYear(year);
+    const code = normaliseCountry(country);
+    const region = String(county ?? "").trim().toUpperCase();
+    if (!/^[A-Z]{2}-[A-Z0-9]{1,3}$/.test(region)) {
+        throw new NagerError(`"${county}" is not a subdivision code - use the country code and the region, for example DE-BE or US-CA.`);
+    }
+    const list = await getJson(`/PublicHolidays/${y}/${encodeURIComponent(code)}?county=${encodeURIComponent(region)}`);
+    if (!list.length)
+        return `No holidays for ${code} in ${y}.`;
+    const own = list.filter((h) => Array.isArray(h.counties) && h.counties.length > 0);
+    const national = list.length - own.length;
+    return [
+        `Holidays that apply in ${region} during ${y}: ${list.length} in total`,
+        `  national (country-wide): ${national} | ${region} specific: ${own.length}`,
+        "",
+        formatHolidays(list, `${region} ${y}`),
+        "",
+        "Subdivision codes follow ISO 3166-2: DE-BE (Berlin), US-CA (California), CA-ON (Ontario).",
+    ].join("\n");
+}
+export async function holidayOnDate(date, country) {
+    const clean = String(date ?? "").trim();
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(clean)) {
+        throw new NagerError(`"${date}" is not a date - use YYYY-MM-DD, for example 2026-12-25.`);
+    }
+    const year = clean.slice(0, 4);
+    const code = normaliseCountry(country);
+    const list = (await holidays(year, code)).sort((a, b) => a.date.localeCompare(b.date));
+    const weekday = new Date(`${clean}T00:00:00Z`).toLocaleDateString("en-US", { weekday: "long", timeZone: "UTC" });
+    const hits = list.filter((h) => h.date === clean);
+    const before = [...list].reverse().find((h) => h.date < clean);
+    const after = list.find((h) => h.date > clean);
+    const neighbours = [
+        before ? `  previous  ${before.date}  ${before.localName}` : "",
+        after ? `  next      ${after.date}  ${after.localName}` : "",
+    ].filter(Boolean);
+    if (!hits.length) {
+        return [
+            `${clean} (${weekday}) is not a public holiday in ${code}.`,
+            "",
+            ...neighbours,
+            "",
+            `The country has ${list.length} holiday(s) listed for ${year}.`,
+        ].join("\n");
+    }
+    return [
+        `Yes - ${clean} (${weekday}) is a public holiday in ${code}:`,
+        "",
+        ...hits.map((h) => `  ${h.localName}${h.name !== h.localName ? ` (${h.name})` : ""}${h.global === false ? " - subdivision only" : ""}`),
+        hits.some((h) => !h.global) ? "  Some entries apply only in part of the country." : "",
+        "",
+        ...neighbours,
+    ].filter((line) => line !== "").join("\n");
+}
+export async function compareCountries(year, countryA, countryB) {
+    const y = normaliseYear(year);
+    const a = normaliseCountry(countryA);
+    const b = normaliseCountry(countryB);
+    if (a === b)
+        throw new NagerError("Give two different country codes to compare.");
+    const [listA, listB] = await Promise.all([holidays(y, a), holidays(y, b)]);
+    if (!listA.length || !listB.length) {
+        throw new NagerError(`date.nager.at has no holidays for ${!listA.length ? a : b} in ${y}.`);
+    }
+    const namesA = new Set(listA.map((h) => `${h.date}|${h.name}`));
+    const namesB = new Set(listB.map((h) => `${h.date}|${h.name}`));
+    const shared = [...namesA].filter((key) => namesB.has(key)).sort();
+    const onlyA = [...namesA].filter((key) => !namesB.has(key)).sort();
+    const onlyB = [...namesB].filter((key) => !namesA.has(key)).sort();
+    const datesA = new Map(listA.map((h) => [h.date, h.name]));
+    const sameDateDifferentName = listB
+        .filter((h) => datesA.has(h.date) && datesA.get(h.date) !== h.name)
+        .map((h) => `  ${h.date}  ${h.name} vs ${datesA.get(h.date)}`);
+    const show = (keys) => keys.slice(0, 12).map((key) => `  ${key.replace("|", "  ")}`);
+    return [
+        `${a} vs ${b} public holidays in ${y}:`,
+        "",
+        `  ${a}: ${listA.length} holiday(s) | ${b}: ${listB.length}`,
+        `  same date and name: ${shared.length} | ${a} only: ${onlyA.length} | ${b} only: ${onlyB.length}`,
+        `  same date, different name: ${sameDateDifferentName.length}`,
+        "",
+        "Shared days:",
+        ...(shared.length ? show(shared) : ["  none"]),
+        "",
+        `Only in ${a}:`,
+        ...(onlyA.length ? show(onlyA) : ["  none"]),
+        "",
+        `Only in ${b}:`,
+        ...(onlyB.length ? show(onlyB) : ["  none"]),
+        "",
+        sameDateDifferentName.length ? "Same day, different name:" : "",
+        ...sameDateDifferentName.slice(0, 8),
+        "",
+        `Shows up to 12 entries per list; both countries keep their own names for the same festival.`,
+    ].filter((line) => line !== "").join("\n");
+}
+// ---- muxF tools:
+/**
+ * The holiday API answers "when are the holidays"; these two answer the
+ * questions a working calendar actually needs - how many working days are
+ * left, and where a holiday lands on a weekend.
+ */
+const NAG_WEEKEND = [0, 6]; // getUTCDay: 0 Sunday, 6 Saturday
+const nagDayName = (date) => new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", { weekday: "short", timeZone: "UTC" });
+const nagIsWeekend = (date) => NAG_WEEKEND.includes(new Date(`${date}T00:00:00Z`).getUTCDay());
+const nagAddDays = (date, days) => {
+    const stamp = Date.parse(`${date}T00:00:00Z`);
+    return new Date(stamp + days * 86_400_000).toISOString().slice(0, 10);
+};
+const nagMonthName = (month) => new Date(`${month}-01T00:00:00Z`).toLocaleDateString("en-US", { month: "long", timeZone: "UTC" });
+async function nagYear(code, year) {
+    const list = await getJson(`/PublicHolidays/${year}/${code}`);
+    return (Array.isArray(list) ? list : []).filter((h) => h && typeof h.date === "string");
+}
+/** Month by month working-day arithmetic for one country and year. */
+export async function workingDayCalendar(args) {
+    const code = normaliseCountry(args?.country);
+    const year = normaliseYear(args?.year);
+    const holidays = await nagYear(code, year);
+    const holidayDays = new Set(holidays.map((h) => h.date));
+    const yearStart = `${year}-01-01`;
+    const yearEnd = `${year}-12-31`;
+    const months = [];
+    let totalWeekdays = 0;
+    let totalWeekends = 0;
+    let totalHolidays = 0;
+    let totalWorking = 0;
+    for (let month = 1; month <= 12; month += 1) {
+        const key = `${year}-${String(month).padStart(2, "0")}`;
+        const daysInMonth = new Date(Date.UTC(Number(year), month, 0)).getUTCDate();
+        let weekends = 0;
+        let holidays = 0;
+        let weekdayHolidays = 0;
+        let workingInMonth = 0;
+        for (let day = 1; day <= daysInMonth; day += 1) {
+            const date = `${key}-${String(day).padStart(2, "0")}`;
+            const weekend = nagIsWeekend(date);
+            const isHoliday = holidayDays.has(date);
+            if (weekend)
+                weekends += 1;
+            if (isHoliday) {
+                holidays += 1;
+                if (!weekend)
+                    weekdayHolidays += 1;
+            }
+            if (!weekend && !isHoliday)
+                workingInMonth += 1;
+        }
+        const weekdays = daysInMonth - weekends;
+        const working = weekdays - weekdayHolidays;
+        totalWorking += working;
+        months.push({ month: key, days: daysInMonth, weekends, weekdays, holidays, working });
+        totalWeekends += weekends;
+        totalHolidays += holidays;
+        totalWeekdays += weekdays;
+    }
+    const longestStreak = () => {
+        let best = { from: "", to: "", days: 0 };
+        let run = 0;
+        let start = "";
+        for (let day = 1; day <= 366; day += 1) {
+            const date = nagAddDays(yearStart, day - 1);
+            if (date > yearEnd)
+                break;
+            const free = !nagIsWeekend(date) && !holidayDays.has(date);
+            if (free) {
+                if (run === 0)
+                    start = date;
+                run += 1;
+                if (run > best.days)
+                    best = { from: start, to: date, days: run };
+            }
+            else {
+                run = 0;
+            }
+        }
+        return best;
+    };
+    const streak = longestStreak();
+    const lines = [
+        `Working-day calendar for ${code} in ${year}, from the holiday API's own list (${holidays.length} holiday date(s))`,
+        `  ${totalWeekdays} weekday(s) in the year, ${totalWeekends} weekend day(s), ${totalHolidays} of those weekdays are holidays`,
+        `  working days: ${totalWorking}`,
+        `  longest unbroken run of working days: ${streak.days} day(s), ${streak.from} to ${streak.to}`,
+        "",
+        "  month          days  weekends  weekdays  holidays  working",
+    ];
+    for (const m of months) {
+        lines.push(`  ${nagMonthName(m.month).padEnd(14)}${String(m.days).padStart(4)}${String(m.weekends).padStart(10)}${String(m.weekdays).padStart(10)}${String(m.holidays).padStart(10)}${String(m.working).padStart(9)}`);
+    }
+    lines.push("");
+    lines.push("  A holiday that falls on a weekend costs no working day, which is why a country's working-day count is lower than its weekday count by less than its holiday count.");
+    return lines.join("\n");
+}
+/** Where each holiday lands, and what it does to the working week around it. */
+export async function holidayObservanceAudit(args) {
+    const code = normaliseCountry(args?.country);
+    const year = normaliseYear(args?.year);
+    const holidays = await nagYear(code, year);
+    if (!holidays.length)
+        throw new NagerError(`The holiday API has no ${year} holidays for ${code}.`);
+    const rows = [...holidays].sort((a, b) => a.date.localeCompare(b.date));
+    const weekendRows = rows.filter((h) => nagIsWeekend(h.date));
+    const mondayObserved = rows.filter((h) => nagIsWeekend(h.date) && nagDayName(h.date) === "Sun");
+    const saturdayRows = rows.filter((h) => nagDayName(h.date) === "Sat");
+    const national = rows.filter((h) => h.global !== false);
+    const regional = rows.filter((h) => h.global === false);
+    const runAfter = (date) => {
+        let count = 0;
+        let cursor = date;
+        for (let i = 0; i < 14; i += 1) {
+            cursor = nagAddDays(cursor, 1);
+            const weekend = nagIsWeekend(cursor);
+            if (!weekend && !rows.some((h) => h.date === cursor))
+                count += 1;
+        }
+        return count;
+    };
+    const lines = [
+        `Holiday observance for ${code} in ${year}: ${rows.length} holiday date(s)`,
+        `  ${national.length} national, ${regional.length} regional (${regional.length ? "regional holidays may not apply where you are" : "none reported"})`,
+        `  ${weekendRows.length} fall on a weekend: ${saturdayRows.length} Saturday, ${mondayObserved.length} Sunday`,
+    ];
+    lines.push("");
+    lines.push("  date        day   falls on   gap to next free working day   name");
+    for (const h of rows) {
+        const day = nagDayName(h.date);
+        const weekend = nagIsWeekend(h.date);
+        const gap = weekend ? "weekend, no working day lost" : `${runAfter(h.date)} working day(s) after`;
+        lines.push(`  ${h.date}  ${day.padEnd(5)} ${(weekend ? "weekend" : "weekday").padEnd(10)} ${gap.padEnd(32)} ${h.localName || h.name}`);
+    }
+    lines.push("");
+    if (weekendRows.length) {
+        lines.push(`  ${weekendRows.length} holiday(s) land on a weekend, so a substitute day is the employer's policy, not something the API states.`);
+    }
+    const backToBack = rows.filter((h, i) => i > 0 && nagAddDays(rows[i - 1].date, 1) === h.date);
+    if (backToBack.length) {
+        lines.push(`  ${backToBack.length} holiday(s) fall on the day after another: ${backToBack.map((h) => `${h.date} ${h.localName}`).join(", ")}`);
+    }
+    return lines.join("\n");
 }

package/dist/license.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Returns null when the caller may run the tool, or a short message telling
+ * them how to get a key.
+ *
+ * A good key is remembered for an hour, so a busy session does not hit the
+ * license server on every call and keeps working through a brief outage.
+ */
+export declare function premiumRequired(tool: string): Promise<string | null>;

package/dist/license.js

@@ -0,0 +1,79 @@
+// Premium tools on this server need a license key bought from MCP Marketplace.
+// Buyers put the key in their MCP client config as MCP_LICENSE_KEY. Every tool
+// that is not listed in PREMIUM keeps working without a key.
+const SLUG = "nager-mcp";
+// Tools that need a key. Everything else is free.
+const PREMIUM = new Set([
+    "working_day_calendar",
+    "holiday_observance_audit",
+]);
+const BUY_URL = `https://mcp-marketplace.io/server/io-github-mrfentmen-${SLUG}`;
+// The license check calls the marketplace's verify endpoint directly instead of
+// using @mcp_marketplace/license. That SDK sends no `apikey` header, so every
+// check it makes is rejected by Supabase before it reaches the function. The
+// publishable key below is public by design - it ships in mcp-marketplace.io's
+// own JavaScript and only ever reaches their licence check.
+const DEFAULT_VERIFY_URL = "https://virupvwhtkpkjsiskckg.supabase.co/functions/v1/verify-key";
+const PUBLISHABLE_KEY = "sb_publishable_BuqlW96Ke8C_zzJG-LQv1Q_YHi_r_4h";
+const OK_CACHE_MS = 60 * 60 * 1000;
+const BAD_CACHE_MS = 60 * 1000;
+const seen = new Map();
+const REASONS = {
+    missing_key: "no key is set",
+    invalid_format: "that key is not a valid MCP Marketplace key",
+    not_found: "that key was not found",
+    revoked: "that key has been revoked",
+    rotated: "that key was rotated, use your new one",
+    expired: "that key has expired, renew it",
+    rate_limited: "there were too many checks just now, try again shortly",
+    network_error: "the license server could not be reached",
+};
+function blocked(tool, reason) {
+    const why = REASONS[reason] ?? `the license server answered "${reason}"`;
+    return `"${tool}" needs a license key, but ${why}. ` +
+        `Set MCP_LICENSE_KEY in your MCP client config. Get a key: ${BUY_URL}`;
+}
+async function verify(key) {
+    const res = await fetch(process.env.MCP_LICENSE_VERIFY_URL || DEFAULT_VERIFY_URL, {
+        method: "POST",
+        headers: {
+            apikey: PUBLISHABLE_KEY,
+            Authorization: `Bearer ${PUBLISHABLE_KEY}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ key, slug: SLUG }),
+        // an unusable key answers 400 with a JSON body, so read the body either way
+        signal: AbortSignal.timeout(15000),
+    });
+    const data = (await res.json());
+    if (typeof data?.valid !== "boolean")
+        return { valid: false, reason: "unexpected_response" };
+    return data;
+}
+/**
+ * Returns null when the caller may run the tool, or a short message telling
+ * them how to get a key.
+ *
+ * A good key is remembered for an hour, so a busy session does not hit the
+ * license server on every call and keeps working through a brief outage.
+ */
+export async function premiumRequired(tool) {
+    if (!PREMIUM.has(tool))
+        return null;
+    const key = process.env.MCP_LICENSE_KEY;
+    if (!key)
+        return blocked(tool, "missing_key");
+    const hit = seen.get(key);
+    if (hit && Date.now() - hit.at < (hit.valid ? OK_CACHE_MS : BAD_CACHE_MS)) {
+        return hit.valid ? null : blocked(tool, hit.reason ?? "invalid");
+    }
+    let result;
+    try {
+        result = await verify(key);
+    }
+    catch {
+        result = { valid: false, reason: "network_error" };
+    }
+    seen.set(key, { ...result, at: Date.now() });
+    return result.valid ? null : blocked(tool, result.reason ?? "invalid");
+}

package/dist/server.js

@@ -1,9 +1,12 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { errorMessage, listCountries, getHolidays, nextHolidays, } from "./api.js";
+import { countries, countryInfo, errorMessage, formatCountryInfo, formatHoliday, formatHolidays, formatLongWeekends, holidays, isTodayHoliday, longWeekends, nextHolidays, worldwideHolidays, regionalHolidays, holidayOnDate, compareCountries, workingDayCalendar, holidayObservanceAudit } from "./api.js";
+import { premiumRequired } from "./license.js";
 const text = (t) => ({ content: [{ type: "text", text: t }] });
 const textError = (t) => ({ content: [{ type: "text", text: t }], isError: true });
 const READ_ONLY = { readOnlyHint: true, openWorldHint: true };
+const COUNTRY = z.string().describe("Two-letter country code, e.g. 'US', 'DE', 'JP'");
+const YEAR = z.string().describe("Four-digit year, e.g. '2026'");
 export function createServer() {
     const server = new McpServer({
         name: "nager-mcp",
@@ -11,28 +14,41 @@ export function createServer() {
     });
     server.registerTool("list_countries", {
         title: "List countries",
-        description: "Supported country codes.",
+        description: "Every country the public holiday API covers, with its two-letter code.",
         inputSchema: z.object({}),
         annotations: READ_ONLY,
-    }, async ({}) => {
+    }, async () => {
         try {
-            return text(await listCountries());
+            const list = await countries();
+            const lines = list.map((c) => `  ${c.countryCode}  ${c.name}`);
+            return text(`${list.length} countries:\n\n${lines.join("\n")}`);
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("country_info", {
+        title: "Country info",
+        description: "Official name, region and land borders for a country.",
+        inputSchema: z.object({ country: COUNTRY }),
+        annotations: READ_ONLY,
+    }, async ({ country }) => {
+        try {
+            return text(formatCountryInfo(await countryInfo(country)));
         }
         catch (e) {
             return textError(errorMessage(e));
         }
     });
     server.registerTool("get_holidays", {
-        title: "Year holidays",
-        description: "Holidays for a year and country.",
-        inputSchema: z.object({
-            year: z.string().describe("Year, e.g. 2026."),
-            country: z.string().describe("ISO code, e.g. US.")
-        }),
+        title: "Public holidays",
+        description: "All public holidays for a country and year, with local and English names.",
+        inputSchema: z.object({ year: YEAR, country: COUNTRY }),
         annotations: READ_ONLY,
     }, async ({ year, country }) => {
         try {
-            return text(await getHolidays(year, country));
+            const list = await holidays(year, country);
+            return text(formatHolidays(list, `${country.toUpperCase()} public holidays in ${year}`));
         }
         catch (e) {
             return textError(errorMessage(e));
@@ -40,14 +56,148 @@ export function createServer() {
     });
     server.registerTool("next_holidays", {
         title: "Upcoming holidays",
-        description: "Next holidays for a country.",
+        description: "The next public holidays for a country, starting from today.",
+        inputSchema: z.object({ country: COUNTRY }),
+        annotations: READ_ONLY,
+    }, async ({ country }) => {
+        try {
+            const list = await nextHolidays(country);
+            return text(formatHolidays(list, `Upcoming holidays in ${country.toUpperCase()}`));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("worldwide_holidays", {
+        title: "Holidays worldwide",
+        description: "The next public holidays around the world - useful for planning around other countries' closures.",
         inputSchema: z.object({
-            country: z.string().describe("ISO code, e.g. US.")
+            limit: z.number().int().min(1).max(100).default(25).describe("How many holidays to show"),
         }),
         annotations: READ_ONLY,
+    }, async ({ limit }) => {
+        try {
+            const list = (await worldwideHolidays()).sort((a, b) => a.date.localeCompare(b.date));
+            const shown = list.slice(0, limit);
+            const lines = shown.map((h) => `${formatHoliday(h)}  [${h.countryCode}]`);
+            return text(`Next holidays worldwide (${shown.length} of ${list.length}):\n\n${lines.join("\n")}`);
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("long_weekends", {
+        title: "Long weekends",
+        description: "Long weekends in a country and year, and whether a bridge day off is needed to get them.",
+        inputSchema: z.object({ year: YEAR, country: COUNTRY }),
+        annotations: READ_ONLY,
+    }, async ({ year, country }) => {
+        try {
+            const list = await longWeekends(year, country);
+            return text(formatLongWeekends(list, `Long weekends in ${country.toUpperCase()} ${year}`));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("is_today_holiday", {
+        title: "Is today a holiday",
+        description: "Whether today is a public holiday in a country.",
+        inputSchema: z.object({ country: COUNTRY }),
+        annotations: READ_ONLY,
     }, async ({ country }) => {
         try {
-            return text(await nextHolidays(country));
+            const result = await isTodayHoliday(country);
+            if (!result.isHoliday) {
+                return text(`Today is not a public holiday in ${country.toUpperCase()}.`);
+            }
+            return text(`Today is a public holiday in ${country.toUpperCase()}:\n\n${formatHoliday(result.holiday).trim()}`);
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("regional_holidays", {
+        title: "Regional holidays",
+        description: "Holidays that actually apply in one subdivision (US-CA, DE-BE, CA-ON): national days plus local ones.",
+        inputSchema: z.object({
+            year: z.string().describe("Four-digit year, e.g. 2026."),
+            country: z.string().describe("Two-letter country code, e.g. US."),
+            county: z.string().describe("ISO 3166-2 subdivision code, e.g. US-CA.")
+        }),
+        annotations: READ_ONLY,
+    }, async ({ year, country, county }) => {
+        try {
+            return text(await regionalHolidays(year, country, county));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("holiday_on_date", {
+        title: "Holiday on a date",
+        description: "Is one specific date a public holiday? Answers yes or no, with the previous and next holiday.",
+        inputSchema: z.object({
+            date: z.string().describe("Date to check, YYYY-MM-DD."),
+            country: z.string().describe("Two-letter country code, e.g. US.")
+        }),
+        annotations: READ_ONLY,
+    }, async ({ date, country }) => {
+        try {
+            return text(await holidayOnDate(date, country));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("compare_countries", {
+        title: "Compare countries",
+        description: "Shared, and country-specific, public holidays for two countries in one year.",
+        inputSchema: z.object({
+            year: z.string().describe("Four-digit year, e.g. 2026."),
+            country_a: z.string().describe("First country code, e.g. US."),
+            country_b: z.string().describe("Second country code, e.g. GB.")
+        }),
+        annotations: READ_ONLY,
+    }, async ({ year, country_a: countryA, country_b: countryB }) => {
+        try {
+            return text(await compareCountries(year, countryA, countryB));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("working_day_calendar", {
+        title: "Working day calendar",
+        description: "Month-by-month working-day arithmetic for a country and year, computed from the holiday list: weekdays, weekend days, how many of those weekdays are holidays, the working-day count, and the longest unbroken run of working days in the year.",
+        inputSchema: z.object({ country: z.string().describe("Two-letter country code, e.g. AT."), year: z.string().describe("Four-digit year, e.g. 2026.") }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        // ---- paywall: working_day_calendar ----
+        const paywallMessage = await premiumRequired("working_day_calendar");
+        if (paywallMessage)
+            return { content: [{ type: "text", text: paywallMessage }], isError: true };
+        // ---- paywall: end ----
+        try {
+            return text(await workingDayCalendar(args));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("holiday_observance_audit", {
+        title: "Holiday observance audit",
+        description: "Where every holiday in a country and year actually lands: the weekday it falls on, whether it costs a working day, how many free working days follow it, which holidays are regional, which fall on a weekend and which run back to back.",
+        inputSchema: z.object({ country: z.string().describe("Two-letter country code, e.g. DE."), year: z.string().describe("Four-digit year, e.g. 2026.") }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        // ---- paywall: holiday_observance_audit ----
+        const paywallMessage = await premiumRequired("holiday_observance_audit");
+        if (paywallMessage)
+            return { content: [{ type: "text", text: paywallMessage }], isError: true };
+        // ---- paywall: end ----
+        try {
+            return text(await holidayObservanceAudit(args));
         }
         catch (e) {
             return textError(errorMessage(e));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nager-mcp",
-  "version": "1.0.0",
-  "description": "Nager public holidays. Keyless.",
+  "version": "1.0.1",
+  "description": "Worldwide public holidays and long weekends - no API key.",
   "type": "module",
   "mcpName": "io.github.mrfentmen/nager-mcp",
   "repository": {
@@ -22,11 +22,11 @@
     "inspect": "npx @modelcontextprotocol/inspector node dist/index.js"
   },
   "keywords": [
-    "mcp",
     "holidays",
     "calendar",
+    "planning",
     "countries",
-    "keyless"
+    "mcp"
   ],
   "license": "MIT",
   "dependencies": {