@aborruso/ckan-mcp-server 0.4.16 → 0.4.18

package/LOG.md

@@ -1,7 +1,85 @@
 # LOG
 
+## 2026-01-26
+
+### Release v0.4.18
+
+- MQA quality output now includes dimension score breakdown with ✅/⚠️ indicators
+- Metrics endpoint link added for direct score inspection
+- Non-max dimension(s) highlighted for quick diagnosis
+- Files: `src/tools/quality.ts`, `tests/integration/quality.test.ts`, `tests/fixtures/responses/mqa-metrics-success.json`
+
+### MQA Quality Metrics - Readable dimension scores
+- **Feature**: Add dimension score breakdown with ✅/⚠️ indicators and non-max dimensions
+- **Source**: Fetch metrics JSON-LD from data.europa.eu for scoring details
+- **Output**: Markdown and JSON include metrics endpoint link and derived scores
+- **Files**: `src/tools/quality.ts`, `tests/integration/quality.test.ts`, `tests/fixtures/responses/mqa-metrics-success.json`
+
+### Website - Fix color contrast issues
+- **Fix**: Added custom color definitions to `tailwind.config.mjs`
+- **Colors**: navy (#0A1628), data-blue (#0066CC), teal (#0D9488), coral (#F97316), amber (#F59E0B), cream (#FFFEF9)
+- **Impact**: CTA section and all custom-colored elements now render correctly with proper contrast
+- **Before**: Custom Tailwind classes (bg-navy, text-data-blue, etc.) were ignored, causing transparent backgrounds and unreadable text
+- **After**: All colors apply correctly, navy CTA section has proper dark background with white/gray text
+
+## 2026-01-25
+
+### Website - Landing Page
+- **Website**: Created production-ready landing page in `website/` directory
+- **Stack**: Astro v5 + React + Tailwind CSS + TypeScript strict mode
+- **Deployment**: GitHub Actions workflow for automatic GitHub Pages deployment
+- **URL**: https://ondata.github.io/ckan-mcp-server/
+- **Content**:
+  - Hero section with value proposition for open data researchers
+  - Features section (6 key capabilities)
+  - Quick start with copy-paste configs (Claude Desktop, VS Code, Cloudflare Workers, global npm)
+  - Use cases (researchers, data scientists, students, journalists, etc.)
+  - Supported portals showcase (dati.gov.it, data.gov, data.europa.eu, etc.)
+  - SEO optimized (meta tags, Open Graph, sitemap)
+  - Responsive design (mobile-first, accessible WCAG AA)
+- **Assets**:
+  - SVG favicon with network graph icon
+  - manifest.json for PWA support
+  - robots.txt and sitemap
+  - Script for PNG favicon generation (`generate-favicons.sh`)
+- **Files**:
+  - `website/src/pages/index.astro` (main landing page)
+  - `website/src/layouts/Layout.astro` (SEO layout)
+  - `website/src/components/Footer.astro`
+  - `website/public/favicon.svg`, `manifest.json`, `robots.txt`
+  - `.github/workflows/deploy-website.yml` (deployment automation)
+  - `website/README.md` (documentation)
+- **Build**: 396 packages, builds successfully in ~1s
+- **Deployment trigger**: Push to main branch with changes in `website/` directory
+
+### Documentation - MCP Inspector
+- **README**: Added "Exploring the Server" section before "Manual Testing"
+- **Tool**: MCP Inspector for interactive server exploration
+- **Usage**: `npx @modelcontextprotocol/inspector node dist/index.js`
+- **Features**: Browse tools/resources, test calls with auto-complete, real-time responses, debug errors
+- **Impact**: Developers can quickly explore and test server without manual JSON-RPC
+
 ## 2026-01-23
 
+### Release v0.4.17
+
+- Published to npm: `@aborruso/ckan-mcp-server@0.4.17`
+- Aligned with GitHub tag `v0.4.17`
+
+### MQA Quality Metrics - Identifier normalization and disambiguation
+
+- **Fix**: Normalize identifiers for data.europa.eu lookups (lowercase, collapse hyphens)
+- **Fix**: Retry with disambiguation suffixes (`~~1`, `~~2`) when base identifier 404s
+- **Result**: MQA quality now matches portal IDs for datasets like Beinasco (with `~~1`)
+- **Improved errors**: clearer message when identifier is not aligned
+- **Files modified**: `src/tools/quality.ts`, `tests/integration/quality.test.ts`
+- **Deployed**: Cloudflare Workers v0.4.17
+
+### Release v0.4.16
+
+- Published to npm: `@aborruso/ckan-mcp-server@0.4.16`
+- Aligned with GitHub tag `v0.4.16`
+
 ### MQA Quality Metrics - Fix identifier format
 
 - **Bug fix**: Identifier transformation for data.europa.eu API compatibility

package/README.md

@@ -67,7 +67,7 @@ Deploy on your own server using Node.js:
 TRANSPORT=http PORT=3000 npm start
 ```
 
-### Option 3: Cloudflare Workers ⭐ NEW
+### Option 3: Cloudflare Workers
 
 **Best for**: Global access, zero infrastructure, free hosting
 
@@ -83,84 +83,128 @@ Use the public Workers endpoint (no local install required):
 }
 ```
 
-**NOTE**: This service uses the Cloudflare Workers free tier which has a limit of 100,000 requests per month.
+**NOTE**: This service uses the Cloudflare Workers free tier which has a limit of 100,000 requests per month. **ITS OPERATION IS THEREFORE NOT GUARANTEED**. With local installation, you will not have any problems.
 
 Want your own deployment? See [DEPLOYMENT.md](docs/DEPLOYMENT.md).
 
-## Guides
+## MCP Client Configuration
 
-### Claude Desktop Configuration
+This server works with any MCP-compatible client. Below are configuration examples for popular clients, organized by category. Using `@aborruso/ckan-mcp-server@latest` ensures you always get the latest version.
 
-Configuration file location:
+### CLI Tools
 
-- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
-- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+#### Codex
 
-#### Option 1: Global Installation (Recommended)
+```json
+{
+  "mcpServers": {
+    "ckan": {
+      "command": "npx",
+      "args": ["@aborruso/ckan-mcp-server@latest"]
+    }
+  }
+}
+```
 
-Install globally to use across all projects:
+#### Copilot CLI
 
 ```bash
-npm install -g @aborruso/ckan-mcp-server
+copilot mcp add ckan npx @aborruso/ckan-mcp-server@latest
+```
+
+#### Gemini CLI
+
+```bash
+gemini mcp add ckan npx @aborruso/ckan-mcp-server@latest
 ```
 
-Then add to `claude_desktop_config.json`:
+### IDEs & Code Editors
+
+#### Copilot / VS Code
+
+Add to VS Code settings (`.vscode/settings.json` or User Settings):
 
 ```json
 {
   "mcpServers": {
     "ckan": {
-      "command": "ckan-mcp-server"
+      "command": "npx",
+      "args": ["@aborruso/ckan-mcp-server@latest"]
     }
   }
 }
 ```
 
-#### Option 2: Local Project Installation (Optional)
+#### Cursor
 
-If you want to install the server in a specific project:
+Add to Cursor MCP settings:
 
-```bash
-cd your-project
-npm install @aborruso/ckan-mcp-server
+```json
+{
+  "mcpServers": {
+    "ckan": {
+      "command": "npx",
+      "args": ["@aborruso/ckan-mcp-server@latest"]
+    }
+  }
+}
 ```
 
-Then add to `claude_desktop_config.json`:
+#### OpenCode
+
+Add to OpenCode configuration:
 
 ```json
 {
   "mcpServers": {
     "ckan": {
       "command": "npx",
-      "args": ["@aborruso/ckan-mcp-server"]
+      "args": ["@aborruso/ckan-mcp-server@latest"]
     }
   }
 }
 ```
 
-**Note**: `npx` will use the locally installed package in `node_modules`. Make sure to install the package first.
+### Desktop Applications
 
-#### Option 3: From Source
+#### Claude Desktop
 
-If you cloned the repository:
+Configuration file location:
+
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+**Using npx (recommended)**:
 
 ```json
 {
   "mcpServers": {
     "ckan": {
-      "command": "node",
-      "args": ["/absolute/path/to/ckan-mcp-server/dist/index.js"]
+      "command": "npx",
+      "args": ["@aborruso/ckan-mcp-server@latest"]
     }
   }
 }
 ```
 
-[A detailed guide](https://github.com/ondata/ckan-mcp-server/discussions/4#discussion-9359684)
+**Using global installation**:
+
+```bash
+npm install -g @aborruso/ckan-mcp-server
+```
 
-#### Option 4: Cloudflare Workers (HTTP transport)
+```json
+{
+  "mcpServers": {
+    "ckan": {
+      "command": "ckan-mcp-server"
+    }
+  }
+}
+```
 
-Use the public Cloudflare Workers deployment (no local installation required):
+**Using Cloudflare Workers (HTTP)**:
 
 ```json
 {
@@ -172,16 +216,21 @@ Use the public Cloudflare Workers deployment (no local installation required):
 }
 ```
 
-**NOTE**: This service uses the Cloudflare Workers free tier which has a limit of 100,000 requests per month.
+**NOTE**: The Cloudflare Workers endpoint uses the free tier (100,000 requests/month limit).
 
-**Note**: This uses the public endpoint. You can also deploy your own Workers instance and use that URL instead.
+[Detailed guide](https://github.com/ondata/ckan-mcp-server/discussions/4#discussion-9359684)
 
-### Web Tools Configuration
+### Web Tools
 
-- [ChatGPT web](docs/guide/chatgpt/chatgpt_web.md)
-- [Claude web](docs/guide/claude/claude_web.md)
+#### ChatGPT
 
-These guides are based on a public demo server, which has a limit of 100,000 calls per month. For reliable usage, it is recommended to install the CKAN MCP Server on your own machine.
+See [ChatGPT web guide](docs/guide/chatgpt/chatgpt_web.md)
+
+#### Claude
+
+See [Claude web guide](docs/guide/claude/claude_web.md)
+
+**Note**: Web tools use a public demo server with 100,000 calls/month limit. For reliable usage, install the server locally.
 
 ## Available Tools
 
@@ -617,6 +666,27 @@ npm run build
 npm run watch
 ```
 
+### Exploring the Server
+
+If you want to explore and test the server interactively, use the MCP Inspector:
+
+```bash
+# Install MCP Inspector globally (one-time setup)
+npm install -g @modelcontextprotocol/inspector
+
+# Build the server
+npm run build
+
+# Launch Inspector with your server
+npx @modelcontextprotocol/inspector node dist/index.js
+```
+
+This opens a web interface (usually at `http://localhost:5173`) where you can:
+- Browse all registered tools and resources
+- Test tool calls with auto-complete for parameters
+- See real-time responses in both JSON and rendered format
+- Debug errors with detailed stack traces
+
 ### Manual Testing
 
 ```bash

package/dist/index.js

@@ -2111,91 +2111,207 @@ var ALLOWED_SERVER_PATTERNS = [
 function isValidMqaServer(serverUrl) {
   return ALLOWED_SERVER_PATTERNS.some((pattern) => pattern.test(serverUrl));
 }
+function normalizeMqaIdentifier(identifier) {
+  return identifier.trim().replace(/:/g, "-").replace(/-+/g, "-").toLowerCase();
+}
+function buildMqaIdCandidates(identifier) {
+  const base = normalizeMqaIdentifier(identifier);
+  if (!base) {
+    return [];
+  }
+  const candidates = [base];
+  if (!base.includes("~~")) {
+    candidates.push(`${base}~~1`, `${base}~~2`);
+  }
+  return candidates;
+}
 async function getMqaQuality(serverUrl, datasetId) {
   const dataset = await makeCkanRequest(
     serverUrl,
     "package_show",
     { id: datasetId }
   );
-  const europeanId = (dataset.identifier || dataset.name).replace(/:/g, "-");
-  const mqaUrl = `${MQA_API_BASE}/${europeanId}`;
-  try {
-    const response = await axios2.get(mqaUrl, {
-      timeout: 3e4,
-      headers: {
-        "User-Agent": "CKAN-MCP-Server/1.0"
+  const baseIdentifier = dataset.identifier || dataset.name;
+  const candidates = buildMqaIdCandidates(baseIdentifier);
+  if (candidates.length === 0) {
+    throw new Error("Dataset identifier is empty; cannot query MQA API");
+  }
+  for (const europeanId of candidates) {
+    const mqaUrl = `${MQA_API_BASE}/${europeanId}`;
+    try {
+      const response = await axios2.get(mqaUrl, {
+        timeout: 3e4,
+        headers: {
+          "User-Agent": "CKAN-MCP-Server/1.0"
+        }
+      });
+      return response.data;
+    } catch (error) {
+      if (axios2.isAxiosError(error)) {
+        if (error.response?.status === 404) {
+          continue;
+        }
+        throw new Error(`MQA API error: ${error.message}`);
       }
-    });
-    return response.data;
-  } catch (error) {
-    if (axios2.isAxiosError(error)) {
-      if (error.response?.status === 404) {
-        throw new Error(`Quality metrics not found for dataset '${europeanId}' on data.europa.eu`);
+      throw error;
+    }
+  }
+  throw new Error(
+    `Quality metrics not found or identifier not aligned on data.europa.eu. Tried: ${candidates.join(", ")}. Check the dataset quality page on data.europa.eu to confirm the identifier (it may include a '~~1' suffix) or verify alignment on dati.gov.it (quality may be marked as 'Non disponibile o identificativo non allineato').`
+  );
+}
+function findSectionMetric(section, key) {
+  if (!Array.isArray(section)) {
+    return void 0;
+  }
+  for (const item of section) {
+    if (item && typeof item === "object" && key in item) {
+      return item[key];
+    }
+  }
+  return void 0;
+}
+function metricArrayIsAvailable(metric) {
+  if (!Array.isArray(metric)) {
+    return void 0;
+  }
+  const byName = /* @__PURE__ */ new Map();
+  for (const entry of metric) {
+    if (!entry || typeof entry !== "object") {
+      continue;
+    }
+    const name = entry.name;
+    const percentage = entry.percentage;
+    if (typeof name === "string" && typeof percentage === "number") {
+      byName.set(name.toLowerCase(), percentage);
+    }
+  }
+  if (byName.has("yes")) {
+    return (byName.get("yes") || 0) > 0;
+  }
+  if (byName.size > 0) {
+    for (const [name, percentage] of byName.entries()) {
+      if (name.startsWith("2") && percentage > 0) {
+        return true;
       }
-      throw new Error(`MQA API error: ${error.message}`);
     }
-    throw error;
+    return false;
+  }
+  return void 0;
+}
+function metricBoolean(section, key) {
+  const metric = findSectionMetric(section, key);
+  if (typeof metric === "boolean") {
+    return metric;
+  }
+  return void 0;
+}
+function metricAvailability(section, availabilityKey, statusKey) {
+  const availabilityMetric = findSectionMetric(section, availabilityKey);
+  const availability = metricArrayIsAvailable(availabilityMetric);
+  if (availability !== void 0) {
+    return { available: availability };
   }
+  if (statusKey) {
+    const statusMetric = findSectionMetric(section, statusKey);
+    const statusAvailable = metricArrayIsAvailable(statusMetric);
+    if (statusAvailable !== void 0) {
+      return { available: statusAvailable };
+    }
+  }
+  return void 0;
+}
+function normalizeQualityData(data) {
+  const resultEntry = data?.result?.results?.[0];
+  if (!resultEntry || typeof resultEntry !== "object") {
+    return data;
+  }
+  return {
+    id: resultEntry.info?.["dataset-id"],
+    info: { score: resultEntry.info?.score },
+    accessibility: {
+      accessUrl: metricAvailability(resultEntry.accessibility, "accessUrlAvailability", "accessUrlStatusCode"),
+      downloadUrl: metricAvailability(resultEntry.accessibility, "downloadUrlAvailability", "downloadUrlStatusCode")
+    },
+    reusability: {
+      licence: metricAvailability(resultEntry.reusability, "licenceAvailability"),
+      contactPoint: metricBoolean(resultEntry.reusability, "contactPointAvailability") !== void 0 ? { available: metricBoolean(resultEntry.reusability, "contactPointAvailability") } : void 0,
+      publisher: metricBoolean(resultEntry.reusability, "publisherAvailability") !== void 0 ? { available: metricBoolean(resultEntry.reusability, "publisherAvailability") } : void 0
+    },
+    interoperability: {
+      format: metricAvailability(resultEntry.interoperability, "formatAvailability"),
+      mediaType: metricAvailability(resultEntry.interoperability, "mediaTypeAvailability")
+    },
+    findability: {
+      keyword: metricBoolean(resultEntry.findability, "keywordAvailability") !== void 0 ? { available: metricBoolean(resultEntry.findability, "keywordAvailability") } : void 0,
+      category: metricBoolean(resultEntry.findability, "categoryAvailability") !== void 0 ? { available: metricBoolean(resultEntry.findability, "categoryAvailability") } : void 0,
+      spatial: metricBoolean(resultEntry.findability, "spatialAvailability") !== void 0 ? { available: metricBoolean(resultEntry.findability, "spatialAvailability") } : void 0,
+      temporal: metricBoolean(resultEntry.findability, "temporalAvailability") !== void 0 ? { available: metricBoolean(resultEntry.findability, "temporalAvailability") } : void 0
+    }
+  };
 }
 function formatQualityMarkdown(data, datasetId) {
+  const normalized = normalizeQualityData(data);
   const lines = [];
   lines.push(`# Quality Metrics for Dataset: ${datasetId}`);
   lines.push("");
-  if (data.info?.score !== void 0) {
-    lines.push(`**Overall Score**: ${data.info.score}/405`);
+  if (normalized.info?.score !== void 0) {
+    lines.push(`**Overall Score**: ${normalized.info.score}/405`);
     lines.push("");
   }
-  if (data.accessibility) {
+  if (normalized.accessibility) {
     lines.push("## Accessibility");
-    if (data.accessibility.accessUrl !== void 0) {
-      lines.push(`- Access URL: ${data.accessibility.accessUrl.available ? "\u2713" : "\u2717"} Available`);
+    if (normalized.accessibility.accessUrl !== void 0) {
+      lines.push(`- Access URL: ${normalized.accessibility.accessUrl.available ? "\u2713" : "\u2717"} Available`);
     }
-    if (data.accessibility.downloadUrl !== void 0) {
-      lines.push(`- Download URL: ${data.accessibility.downloadUrl.available ? "\u2713" : "\u2717"} Available`);
+    if (normalized.accessibility.downloadUrl !== void 0) {
+      lines.push(`- Download URL: ${normalized.accessibility.downloadUrl.available ? "\u2713" : "\u2717"} Available`);
     }
     lines.push("");
   }
-  if (data.reusability) {
+  if (normalized.reusability) {
     lines.push("## Reusability");
-    if (data.reusability.licence !== void 0) {
-      lines.push(`- License: ${data.reusability.licence.available ? "\u2713" : "\u2717"} Available`);
+    if (normalized.reusability.licence !== void 0) {
+      lines.push(`- License: ${normalized.reusability.licence.available ? "\u2713" : "\u2717"} Available`);
     }
-    if (data.reusability.contactPoint !== void 0) {
-      lines.push(`- Contact Point: ${data.reusability.contactPoint.available ? "\u2713" : "\u2717"} Available`);
+    if (normalized.reusability.contactPoint !== void 0) {
+      lines.push(`- Contact Point: ${normalized.reusability.contactPoint.available ? "\u2713" : "\u2717"} Available`);
     }
-    if (data.reusability.publisher !== void 0) {
-      lines.push(`- Publisher: ${data.reusability.publisher.available ? "\u2713" : "\u2717"} Available`);
+    if (normalized.reusability.publisher !== void 0) {
+      lines.push(`- Publisher: ${normalized.reusability.publisher.available ? "\u2713" : "\u2717"} Available`);
     }
     lines.push("");
   }
-  if (data.interoperability) {
+  if (normalized.interoperability) {
     lines.push("## Interoperability");
-    if (data.interoperability.format !== void 0) {
-      lines.push(`- Format: ${data.interoperability.format.available ? "\u2713" : "\u2717"} Available`);
+    if (normalized.interoperability.format !== void 0) {
+      lines.push(`- Format: ${normalized.interoperability.format.available ? "\u2713" : "\u2717"} Available`);
     }
-    if (data.interoperability.mediaType !== void 0) {
-      lines.push(`- Media Type: ${data.interoperability.mediaType.available ? "\u2713" : "\u2717"} Available`);
+    if (normalized.interoperability.mediaType !== void 0) {
+      lines.push(`- Media Type: ${normalized.interoperability.mediaType.available ? "\u2713" : "\u2717"} Available`);
     }
     lines.push("");
   }
-  if (data.findability) {
+  if (normalized.findability) {
     lines.push("## Findability");
-    if (data.findability.keyword !== void 0) {
-      lines.push(`- Keywords: ${data.findability.keyword.available ? "\u2713" : "\u2717"} Available`);
+    if (normalized.findability.keyword !== void 0) {
+      lines.push(`- Keywords: ${normalized.findability.keyword.available ? "\u2713" : "\u2717"} Available`);
     }
-    if (data.findability.category !== void 0) {
-      lines.push(`- Category: ${data.findability.category.available ? "\u2713" : "\u2717"} Available`);
+    if (normalized.findability.category !== void 0) {
+      lines.push(`- Category: ${normalized.findability.category.available ? "\u2713" : "\u2717"} Available`);
     }
-    if (data.findability.spatial !== void 0) {
-      lines.push(`- Spatial: ${data.findability.spatial.available ? "\u2713" : "\u2717"} Available`);
+    if (normalized.findability.spatial !== void 0) {
+      lines.push(`- Spatial: ${normalized.findability.spatial.available ? "\u2713" : "\u2717"} Available`);
     }
-    if (data.findability.temporal !== void 0) {
-      lines.push(`- Temporal: ${data.findability.temporal.available ? "\u2713" : "\u2717"} Available`);
+    if (normalized.findability.temporal !== void 0) {
+      lines.push(`- Temporal: ${normalized.findability.temporal.available ? "\u2713" : "\u2717"} Available`);
     }
     lines.push("");
   }
   lines.push("---");
-  lines.push(`Source: ${MQA_API_BASE}/${data.id || datasetId}`);
+  const portalId = normalized.id || datasetId;
+  lines.push(`Portal: https://data.europa.eu/data/datasets/${portalId}/quality?locale=it`);
+  lines.push(`Source: ${MQA_API_BASE}/${portalId}`);
   return lines.join("\n");
 }
 function registerQualityTools(server2) {
@@ -2749,7 +2865,7 @@ var registerAllPrompts = (server2) => {
 function createServer() {
   return new McpServer({
     name: "ckan-mcp-server",
-    version: "0.4.16"
+    version: "0.4.17"
   });
 }
 function registerAll(server2) {