@aborruso/ckan-mcp-server 0.4.64 → 0.4.66

package/LOG.md

@@ -1,5 +1,15 @@
 # LOG
 
+## 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
+
 ## 2026-03-04 (v0.4.64)
 
 - fix(europa): `q=*` now correctly returns all 1.7M+ datasets — Europa API ignores `q` when omitted; sending `q=*` was causing Elasticsearch to return only ~6k results; match-all queries (`*`, `*:*`) now omit the `q` parameter

package/dist/index.js

@@ -4188,7 +4188,8 @@ var ALLOWED_FACETS = /* @__PURE__ */ new Set([
   "scoring",
   "language",
   "subject",
-  "hvdCategory"
+  "hvdCategory",
+  "publisher"
 ]);
 function resolveFacetTitle(title, lang) {
   if (typeof title === "string") return title;
@@ -4262,6 +4263,15 @@ Args:
   - page_size (number): Results per page (default 10, max 50)
   - response_format: "markdown" or "json" (JSON is compact: description truncated, max 3 distributions)
 
+Available facets (fixed \u2014 returned automatically): country, categories, format, language, is_hvd, hvdCategory, scoring.
+Publisher/organization breakdown is NOT available as a facet here. Use sparql_query on https://data.europa.eu/sparql for that.
+
+When to use sparql_query instead of this tool:
+  - Count or list datasets grouped by publisher/organization
+  - Query any property not exposed as a facet (e.g., license URI, spatial coverage, themes)
+  - Cross-join datasets with EU controlled vocabularies (publications.europa.eu)
+  - Any aggregation or filter not supported by the search API
+
 Examples:
   - { q: "environment", country: ["IT"], page_size: 5 }
   - { q: "transport", sort: "modified", order: "desc" }
@@ -4356,6 +4366,138 @@ Examples:
   );
 }
 
+// src/tools/sparql.ts
+import { z as z11 } from "zod";
+async function querySparqlEndpoint(endpointUrl, query) {
+  const url = new URL(endpointUrl);
+  if (url.protocol !== "https:") {
+    throw new Error("Only HTTPS endpoints are allowed");
+  }
+  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 (!response.ok) {
+    throw new Error(`SPARQL endpoint error (${response.status}): ${response.statusText}`);
+  }
+  return response.json();
+}
+function formatSparqlMarkdown(data, endpointUrl) {
+  const vars = data.head.vars;
+  const bindings = data.results.bindings;
+  let md = `# SPARQL Query Results
+
+`;
+  md += `**Endpoint**: ${endpointUrl}
+`;
+  md += `**Rows**: ${bindings.length}
+
+`;
+  if (bindings.length === 0) {
+    return md + "_No results_\n";
+  }
+  md += `| ${vars.join(" | ")} |
+`;
+  md += `| ${vars.map(() => "---").join(" | ")} |
+`;
+  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 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 registerSparqlTools(server2) {
+  server2.registerTool(
+    "sparql_query",
+    {
+      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
+
+Only HTTPS endpoints are allowed. Queries timeout after 15 seconds.
+Only SELECT queries are supported (read-only).
+
+Args:
+  - endpoint_url (string): HTTPS URL of the SPARQL endpoint
+  - query (string): SPARQL SELECT query to execute
+  - response_format ('markdown' | 'json'): Output format
+
+Examples:
+  - 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: z11.object({
+        endpoint_url: z11.string().url().describe("HTTPS URL of the SPARQL endpoint"),
+        query: z11.string().min(1).describe("SPARQL SELECT query to execute"),
+        response_format: ResponseFormatSchema
+      }).strict(),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      }
+    },
+    async (params) => {
+      try {
+        const data = await querySparqlEndpoint(params.endpoint_url, params.query);
+        if (params.response_format === "json" /* JSON */) {
+          return {
+            content: [{ type: "text", text: JSON.stringify(formatSparqlJson(data), null, 2) }],
+            structuredContent: formatSparqlJson(data)
+          };
+        }
+        return {
+          content: [{ type: "text", text: formatSparqlMarkdown(data, params.endpoint_url) }]
+        };
+      } catch (error) {
+        return {
+          content: [{
+            type: "text",
+            text: `SPARQL query failed:
+${error instanceof Error ? error.message : String(error)}`
+          }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
 // src/resources/dataset.ts
 import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 
@@ -4625,7 +4767,7 @@ function registerAllResources(server2) {
 }
 
 // src/prompts/theme.ts
-import { z as z11 } from "zod";
+import { z as z12 } from "zod";
 
 // src/prompts/types.ts
 var createTextPrompt = (text) => ({
@@ -4686,9 +4828,9 @@ var registerThemePrompt = (server2) => {
       title: "Search datasets by theme",
       description: "Guided prompt to discover a theme and search datasets under it.",
       argsSchema: {
-        server_url: z11.string().url().describe("Base URL of the CKAN server"),
-        theme: z11.string().min(1).describe("Theme or group name to search"),
-        rows: z11.coerce.number().int().positive().default(10).describe("Max results to return")
+        server_url: z12.string().url().describe("Base URL of the CKAN server"),
+        theme: z12.string().min(1).describe("Theme or group name to search"),
+        rows: z12.coerce.number().int().positive().default(10).describe("Max results to return")
       }
     },
     async ({ server_url, theme, rows }) => createTextPrompt(buildThemePromptText(server_url, theme, rows))
@@ -4696,7 +4838,7 @@ var registerThemePrompt = (server2) => {
 };
 
 // src/prompts/organization.ts
-import { z as z12 } from "zod";
+import { z as z13 } from "zod";
 var ORGANIZATION_PROMPT_NAME = "ckan-search-by-organization";
 var buildOrganizationPromptText = (serverUrl, organization, rows) => `# Guided search: datasets by organization
 
@@ -4731,9 +4873,9 @@ var registerOrganizationPrompt = (server2) => {
       title: "Search datasets by organization",
       description: "Guided prompt to find a publisher and list its datasets.",
       argsSchema: {
-        server_url: z12.string().url().describe("Base URL of the CKAN server"),
-        organization: z12.string().min(1).describe("Organization name or keyword"),
-        rows: z12.coerce.number().int().positive().default(10).describe("Max results to return")
+        server_url: z13.string().url().describe("Base URL of the CKAN server"),
+        organization: z13.string().min(1).describe("Organization name or keyword"),
+        rows: z13.coerce.number().int().positive().default(10).describe("Max results to return")
       }
     },
     async ({ server_url, organization, rows }) => createTextPrompt(buildOrganizationPromptText(server_url, organization, rows))
@@ -4741,7 +4883,7 @@ var registerOrganizationPrompt = (server2) => {
 };
 
 // src/prompts/format.ts
-import { z as z13 } from "zod";
+import { z as z14 } from "zod";
 var FORMAT_PROMPT_NAME = "ckan-search-by-format";
 var buildFormatPromptText = (serverUrl, format, rows) => `# Guided search: datasets by resource format
 
@@ -4765,9 +4907,9 @@ var registerFormatPrompt = (server2) => {
       title: "Search datasets by resource format",
       description: "Guided prompt to find datasets with a given resource format.",
       argsSchema: {
-        server_url: z13.string().url().describe("Base URL of the CKAN server"),
-        format: z13.string().min(1).describe("Resource format (e.g., CSV, JSON)"),
-        rows: z13.coerce.number().int().positive().default(10).describe("Max results to return")
+        server_url: z14.string().url().describe("Base URL of the CKAN server"),
+        format: z14.string().min(1).describe("Resource format (e.g., CSV, JSON)"),
+        rows: z14.coerce.number().int().positive().default(10).describe("Max results to return")
       }
     },
     async ({ server_url, format, rows }) => createTextPrompt(buildFormatPromptText(server_url, format, rows))
@@ -4775,7 +4917,7 @@ var registerFormatPrompt = (server2) => {
 };
 
 // src/prompts/recent.ts
-import { z as z14 } from "zod";
+import { z as z15 } from "zod";
 var RECENT_PROMPT_NAME = "ckan-recent-datasets";
 var buildRecentPromptText = (serverUrl, rows) => `# Guided search: recent datasets
 
@@ -4823,8 +4965,8 @@ var registerRecentPrompt = (server2) => {
       title: "Find recently updated datasets",
       description: "Guided prompt to list recently updated datasets on a CKAN portal.",
       argsSchema: {
-        server_url: z14.string().url().describe("Base URL of the CKAN server"),
-        rows: z14.coerce.number().int().positive().default(10).describe("Max results to return")
+        server_url: z15.string().url().describe("Base URL of the CKAN server"),
+        rows: z15.coerce.number().int().positive().default(10).describe("Max results to return")
       }
     },
     async ({ server_url, rows }) => createTextPrompt(buildRecentPromptText(server_url, rows))
@@ -4832,7 +4974,7 @@ var registerRecentPrompt = (server2) => {
 };
 
 // src/prompts/dataset-analysis.ts
-import { z as z15 } from "zod";
+import { z as z16 } from "zod";
 var DATASET_ANALYSIS_PROMPT_NAME = "ckan-analyze-dataset";
 var buildDatasetAnalysisPromptText = (serverUrl, id) => `# Guided analysis: dataset
 
@@ -4874,8 +5016,8 @@ var registerDatasetAnalysisPrompt = (server2) => {
       title: "Analyze a dataset",
       description: "Guided prompt to inspect dataset metadata and explore DataStore tables.",
       argsSchema: {
-        server_url: z15.string().url().describe("Base URL of the CKAN server"),
-        id: z15.string().min(1).describe("Dataset id or name (CKAN package id)")
+        server_url: z16.string().url().describe("Base URL of the CKAN server"),
+        id: z16.string().min(1).describe("Dataset id or name (CKAN package id)")
       }
     },
     async ({ server_url, id }) => createTextPrompt(buildDatasetAnalysisPromptText(server_url, id))
@@ -4895,7 +5037,7 @@ var registerAllPrompts = (server2) => {
 function createServer() {
   return new McpServer({
     name: "ckan-mcp-server",
-    version: "0.4.63"
+    version: "0.4.66"
   });
 }
 function registerAll(server2) {
@@ -4909,6 +5051,7 @@ function registerAll(server2) {
   registerAnalyzeTools(server2);
   registerCatalogStatsTools(server2);
   registerEuropaTools(server2);
+  registerSparqlTools(server2);
   registerAllResources(server2);
   registerAllPrompts(server2);
 }