enrico-mcp 1.0.0 → 1.0.2

package/README.md

@@ -19,3 +19,21 @@ node dist/index.js
 ```
 
 Data comes from the public Enrico API.
+
+<!-- paywall -->
+## Premium tools
+
+These tools need a license key:
+
+* `country_calendar`
+
+Buy a key at https://mcp-marketplace.io/server/io-github-mrfentmen-enrico-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.js

@@ -29,3 +29,152 @@ export async function holidays(args) {
         return `* ${date}: ${h.name?.[0]?.text ?? '?'}`;
     }).join('\n');
 }
+// ---- muxE tools:
+// The two existing tools print a country's code and name, or one year of its
+// public holidays. The new ones use the parts of the payload neither reads: the
+// coverage window and holiday type list every country record carries, and the
+// non public holiday types the service also serves per country.
+const ENRICO = "https://kayaposoft.com/enrico/json/v2.0";
+const ENRICO_UA = "mrfentmen-enrico-mcp/1.0";
+async function enricoJson(params) {
+    const qs = new URLSearchParams(params).toString();
+    const res = await fetch(`${ENRICO}/?${qs}`, {
+        headers: { "User-Agent": ENRICO_UA, Accept: "application/json" },
+        signal: AbortSignal.timeout(30000),
+    });
+    if (!res.ok)
+        throw new Error(`Enrico returned ${res.status}`);
+    const raw = await res.text();
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("Enrico returned a body that is not JSON.");
+    }
+    if (parsed && typeof parsed.error === "string")
+        throw new Error(`Enrico said: ${parsed.error}`);
+    return parsed;
+}
+const isoDate = (d) => {
+    if (!d || typeof d.year !== "number")
+        return "not reported";
+    // 52 of the 60 country records carry 32767 as a placeholder end year, verified
+    // live, so a real date is not printed for it
+    if (d.year >= 30000)
+        return "open ended, the record carries a placeholder year";
+    return `${d.year}-${String(d.month ?? 1).padStart(2, "0")}-${String(d.day ?? 1).padStart(2, "0")}`;
+};
+/** the name array is localised, so pick English when the service offers it */
+const localised = (names) => {
+    if (!Array.isArray(names) || !names.length)
+        return "name not reported";
+    const english = names.find((n) => String(n?.lang ?? "").toLowerCase().startsWith("en"));
+    if (english?.text)
+        return english.text;
+    const first = names.find((n) => n?.text);
+    const others = names.length - 1;
+    return `${first?.text ?? "name not reported"}${others > 0 ? ` (only ${names.length} translation${names.length === 1 ? "" : "s"}; ${names.map((n) => n?.lang ?? "?").join(", ")})` : ""}`;
+};
+const WEEKDAYS = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"];
+export async function countryCoverage(_args = {}) {
+    const list = await enricoJson({ action: "getSupportedCountries" });
+    const countries = Array.isArray(list) ? list : [];
+    if (!countries.length)
+        throw new Error("Enrico returned no countries.");
+    const typeCount = new Map();
+    for (const c of countries) {
+        for (const t of c.holidayTypes ?? [])
+            typeCount.set(t, (typeCount.get(t) ?? 0) + 1);
+    }
+    const fromYears = countries
+        .map((c) => c.fromDate?.year)
+        .filter((y) => typeof y === "number");
+    const bounded = countries.filter((c) => typeof c.toDate?.year === "number" && c.toDate.year < 30000);
+    const withRegions = countries.filter((c) => Array.isArray(c.regions) && c.regions.length > 0);
+    const lines = [
+        `What the Enrico holiday service actually covers, across its ${countries.length} countries:`,
+        `  every country offers: ${[...typeCount.entries()].filter(([, n]) => n === countries.length).map(([t]) => t).join(", ") || "none of them"}`,
+        `  distinct holiday types in the catalogue: ${typeCount.size}`,
+    ];
+    for (const [type, n] of [...typeCount.entries()].sort((a, b) => b[1] - a[1])) {
+        const names = countries.filter((c) => (c.holidayTypes ?? []).includes(type)).map((c) => (c.countryCode ?? "?").toUpperCase());
+        const shown = names.slice(0, 12).join(", ");
+        lines.push(`    ${type}: ${n} of ${countries.length} countries${names.length ? ` (${shown}${names.length > 12 ? `, and ${names.length - 12} more` : ""})` : ""}`);
+    }
+    lines.push(`  countries that publish a start year: ${fromYears.length}, earliest ${fromYears.length ? Math.min(...fromYears) : "not reported"}, latest ${fromYears.length ? Math.max(...fromYears) : "not reported"}`);
+    lines.push(`  countries whose records stop: ${bounded.length ? `${bounded.length} name a real end year (${[...new Set(bounded.map((c) => c.toDate?.year))].sort((a, b) => (a ?? 0) - (b ?? 0)).join(", ")}), the other ${countries.length - bounded.length} carry a placeholder end year` : `none name a real end year, all ${countries.length} carry a placeholder`}`);
+    lines.push(`  countries split into regions: ${withRegions.length}`);
+    for (const c of withRegions.slice(0, 8)) {
+        lines.push(`    ${(c.countryCode ?? "?").toUpperCase()} ${c.fullName ?? ""}: ${(c.regions ?? []).length} region code(s) - ${(c.regions ?? []).join(", ")}`);
+    }
+    if (withRegions.length > 8)
+        lines.push(`    and ${withRegions.length - 8} more region-split countries`);
+    const longest = [...countries].sort((a, b) => (b.holidayTypes ?? []).length - (a.holidayTypes ?? []).length)[0];
+    lines.push(`  richest country record: ${(longest.countryCode ?? "?").toUpperCase()} ${longest.fullName ?? ""} with ${(longest.holidayTypes ?? []).length} holiday types, covering ${isoDate(longest.fromDate)} to ${isoDate(longest.toDate)}`);
+    lines.push("  the countries tool prints only the code and the name and stops at 30 of them, so none of this is visible there.");
+    return lines.join("\n");
+}
+export async function countryCalendar(args) {
+    const raw = (args?.country ?? "").trim().toLowerCase();
+    if (!raw)
+        throw new Error("Provide a country code, like USA or DEU.");
+    if (!/^[a-z]{3}$/.test(raw))
+        throw new Error("Enrico country codes are three letters, like USA or DEU.");
+    const year = Math.floor(Number(args?.year));
+    if (!Number.isInteger(year) || year < 1940 || year > 2100) {
+        throw new Error("Provide a year between 1940 and 2100.");
+    }
+    const list = await enricoJson({ action: "getSupportedCountries" });
+    const countries = Array.isArray(list) ? list : [];
+    const record = countries.find((c) => String(c.countryCode ?? "").toLowerCase() === raw);
+    if (!record) {
+        const near = countries.map((c) => String(c.countryCode ?? "").toUpperCase()).filter((c) => c.includes(raw.toUpperCase())).slice(0, 8);
+        throw new Error(near.length
+            ? `Enrico has no country "${raw.toUpperCase()}". Close by: ${near.join(", ")}.`
+            : `Enrico has no country "${raw.toUpperCase()}".`);
+    }
+    const code = String(record.countryCode ?? raw).toUpperCase();
+    const types = Array.isArray(record.holidayTypes) && record.holidayTypes.length ? record.holidayTypes : ["public_holiday"];
+    const fromYear = typeof record.fromDate?.year === "number" ? record.fromDate.year : null;
+    const toYear = typeof record.toDate?.year === "number" && record.toDate.year < 30000 ? record.toDate.year : null;
+    const inWindow = (fromYear === null || year >= fromYear) && (toYear === null || year <= toYear);
+    if (!inWindow) {
+        return [
+            `Enrico holds no record for ${code} ${record.fullName ?? ""} in ${year}.`,
+            `  its coverage window is ${isoDate(record.fromDate)} to ${isoDate(record.toDate)}, and ${year} sits outside it.`,
+            `  regions it is split into: ${(record.regions ?? []).length ? (record.regions ?? []).join(", ") : "none"}`,
+            "  no figures are guessed for a year the service does not cover.",
+        ].join("\n");
+    }
+    const lines = [
+        `Every holiday Enrico publishes for ${code} ${record.fullName ?? ""} in ${year}:`,
+        `  coverage window: ${isoDate(record.fromDate)} to ${isoDate(record.toDate)}, and ${year} is inside it`,
+        `  regions the service splits this country into: ${(record.regions ?? []).length ? (record.regions ?? []).join(", ") : "none"}`,
+        `  holiday types offered: ${types.join(", ")}`,
+    ];
+    const seen = new Set();
+    for (const type of types) {
+        const rows = await enricoJson({
+            action: "getHolidaysForYear",
+            year: String(year),
+            country: raw,
+            holidayType: type,
+        });
+        const holidays = Array.isArray(rows) ? rows : [];
+        lines.push(`  ${type}: ${holidays.length} record(s)`);
+        for (const h of holidays.slice(0, 20)) {
+            const day = h.date?.dayOfWeek;
+            const stamp = h.date ? `${String(h.date.year ?? year)}-${String(h.date.month ?? 1).padStart(2, "0")}-${String(h.date.day ?? 1).padStart(2, "0")}` : "date not reported";
+            const weekday = typeof day === "number" && day >= 1 && day <= 7 ? ` (${WEEKDAYS[day - 1]})` : "";
+            const line = `    ${stamp}${weekday}: ${localised(h.name)}`;
+            lines.push(line);
+            seen.add(line);
+        }
+        if (holidays.length > 20)
+            lines.push(`    and ${holidays.length - 20} more ${type} record(s) not listed here`);
+    }
+    lines.push(`  ${seen.size} distinct dated record(s) across all ${types.length} type(s).`);
+    lines.push("  the holidays tool reads only the public_holiday type and only the first name in each record, so a country whose first name is not English comes back in its own language there.");
+    return lines.join("\n");
+}

package/dist/license.js

@@ -0,0 +1,78 @@
+// 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 = "enrico-mcp";
+// Tools that need a key. Everything else is free.
+const PREMIUM = new Set([
+    "country_calendar",
+]);
+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,7 +1,8 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { countries } from "./api.js";
-import { holidays } from "./api.js";
+import { holidays, countryCoverage, countryCalendar } from "./api.js";
+import { premiumRequired } from "./license.js";
 const text = (value) => ({ content: [{ type: "text", text: value }] });
 const textError = (t) => ({ content: [{ type: "text", text: t }], isError: true });
 const READ_ONLY = { readOnlyHint: true, openWorldHint: true };
@@ -34,5 +35,36 @@ export function createServer() {
             return textError(error(e));
         }
     });
+    server.registerTool("country_coverage", {
+        title: "Country coverage",
+        description: "What the Enrico holiday service actually covers across all its countries: every holiday type in the catalogue and how many countries offer each, the earliest year any country starts at, which countries name a real end year rather than a placeholder, and which countries are split into regions. The countries tool prints only a code and a name and stops at 30 of them.",
+        inputSchema: z.object({}),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        try {
+            return text(await countryCoverage());
+        }
+        catch (e) {
+            return textError(error(e));
+        }
+    });
+    server.registerTool("country_calendar", {
+        title: "Country calendar",
+        description: "Every holiday type Enrico serves for one country in one year, not just public holidays: observances, other days, extra working days, school holidays and postal holidays, with the English name where the record carries one, the weekday, the country's real coverage window and its region codes. The holidays tool reads a single type and takes only the first name in each record.",
+        inputSchema: z.object({ country: z.string().describe("Three letter country code like USA or DEU."), year: z.number().describe("Year, 1940 to 2100.") }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        // ---- paywall: country_calendar ----
+        const paywallMessage = await premiumRequired("country_calendar");
+        if (paywallMessage)
+            return { content: [{ type: "text", text: paywallMessage }], isError: true };
+        // ---- paywall: end ----
+        try {
+            return text(await countryCalendar(args));
+        }
+        catch (e) {
+            return textError(error(e));
+        }
+    });
     return server;
 }

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.0",
+  "version": "1.0.2",
   "type": "module",
   "repository": {
     "type": "git",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/mrfentmen/enrico-mcp",
     "source": "github"
   },
-  "version": "1.0.0",
+  "version": "1.0.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "enrico-mcp",
-      "version": "1.0.0",
+      "version": "1.0.1",
       "transport": {
         "type": "stdio"
       }