countryflags-mcp 1.0.1 → 1.0.2

package/README.md

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

@@ -23,3 +23,65 @@ export async function flag(args) {
         return 'Provide a country code like us.';
     return `${code.toUpperCase()}: ${BASE}/${code}.png (w160: ${BASE}/w160/${code}.png, w320: ${BASE}/w320/${code}.png)`;
 }
+// ---- muxA tools:
+// The existing tools search the code list and print a bare flag url. The bare
+// form has no size and answers 404, so these return only the sized urls that
+// really exist and resolve a country or region name to its code.
+/** Sizes confirmed to answer 200 for a country code. Anything else 404s. */
+const SIZES = [
+    'w20', 'w40', 'w80', 'w160', 'w320', 'w640', 'w1280', 'w2560',
+    'h20', 'h24', 'h40', 'h60', 'h80', 'h120',
+    '24x18', '32x24', '48x36', '64x48', '96x72', '128x96', '256x192',
+];
+async function codes() {
+    const res = await fetch(`${BASE}/en/codes.json`, {
+        headers: { 'User-Agent': 'mrfentmen-countryflags-mcp/1.0', Accept: 'application/json' },
+        signal: AbortSignal.timeout(20000),
+    });
+    if (!res.ok)
+        throw new Error(`Flagcdn returned ${res.status}`);
+    const d = (await res.json());
+    return d && typeof d === 'object' ? d : {};
+}
+function sizeList(requested) {
+    if (!requested)
+        return SIZES;
+    const wanted = requested.split(/[,\s]+/).filter(Boolean).map((s) => s.toLowerCase());
+    const bad = wanted.filter((s) => !SIZES.includes(s));
+    if (bad.length)
+        throw new Error(`These sizes do not exist: ${bad.join(', ')}. Available: ${SIZES.join(', ')}.`);
+    return wanted;
+}
+export async function flagUrls(args) {
+    const code = (args.code ?? '').trim().toLowerCase();
+    if (!code)
+        throw new Error('Provide a country code like us, or a subdivision code like gb-eng.');
+    const names = await codes();
+    if (!names[code]) {
+        throw new Error(`Flagcdn has no code "${code}". It serves ${Object.keys(names).length} codes, including ${Object.keys(names).slice(0, 8).join(', ')}.`);
+    }
+    const wanted = sizeList(args.sizes);
+    const lines = [`${names[code]} (${code.toUpperCase()}):`];
+    for (const size of wanted)
+        lines.push(`  ${size}: ${BASE}/${size}/${code}.png`);
+    lines.push(`The bare ${BASE}/${code}.png answers 404, so a size is always required.`);
+    return lines.join('\n');
+}
+export async function resolveName(args) {
+    const query = (args.name ?? '').trim().toLowerCase();
+    if (!query)
+        throw new Error('Provide a country or region name, or part of one.');
+    const names = await codes();
+    const hits = Object.entries(names).filter(([code, name]) => name.toLowerCase().includes(query) || code === query);
+    if (!hits.length)
+        return `No flag matches "${args.name}".`;
+    const wanted = sizeList(args.sizes);
+    const shown = hits.slice(0, 10);
+    const lines = [`Flags matching "${args.name}": ${hits.length}${hits.length > shown.length ? `, showing ${shown.length}` : ''}`];
+    for (const [code, name] of shown) {
+        lines.push(`  ${name} (${code})`);
+        for (const size of wanted.slice(0, 3))
+            lines.push(`     ${BASE}/${size}/${code}.png`);
+    }
+    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 = "countryflags-mcp";
+// Tools that need a key. Everything else is free.
+const PREMIUM = new Set([
+    "flag_urls",
+]);
+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 { flag } from "./api.js";
-import { list } from "./api.js";
+import { list, flagUrls, resolveName } 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("flag_urls", {
+        title: "Flag urls",
+        description: "Every working size url for one flag code, checked against the live code list and restricted to the sizes that really exist. The unsized url the flag tool prints answers 404.",
+        inputSchema: z.object({ code: z.string().describe("Country code like us, or a subdivision code like gb-eng."), sizes: z.string().describe("Comma separated sizes to show, like w320,256x192. Defaults to all 21 that exist.").optional() }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        // ---- paywall: flag_urls ----
+        const paywallMessage = await premiumRequired("flag_urls");
+        if (paywallMessage)
+            return { content: [{ type: "text", text: paywallMessage }], isError: true };
+        // ---- paywall: end ----
+        try {
+            return text(await flagUrls(args));
+        }
+        catch (e) {
+            return textError(error(e));
+        }
+    });
+    server.registerTool("resolve_name", {
+        title: "Resolve name",
+        description: "Find flag codes by country or region name and get real image urls for each, instead of guessing the two letter code.",
+        inputSchema: z.object({ name: z.string().describe("Country or region name or part of one, like united or korea."), sizes: z.string().describe("Comma separated sizes to show, like w320. Defaults to all 21 that exist.").optional() }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        try {
+            return text(await resolveName(args));
+        }
+        catch (e) {
+            return textError(error(e));
+        }
+    });
     return server;
 }

package/package.json

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