data-gov-uk-mcp 1.0.0 → 1.0.2

package/README.md

@@ -18,3 +18,21 @@ node dist/index.js
 ```
 
 Data comes from the public data.gov.uk CKAN API.
+
+<!-- paywall -->
+## Premium tools
+
+These tools need a license key:
+
+* `dataset_detail`
+
+Buy a key at https://mcp-marketplace.io/server/io-github-mrfentmen-data-gov-uk-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,125 @@ export async function search(args) {
         })
             .join('\n');
 }
+// ---- muxE tools:
+// The one existing tool does free text package_search and prints three fields.
+// The new ones ask data.gov.uk two other questions: everything about one named
+// dataset, and everything one publisher has published. data.gov.uk now 301s every
+// api/3/action call to ckan.publishing.service.gov.uk, verified live, so the
+// canonical host is used directly rather than paying for the redirect each time.
+const CANON = 'https://ckan.publishing.service.gov.uk/api/3/action';
+const DG_UA = 'mrfentmen-data-gov-uk-mcp/1.0';
+async function dgGet(path, params) {
+    const qs = new URLSearchParams(params).toString();
+    const res = await fetch(`${CANON}/${path}?${qs}`, {
+        headers: { 'User-Agent': DG_UA, Accept: 'application/json' },
+        signal: AbortSignal.timeout(30000),
+    });
+    if (res.status === 404)
+        throw new Error('data.gov.uk has no record for that.');
+    if (res.status === 403)
+        throw new Error(`data.gov.uk refused that request with HTTP 403; its nginx only allows package_search, package_show and package_list.`);
+    if (!res.ok)
+        throw new Error(`data.gov.uk returned ${res.status}`);
+    const body = (await res.json());
+    if (body?.success === false) {
+        const why = typeof body.error === 'string' ? body.error : body.error?.message;
+        throw new Error(`data.gov.uk said: ${why ?? 'the request was rejected'}`);
+    }
+    return body;
+}
+const dayOf = (value) => (value ? String(value).slice(0, 10) : 'not reported');
+export async function datasetDetail(args) {
+    const name = (args?.name ?? '').trim();
+    if (!name)
+        throw new Error('Provide the dataset name, the slug that ends data.gov.uk/dataset/<name>.');
+    if (!/^[\w.-]{1,120}$/.test(name)) {
+        throw new Error('A dataset name may only hold letters, digits, dots, dashes and underscores.');
+    }
+    const d = await dgGet('package_show', { id: name });
+    const p = d.result;
+    if (!p || typeof p !== 'object' || typeof p.name !== 'string')
+        throw new Error('data.gov.uk returned no dataset for that name.');
+    const resources = Array.isArray(p.resources) ? p.resources : [];
+    const tags = Array.isArray(p.tags) ? p.tags : [];
+    const groups = Array.isArray(p.groups) ? p.groups : [];
+    const byFormat = new Map();
+    for (const r of resources) {
+        const key = r?.format || 'not reported';
+        byFormat.set(key, (byFormat.get(key) ?? 0) + 1);
+    }
+    const lines = [
+        p.title || p.name,
+        `  dataset name: ${p.name}`,
+        `  publisher: ${p.organization?.title ?? 'not reported'}${p.organization?.name ? ` (${p.organization.name})` : ''}`,
+        `  licence: ${p.license_title ?? 'not reported'}${p.license_url ? ` - ${p.license_url}` : ''}`,
+        `  state: ${p.state ?? 'not reported'}, open: ${p.isopen === true ? 'yes' : p.isopen === false ? 'no' : 'not reported'}`,
+        `  version: ${p.version ?? 'not reported'}`,
+        `  created: ${dayOf(p.metadata_created)}, metadata last changed: ${dayOf(p.metadata_modified)}`,
+        `  resources: ${typeof p.num_resources === 'number' ? p.num_resources : 'not reported'}, tags: ${typeof p.num_tags === 'number' ? p.num_tags : 'not reported'}`,
+    ];
+    if (p.url)
+        lines.push(`  landing page: ${p.url}`);
+    if (p.notes)
+        lines.push(`  description: ${p.notes.replace(/\s+/g, ' ').slice(0, 500)}`);
+    if (tags.length) {
+        const vocab = new Set(tags.map((t) => t.vocabulary_id).filter(Boolean).map(String));
+        lines.push(`  tags: ${tags.slice(0, 25).map((t) => t.name ?? '?').join(', ')}${tags.length > 25 ? `, and ${tags.length - 25} more` : ''}`);
+        lines.push(`  tag vocabularies used: ${vocab.size ? [...vocab].join(', ') : 'none recorded'}`);
+    }
+    else {
+        lines.push('  tags: none recorded.');
+    }
+    if (groups.length)
+        lines.push(`  groups: ${groups.map((g) => g.title ?? g.name ?? '?').join(', ')}`);
+    if (byFormat.size) {
+        lines.push('  resources by format:');
+        for (const [k, n] of [...byFormat.entries()].sort((a, b) => b[1] - a[1]))
+            lines.push(`    ${k}: ${n}`);
+    }
+    lines.push(`  the ${resources.length} resource(s) below, each with the id a data store query would take:`);
+    for (const r of resources.slice(0, 25)) {
+        lines.push(`    [${r.format || 'format not reported'}] ${r.name || 'name not reported'}`);
+        lines.push(`      id ${r.id ?? 'not reported'}, table queryable: ${r.datastore_active === true ? 'yes' : r.datastore_active === false ? 'no' : 'not reported'}`);
+        if (r.url)
+            lines.push(`      ${r.url.slice(0, 160)}`);
+        lines.push(`      last modified ${dayOf(r.last_modified)}${typeof r.size === 'number' ? `, ${r.size.toLocaleString('en-US')} bytes` : ''}`);
+    }
+    if (resources.length > 25)
+        lines.push(`    and ${resources.length - 25} more resource(s) not listed here`);
+    return lines.join('\n');
+}
+export async function publisherDatasets(args) {
+    const org = (args?.organization ?? '').trim();
+    if (!org)
+        throw new Error('Provide the publisher slug, the name field of data.gov.uk/organisation/<slug>, not the display title.');
+    if (!/^[\w.-]{1,120}$/.test(org)) {
+        throw new Error('A publisher slug may only hold letters, digits, dots, dashes and underscores.');
+    }
+    const limit = Math.max(1, Math.min(Number(args?.limit ?? 10) || 10, 25));
+    const d = await dgGet('package_search', { fq: `organization:${org}`, rows: String(limit) });
+    const rows = Array.isArray(d.result?.results) ? d.result?.results : [];
+    const count = typeof d.result?.count === 'number' ? d.result.count : null;
+    if (!rows.length) {
+        if (count === 0)
+            return `data.gov.uk lists no dataset for the publisher "${org}".`;
+        return `data.gov.uk reports ${count} dataset(s) for "${org}" but returned none.`;
+    }
+    const publisher = rows[0].organization?.title ?? org;
+    const lines = [
+        `Datasets published by ${publisher} (${org}) on data.gov.uk:`,
+        `  datasets the catalogue reports: ${count !== null ? count.toLocaleString('en-US') : 'not reported'}`,
+        `  shown here: ${rows.length}`,
+    ];
+    rows.forEach((p, i) => {
+        const resources = Array.isArray(p.resources) ? p.resources : [];
+        const formats = new Set(resources.map((r) => r.format).filter(Boolean).map(String));
+        lines.push(`${i + 1}. ${p.title || p.name || 'title not reported'}`);
+        lines.push(`   name ${p.name ?? 'not reported'}, licence ${p.license_title ?? 'not reported'}, last changed ${dayOf(p.metadata_modified)}`);
+        lines.push(`   resources ${typeof p.num_resources === 'number' ? p.num_resources : 'not reported'}${formats.size ? ` (${[...formats].slice(0, 6).join(', ')})` : ''}, tags ${typeof p.num_tags === 'number' ? p.num_tags : 'not reported'}`);
+    });
+    if (count !== null && count > rows.length) {
+        lines.push(`  ${(count - rows.length).toLocaleString('en-US')} further dataset(s) exist for this publisher; ask for a higher limit to page further in.`);
+    }
+    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 = "data-gov-uk-mcp";
+// Tools that need a key. Everything else is free.
+const PREMIUM = new Set([
+    "dataset_detail",
+]);
+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,6 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { search } from "./api.js";
+import { search, datasetDetail, publisherDatasets } 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 };
@@ -20,5 +21,36 @@ export function createServer() {
             return textError(error(e));
         }
     });
+    server.registerTool("dataset_detail", {
+        title: "Dataset detail",
+        description: "One data.gov.uk dataset in full: its publisher, licence, state, version, dates, tags, vocabularies and every downloadable resource with its format, its resource id and whether the table can be queried. The search tool returns only a title, a truncated note and a date.",
+        inputSchema: z.object({ name: z.string().describe("The dataset slug, the part after data.gov.uk/dataset/.") }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        // ---- paywall: dataset_detail ----
+        const paywallMessage = await premiumRequired("dataset_detail");
+        if (paywallMessage)
+            return { content: [{ type: "text", text: paywallMessage }], isError: true };
+        // ---- paywall: end ----
+        try {
+            return text(await datasetDetail(args));
+        }
+        catch (e) {
+            return textError(error(e));
+        }
+    });
+    server.registerTool("publisher_datasets", {
+        title: "Publisher datasets",
+        description: "Everything one publisher has put on data.gov.uk: how many datasets the catalogue holds for it and each one with its name, licence, resource count and formats and the date its metadata last changed. The search tool does free text only and cannot filter to a publisher.",
+        inputSchema: z.object({ organization: z.string().describe("Publisher slug, the part after data.gov.uk/organisation/, e.g. open-data-ni. This is the name field, not the display title."), limit: z.number().describe("Max datasets, 1 to 25.").optional() }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        try {
+            return text(await publisherDatasets(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/data-gov-uk-mcp",
     "source": "github"
   },
-  "version": "1.0.0",
+  "version": "1.0.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "data-gov-uk-mcp",
-      "version": "1.0.0",
+      "version": "1.0.1",
       "transport": {
         "type": "stdio"
       }