@aborruso/ckan-mcp-server 0.4.65 → 0.4.67

package/LOG.md

@@ -1,5 +1,16 @@
 # LOG
 
+## 2026-03-04 (v0.4.67)
+
+- improve: `sparql_query` — validate SELECT-only, auto-inject LIMIT (default 25, max 1000), truncate output at CHARACTER_LIMIT; +11 tests (310 total)
+- remove: `europa_dataset_search` tool and related files (`src/tools/europa.ts`, `src/utils/europa-http.ts`, Europa types in `src/types.ts`, docs, tests); tool count 19→18
+
+## 2026-03-04 (v0.4.66)
+
+- feat: add `sparql_query` tool — execute SPARQL SELECT against any public HTTPS endpoint (e.g. data.europa.eu/sparql, DBpedia, Wikidata)
+- feat(europa): update `europa_dataset_search` description to suggest `sparql_query` for publisher aggregations and queries not exposed as facets
+- test: add 12 tests for `sparql_query` (querySparqlEndpoint, formatSparqlMarkdown, formatSparqlJson)
+
 ## 2026-03-04 (v0.4.65)
 
 - feat(europa): add `publisher` to `ALLOWED_FACETS` in `europa_dataset_search` — now shows top publishers per query

package/dist/index.js

@@ -3982,301 +3982,122 @@ Typical workflow: ckan_catalog_stats (understand the portal) \u2192 ckan_package
   );
 }
 
-// src/tools/europa.ts
+// src/tools/sparql.ts
 import { z as z10 } from "zod";
-
-// src/utils/europa-http.ts
-import axios3 from "axios";
-var EUROPA_SEARCH_URL = "https://data.europa.eu/api/hub/search/search";
-async function makeEuropaSearchRequest(params) {
-  const isNode = typeof process !== "undefined" && !!process.versions?.node;
-  const searchParams = new URLSearchParams();
-  const isMatchAll = !params.q || params.q === "*" || params.q === "*:*";
-  if (!isMatchAll) {
-    searchParams.set("q", params.q);
-  }
-  searchParams.set("page", String(params.page ?? 0));
-  searchParams.set("limit", String(params.limit ?? 10));
-  searchParams.set("filters", "dataset");
-  if (params.facets && Object.keys(params.facets).length > 0) {
-    searchParams.set("facets", JSON.stringify(params.facets));
-  }
-  if (params.sort) {
-    searchParams.set("sort", params.sort);
-  }
-  const url = `${EUROPA_SEARCH_URL}?${searchParams.toString()}`;
-  let data;
-  if (isNode) {
-    const response = await axios3.get(url, {
-      timeout: 3e4,
-      headers: {
-        Accept: "application/json",
-        "User-Agent": "CKAN-MCP-Server/1.0"
-      }
-    });
-    data = response.data;
-  } else {
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), 3e4);
-    try {
-      const response = await fetch(url, {
-        method: "GET",
-        signal: controller.signal,
-        headers: {
-          Accept: "application/json",
-          "User-Agent": "CKAN-MCP-Server/1.0"
-        }
-      });
-      if (!response.ok) {
-        throw new Error(`Europa API error (${response.status}): ${response.statusText}`);
-      }
-      data = await response.json();
-    } finally {
-      clearTimeout(timeoutId);
-    }
+var DEFAULT_LIMIT = 25;
+var MAX_LIMIT = 1e3;
+function validateSelectQuery(query) {
+  const stripped = query.replace(/#[^\n]*/g, "");
+  if (!/\bSELECT\b/i.test(stripped)) {
+    throw new Error(
+      "Only SELECT queries are supported (not CONSTRUCT, ASK, DESCRIBE, or write operations)."
+    );
   }
-  const envelope = data;
-  return {
-    count: envelope?.result?.count ?? 0,
-    results: envelope?.result?.results ?? [],
-    rawFacets: envelope?.result?.facets ?? []
-  };
 }
-
-// src/tools/europa.ts
-function sanitizeText(text) {
-  return text.replace(/[\x00-\x09\x0B\x0C\x0E-\x1F]/g, " ").replace(/[\r\n]+/g, " ");
-}
-function pickLang(obj, lang) {
-  if (!obj || typeof obj !== "object") return "";
-  const raw = obj[lang] || (lang !== "en" ? obj["en"] : void 0);
-  if (raw) return sanitizeText(raw);
-  const keys = Object.keys(obj);
-  return keys.length > 0 ? sanitizeText(obj[keys[0]]) : "";
-}
-function extractFormats(dataset) {
-  if (!Array.isArray(dataset.distributions)) return [];
-  const formats = /* @__PURE__ */ new Set();
-  for (const dist of dataset.distributions) {
-    const label = dist.format?.label;
-    if (label) formats.add(label.toUpperCase());
-  }
-  return Array.from(formats).sort();
+function injectLimit(query, limit) {
+  if (/\bLIMIT\b/i.test(query)) return query;
+  return `${query.trimEnd()}
+LIMIT ${limit}`;
 }
-function extractKeywords(dataset, lang) {
-  if (!Array.isArray(dataset.keywords)) return [];
-  const kws = [];
-  for (const kw of dataset.keywords) {
-    if (kw.language === lang && kw.label) {
-      kws.push(kw.label);
-    }
+async function querySparqlEndpoint(endpointUrl, query) {
+  const url = new URL(endpointUrl);
+  if (url.protocol !== "https:") {
+    throw new Error("Only HTTPS endpoints are allowed");
   }
-  if (kws.length === 0) {
-    for (const kw of dataset.keywords) {
-      if (kw.language === "en" && kw.label) {
-        kws.push(kw.label);
-      }
-    }
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), 15e3);
+  let response;
+  try {
+    response = await fetch(endpointUrl, {
+      method: "POST",
+      signal: controller.signal,
+      headers: {
+        "Content-Type": "application/sparql-query",
+        "Accept": "application/sparql-results+json"
+      },
+      body: query
+    });
+  } finally {
+    clearTimeout(timeoutId);
   }
-  if (kws.length === 0) {
-    for (const kw of dataset.keywords) {
-      if (kw.label) kws.push(kw.label);
-    }
+  if (!response.ok) {
+    throw new Error(`SPARQL endpoint error (${response.status}): ${response.statusText}`);
   }
-  return [...new Set(kws)];
+  return response.json();
 }
-function extractDistributions(dataset) {
-  if (!Array.isArray(dataset.distributions)) return [];
-  const dists = [];
-  for (const dist of dataset.distributions) {
-    const format = dist.format?.label?.toUpperCase() || "UNKNOWN";
-    const rawDownload = dist.download_url;
-    const rawAccess = dist.access_url;
-    const download = Array.isArray(rawDownload) ? rawDownload[0] : rawDownload;
-    const access = Array.isArray(rawAccess) ? rawAccess[0] : rawAccess;
-    const url = download || access || "";
-    if (url) dists.push({ format, url });
-  }
-  return dists;
-}
-function renderEuropaSearchMarkdown(results, count, params) {
-  const { q, country, lang, page, page_size } = params;
-  let md = `# European Data Portal \u2014 Search Results
-
-`;
-  md += `**Query**: ${q}`;
-  if (country && country.length > 0) {
-    md += ` | **Country**: ${country.map((c) => c.toUpperCase()).join(", ")}`;
-  }
-  md += ` | **Results**: ${count} (page ${page}, ${page_size} per page)
-
-`;
-  if (results.length === 0) {
-    md += `No datasets found matching your query.
-`;
-    return md;
-  }
-  md += `---
-
-`;
-  results.forEach((dataset, i) => {
-    const title = pickLang(dataset.title, lang) || dataset.id;
-    const description = pickLang(dataset.description, lang);
-    const formats = extractFormats(dataset);
-    const keywords = extractKeywords(dataset, lang);
-    const countryLabel = dataset.country?.id?.toUpperCase() || "";
-    md += `### ${i + 1}. ${title}
-
-`;
-    md += `| Field | Value |
-|---|---|
-`;
-    if (countryLabel) md += `| Country | ${countryLabel} |
-`;
-    if (dataset.issued) md += `| Issued | ${formatDate(dataset.issued)} |
-`;
-    if (dataset.modified) md += `| Modified | ${formatDate(dataset.modified)} |
-`;
-    if (formats.length > 0) md += `| Formats | ${formats.join(", ")} |
-`;
-    if (keywords.length > 0) md += `| Keywords | ${keywords.slice(0, 8).join(", ")}${keywords.length > 8 ? ", ..." : ""} |
-`;
-    if (dataset.is_hvd) md += `| HVD | Yes |
-`;
-    md += `
-`;
-    if (description) {
-      const truncated = description.length > 200 ? description.substring(0, 200) + "..." : description;
-      md += `${truncated}
+function formatSparqlMarkdown(data, endpointUrl) {
+  const vars = data.head.vars;
+  const bindings = data.results.bindings;
+  let md = `# SPARQL Query Results
 
 `;
-    }
-    md += `Link: https://data.europa.eu/data/datasets/${dataset.id}
-
-`;
-    const dists = extractDistributions(dataset);
-    if (dists.length > 0) {
-      md += `**Resources** (${dists.length}):
-`;
-      for (const d of dists.slice(0, 5)) {
-        md += `- ${d.format}: ${d.url}
-`;
-      }
-      if (dists.length > 5) {
-        md += `- ... and ${dists.length - 5} more
-`;
-      }
-      md += `
+  md += `**Endpoint**: ${endpointUrl}
 `;
-    }
-    md += `---
+  md += `**Rows**: ${bindings.length}
 
 `;
-  });
-  if (count > page * page_size) {
-    md += `> More results available \u2014 use \`page: ${page + 1}\`
-`;
-  }
-  return md;
-}
-var MAX_FACET_ITEMS = 15;
-var ALLOWED_FACETS = /* @__PURE__ */ new Set([
-  "country",
-  "categories",
-  "format",
-  "is_hvd",
-  "scoring",
-  "language",
-  "subject",
-  "hvdCategory",
-  "publisher"
-]);
-function resolveFacetTitle(title, lang) {
-  if (typeof title === "string") return title;
-  return title[lang] || title["en"] || Object.values(title)[0] || "";
-}
-function resolveRawFacets(rawFacets, lang) {
-  const result = [];
-  for (const raw of rawFacets) {
-    if (!ALLOWED_FACETS.has(raw.id)) continue;
-    if (!raw.items || raw.items.length === 0) continue;
-    const items = raw.items.sort((a, b) => b.count - a.count).slice(0, MAX_FACET_ITEMS).map((item) => ({
-      id: item.id,
-      title: resolveFacetTitle(item.title, lang),
-      count: item.count
-    }));
-    result.push({ id: raw.id, title: raw.title, items });
+  if (bindings.length === 0) {
+    return md + "_No results_\n";
   }
-  return result;
-}
-function renderFacetsMarkdown(facets) {
-  if (!facets || facets.length === 0) return "";
-  let md = `## Facets
-
-`;
-  for (const facet of facets) {
-    if (!facet.items || facet.items.length === 0) continue;
-    md += `### ${facet.title || facet.id}
-
-`;
-    md += `| Value | Count |
-|---|---:|
+  md += `| ${vars.join(" | ")} |
 `;
-    for (const item of facet.items) {
-      md += `| ${item.title || item.id} | ${item.count} |
+  md += `| ${vars.map(() => "---").join(" | ")} |
 `;
-    }
-    md += `
+  for (const row of bindings) {
+    const cells = vars.map((v) => {
+      const val = row[v]?.value ?? "";
+      return val.replace(/\|/g, "\\|");
+    });
+    md += `| ${cells.join(" | ")} |
 `;
   }
   return md;
 }
-function facetsToCompactJson(facets) {
-  const result = {};
-  for (const facet of facets) {
-    if (!facet.items || facet.items.length === 0) continue;
-    result[facet.id] = facet.items.map((item) => ({
-      id: item.id,
-      title: item.title,
-      count: item.count
-    }));
-  }
-  return result;
+function formatSparqlJson(data) {
+  const vars = data.head.vars;
+  const rows = data.results.bindings.map((row) => {
+    const obj = {};
+    for (const v of vars) {
+      obj[v] = row[v]?.value ?? "";
+    }
+    return obj;
+  });
+  return { count: rows.length, columns: vars, rows };
 }
-function registerEuropaTools(server2) {
+function registerSparqlTools(server2) {
   server2.registerTool(
-    "europa_dataset_search",
+    "sparql_query",
     {
-      title: "Search European Data Portal",
-      description: `Search datasets on the European Data Portal (data.europa.eu), which aggregates 1.7M+ datasets from all EU countries.
+      title: "SPARQL Query",
+      description: `Execute a SPARQL SELECT query against any public HTTPS SPARQL endpoint.
+
+Useful for querying open data portals and knowledge graphs that expose SPARQL endpoints, including:
+- data.europa.eu (European open data portal)
+- publications.europa.eu (EU Publications Office)
+- DBpedia, Wikidata
+- Any DCAT-AP compliant data catalog
 
-This is NOT a CKAN portal. Use this tool specifically for EU-wide open data discovery.
+Only HTTPS endpoints are allowed. Queries timeout after 15 seconds.
+Only SELECT queries are supported (read-only).
+
+If the query does not contain a LIMIT clause, one is injected automatically (default: ${DEFAULT_LIMIT}, max: ${MAX_LIMIT}).
 
 Args:
-  - q (string): Search query
-  - country (string[]): ISO 3166-1 alpha-2 country codes (e.g., ["IT", "DE"])
-  - is_hvd (boolean): Filter only High Value Datasets
-  - lang (string): Language for multilingual fields (default "en")
-  - sort (enum): Sort by "relevance", "issued", "modified", "title"
-  - order (enum): Sort direction "asc" or "desc" (default "desc")
-  - page (number): Page number, 1-based (default 1)
-  - page_size (number): Results per page (default 10, max 50)
-  - response_format: "markdown" or "json" (JSON is compact: description truncated, max 3 distributions)
+  - endpoint_url (string): HTTPS URL of the SPARQL endpoint
+  - query (string): SPARQL SELECT query to execute
+  - limit (number): Max rows to return (default: ${DEFAULT_LIMIT}). Ignored if query already contains LIMIT.
+  - response_format ('markdown' | 'json'): Output format
 
 Examples:
-  - { q: "environment", country: ["IT"], page_size: 5 }
-  - { q: "transport", sort: "modified", order: "desc" }
-  - { q: "health data", lang: "it" }
-  - { q: "transport", is_hvd: true }`,
+  - Count Italian HVD datasets by publisher on data.europa.eu
+  - Query Wikidata for entities related to a dataset topic
+  - Explore EU controlled vocabularies on publications.europa.eu
+
+Typical workflow: sparql_query (explore schema) \u2192 sparql_query (targeted query) \u2192 ckan_package_search (get dataset details)`,
       inputSchema: z10.object({
-        q: z10.string().min(1).describe("Search query"),
-        country: z10.array(z10.string().length(2)).optional().describe("ISO 3166-1 alpha-2 country codes"),
-        is_hvd: z10.boolean().optional().describe("Filter only High Value Datasets (HVD)"),
-        lang: z10.string().optional().default("en").describe("Language for multilingual fields"),
-        sort: z10.enum(["relevance", "issued", "modified", "title"]).optional().describe("Sort field"),
-        order: z10.enum(["asc", "desc"]).optional().default("desc").describe("Sort direction"),
-        page: z10.number().int().min(1).optional().default(1).describe("Page number (1-based)"),
-        page_size: z10.number().int().min(1).max(50).optional().default(10).describe("Results per page"),
+        endpoint_url: z10.string().url().describe("HTTPS URL of the SPARQL endpoint"),
+        query: z10.string().min(1).describe("SPARQL SELECT query to execute"),
+        limit: z10.number().int().min(1).max(MAX_LIMIT).default(DEFAULT_LIMIT).describe(`Max rows to return (default: ${DEFAULT_LIMIT}, max: ${MAX_LIMIT}). Injected as SPARQL LIMIT if not already present in query.`),
         response_format: ResponseFormatSchema
       }).strict(),
       annotations: {
@@ -4288,67 +4109,31 @@ Examples:
     },
     async (params) => {
       try {
-        const filterFacets = {};
-        if (params.country && params.country.length > 0) {
-          filterFacets.country = params.country.map((c) => c.toLowerCase());
-        }
-        if (params.is_hvd) {
-          filterFacets.is_hvd = ["true"];
-        }
-        let sortParam;
-        if (params.sort && params.sort !== "relevance") {
-          sortParam = `${params.sort}+${params.order}`;
-        }
-        const { count, results, rawFacets } = await makeEuropaSearchRequest({
-          q: params.q,
-          page: params.page - 1,
-          limit: params.page_size,
-          facets: Object.keys(filterFacets).length > 0 ? filterFacets : void 0,
-          sort: sortParam
-        });
-        const facets = resolveRawFacets(rawFacets, params.lang);
+        validateSelectQuery(params.query);
+        const limitedQuery = injectLimit(params.query, params.limit);
+        const data = await querySparqlEndpoint(params.endpoint_url, limitedQuery);
         if (params.response_format === "json" /* JSON */) {
-          const filtered = results.map((d) => {
-            const desc = pickLang(d.description, params.lang);
-            const dists = extractDistributions(d);
-            return {
-              id: d.id,
-              title: pickLang(d.title, params.lang),
-              description: desc.length > 200 ? desc.substring(0, 200) + "..." : desc,
-              issued: d.issued ?? null,
-              modified: d.modified ?? null,
-              country: d.country?.id?.toUpperCase() || null,
-              formats: extractFormats(d),
-              keywords: extractKeywords(d, params.lang).slice(0, 5),
-              is_hvd: d.is_hvd ?? false,
-              link: `https://data.europa.eu/data/datasets/${d.id}`,
-              distributions: dists.slice(0, 3)
-            };
-          });
-          const compactFacets = facetsToCompactJson(facets);
+          const result = formatSparqlJson(data);
+          let text2 = JSON.stringify(result, null, 2);
+          if (text2.length > CHARACTER_LIMIT) {
+            text2 = text2.slice(0, CHARACTER_LIMIT) + "\n/* output truncated */";
+          }
           return {
-            content: [{
-              type: "text",
-              text: truncateText(JSON.stringify({ count, results: filtered, facets: compactFacets }, null, 2))
-            }]
+            content: [{ type: "text", text: text2 }],
+            structuredContent: result
           };
         }
-        let markdown = renderEuropaSearchMarkdown(results, count, {
-          q: params.q,
-          country: params.country,
-          lang: params.lang,
-          page: params.page,
-          page_size: params.page_size
-        });
-        markdown += renderFacetsMarkdown(facets);
-        return {
-          content: [{ type: "text", text: truncateText(addDemoFooter(markdown)) }]
-        };
+        let text = formatSparqlMarkdown(data, params.endpoint_url);
+        if (text.length > CHARACTER_LIMIT) {
+          text = text.slice(0, CHARACTER_LIMIT) + "\n\n_Output truncated._";
+        }
+        return { content: [{ type: "text", text }] };
       } catch (error) {
         return {
           content: [{
             type: "text",
-            text: `Error searching European Data Portal: ${error instanceof Error ? error.message : String(error)}`
+            text: `SPARQL query failed:
+${error instanceof Error ? error.message : String(error)}`
           }],
           isError: true
         };
@@ -4896,7 +4681,7 @@ var registerAllPrompts = (server2) => {
 function createServer() {
   return new McpServer({
     name: "ckan-mcp-server",
-    version: "0.4.63"
+    version: "0.4.67"
   });
 }
 function registerAll(server2) {
@@ -4909,7 +4694,7 @@ function registerAll(server2) {
   registerQualityTools(server2);
   registerAnalyzeTools(server2);
   registerCatalogStatsTools(server2);
-  registerEuropaTools(server2);
+  registerSparqlTools(server2);
   registerAllResources(server2);
   registerAllPrompts(server2);
 }