@opendata.cat/mcp-server 0.0.1

package/README.md

@@ -0,0 +1,155 @@
+<p align="center">
+  <img src="banner.png" alt="opendata.cat MCP — Connecta el teu LLM amb les dades obertes de Catalunya" width="100%">
+</p>
+
+# Opendata.cat MCP Server
+
+Servidor [MCP](https://modelcontextprotocol.io/) (Model Context Protocol) que connecta els models de llenguatge (Claude, ChatGPT, Gemini...) amb les **dades obertes públiques de Catalunya**. Cerca datasets, explora metadades i consulta dades reals de la Generalitat, l'Ajuntament de Barcelona i la Diputació de Barcelona directament des del teu assistent d'IA.
+
+Un projecte d'**[opendata.cat](https://opendata.cat)** — associació sense ànim de lucre fundada el 2012 que promou la transparència, la difusió i l'estandardització de les dades obertes a Catalunya. Organitza formacions, conferències i desenvolupa plataformes per facilitar l'accés a la informació pública.
+
+## Portals disponibles
+
+| Portal | Datasets | API | Dades |
+|--------|----------|-----|-------|
+| [Generalitat de Catalunya](https://analisi.transparenciacatalunya.cat) | ~1.480 | Socrata | Medi ambient, salut, educació, economia, transport... |
+| [Ajuntament de Barcelona](https://opendata-ajuntament.barcelona.cat) | ~1.036 | CKAN | Urbanisme, mobilitat, cultura, demografia, pressupostos... |
+| [Diputació de Barcelona](https://dadesobertes.diba.cat) | ~124 | CKAN | Municipis, equipaments, patrimoni, energia, territori... |
+
+**+2.600 datasets** actualitzats automàticament cada setmana.
+
+## Instal·lació ràpida
+
+### Claude Desktop
+
+Afegeix al fitxer de configuració (`~/Library/Application Support/Claude/claude_desktop_config.json` a macOS o `%APPDATA%\Claude\claude_desktop_config.json` a Windows):
+
+```json
+{
+  "mcpServers": {
+    "opendata-cat": {
+      "command": "npx",
+      "args": ["-y", "opendata-cat-mcp-server"]
+    }
+  }
+}
+```
+
+### Claude Code (CLI)
+
+```bash
+claude mcp add opendata-cat -- npx -y opendata-cat-mcp-server
+```
+
+### VS Code / Cursor
+
+Afegeix al fitxer `.vscode/mcp.json` del teu projecte:
+
+```json
+{
+  "servers": {
+    "opendata-cat": {
+      "command": "npx",
+      "args": ["-y", "opendata-cat-mcp-server"]
+    }
+  }
+}
+```
+
+## Tools disponibles
+
+| Tool | Descripció |
+|------|-----------|
+| `search_datasets` | Cerca datasets per text lliure al catàleg de +2.600 datasets |
+| `get_dataset_info` | Retorna metadades completes: camps, tipus, llicència, endpoint |
+| `list_dataset_fields` | Llista els camps d'un dataset amb nom, tipus i descripció |
+| `query_dataset` | Consulta dades reals directament al portal origen |
+| `list_portals` | Llista els portals disponibles amb estadístiques |
+| `list_categories` | Llista categories i temes disponibles amb comptadors |
+
+### search_datasets
+
+Cerca datasets per text lliure.
+
+```
+query: "qualitat aire"
+portal: "barcelona"        # opcional: generalitat, barcelona, diba
+category: "Medi Ambient"   # opcional
+limit: 20                  # opcional (defecte: 20)
+```
+
+### get_dataset_info
+
+Retorna totes les metadades d'un dataset.
+
+```
+dataset_id: "generalitat:gn9e-3qhr"
+```
+
+### list_dataset_fields
+
+Llista els camps d'un dataset amb nom, tipus i descripció.
+
+```
+dataset_id: "generalitat:gn9e-3qhr"
+```
+
+### query_dataset
+
+Executa una consulta directament contra el portal origen i retorna dades reals.
+
+```
+dataset_id: "generalitat:gn9e-3qhr"
+filters: {"estaci": "Sau"}   # opcional
+search: "embassament"         # opcional
+limit: 20                     # opcional (defecte: 20, màx: 100)
+offset: 0                     # opcional
+```
+
+### list_portals
+
+Llista els portals disponibles amb el nombre de datasets de cadascun. No requereix paràmetres.
+
+### list_categories
+
+Llista totes les categories i temes de datasets disponibles amb comptadors per portal. Ideal per descobrir quins tipus de dades hi ha.
+
+## Exemples d'ús
+
+Un cop configurat, pots fer preguntes al teu LLM com:
+
+- *"Quins datasets hi ha sobre mobilitat a Barcelona?"*
+- *"Mostra'm les dades de qualitat de l'aire d'ahir"*
+- *"Quants equipaments culturals té Girona?"*
+- *"Dona'm les últimes dades de pressupostos municipals"*
+- *"Quin és l'estat dels embassaments de Catalunya?"*
+- *"Compara les dades de transport públic entre Barcelona i la Diputació"*
+- *"Quines dades obertes hi ha sobre educació a Catalunya?"*
+
+## Com funciona
+
+```
+Usuari → LLM → MCP opendata.cat → API opendata.cat (catàleg)
+                                 → Portal origen (dades reals)
+```
+
+1. L'MCP consulta l'[API d'opendata.cat](https://opendata.cat) per descobrir datasets rellevants
+2. Quan l'usuari vol dades concretes, l'MCP fa la consulta directament al portal origen (Socrata o CKAN)
+3. Les dades tornen a l'LLM, que les interpreta i presenta a l'usuari
+
+No emmagatzema ni fa de proxy de dades. Cada consulta va directament a la font oficial.
+
+## Sobre opendata.cat
+
+[opendata.cat](https://opendata.cat) és una associació catalana sense ànim de lucre fundada el 2012 (registre 47468) dedicada a promoure la transparència i l'accés a la informació pública. Treballa en tres eixos: **estandardització** de formats i protocols, **formació** especialitzada per a professionals i administracions, i **col·laboració** público-privada per a l'obertura de dades.
+
+## Contribuir
+
+Les contribucions són benvingudes! Per afegir un nou portal de dades obertes:
+
+1. Obre una [issue](https://github.com/xaviviro/Opendata.cat-MCP-Server/issues) amb la URL del portal i el tipus d'API
+2. O envia un pull request
+
+## Llicència
+
+MIT

package/dist/api.d.ts

@@ -0,0 +1,49 @@
+export interface DatasetSummary {
+    dataset_id: string;
+    portal_id: string;
+    name: string;
+    description: string;
+    category: string;
+    formats: string[];
+    api_type: string;
+}
+export interface DatasetDetail {
+    dataset_id: string;
+    portal_id: string;
+    name: string;
+    description: string;
+    category: string;
+    tags: string[];
+    api_type: "socrata" | "ckan";
+    api_endpoint: string;
+    formats: string[];
+    fields: {
+        name: string;
+        type: string;
+        description: string;
+    }[];
+    row_count: number | null;
+    last_updated: string;
+    license: string;
+}
+export interface SearchResult {
+    items: DatasetSummary[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+export declare function searchDatasets(query: string, portal?: string, category?: string, limit?: number, offset?: number): Promise<SearchResult>;
+export interface CategoriesResult {
+    total_datasets: number;
+    portals: {
+        portal_id: string;
+        total: number;
+    }[];
+    categories: {
+        portal_id: string;
+        category: string;
+        total: number;
+    }[];
+}
+export declare function getCategories(): Promise<CategoriesResult>;
+export declare function getDatasetInfo(datasetId: string): Promise<DatasetDetail | null>;

package/dist/api.js

@@ -0,0 +1,30 @@
+const API_BASE = "https://opendata.cat/api";
+export async function searchDatasets(query, portal, category, limit = 20, offset = 0) {
+    const params = new URLSearchParams();
+    if (query)
+        params.set("q", query);
+    if (portal)
+        params.set("portal", portal);
+    if (category)
+        params.set("category", category);
+    params.set("limit", String(limit));
+    params.set("offset", String(offset));
+    const resp = await fetch(`${API_BASE}/datasets.php?${params}`);
+    if (!resp.ok)
+        throw new Error(`API error ${resp.status}`);
+    return (await resp.json());
+}
+export async function getCategories() {
+    const resp = await fetch(`${API_BASE}/categories.php`);
+    if (!resp.ok)
+        throw new Error(`API error ${resp.status}`);
+    return (await resp.json());
+}
+export async function getDatasetInfo(datasetId) {
+    const resp = await fetch(`${API_BASE}/dataset.php?id=${encodeURIComponent(datasetId)}`);
+    if (resp.status === 404)
+        return null;
+    if (!resp.ok)
+        throw new Error(`API error ${resp.status}`);
+    return (await resp.json());
+}

package/dist/clients/ckan.d.ts

@@ -0,0 +1,4 @@
+export declare function queryCkan(endpoint: string, filters?: Record<string, string>, search?: string, limit?: number, offset?: number): Promise<{
+    records: Record<string, unknown>[];
+    total: number;
+}>;

package/dist/clients/ckan.js

@@ -0,0 +1,20 @@
+export async function queryCkan(endpoint, filters, search, limit = 20, offset = 0) {
+    const url = new URL(endpoint);
+    if (filters && Object.keys(filters).length > 0) {
+        url.searchParams.set("filters", JSON.stringify(filters));
+    }
+    if (search)
+        url.searchParams.set("q", search);
+    url.searchParams.set("limit", String(Math.min(limit, 100)));
+    url.searchParams.set("offset", String(offset));
+    const resp = await fetch(url.toString());
+    if (!resp.ok)
+        throw new Error(`CKAN error ${resp.status}: ${resp.statusText}`);
+    const data = await resp.json();
+    if (!data.success)
+        throw new Error(`CKAN error: ${JSON.stringify(data.error)}`);
+    return {
+        records: data.result.records ?? [],
+        total: data.result.total ?? 0,
+    };
+}

package/dist/clients/socrata.d.ts

@@ -0,0 +1 @@
+export declare function querySocrata(endpoint: string, filters?: Record<string, string>, search?: string, limit?: number, offset?: number): Promise<Record<string, unknown>[]>;

package/dist/clients/socrata.js

@@ -0,0 +1,15 @@
+export async function querySocrata(endpoint, filters, search, limit = 20, offset = 0) {
+    const url = new URL(endpoint);
+    if (filters && Object.keys(filters).length > 0) {
+        const clauses = Object.entries(filters).map(([key, value]) => `${key}='${value.replace(/'/g, "''")}'`);
+        url.searchParams.set("$where", clauses.join(" AND "));
+    }
+    if (search)
+        url.searchParams.set("$q", search);
+    url.searchParams.set("$limit", String(Math.min(limit, 100)));
+    url.searchParams.set("$offset", String(offset));
+    const resp = await fetch(url.toString());
+    if (!resp.ok)
+        throw new Error(`Socrata error ${resp.status}: ${resp.statusText}`);
+    return (await resp.json());
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { searchDatasets, getDatasetInfo, getCategories } from "./api.js";
+import { querySocrata } from "./clients/socrata.js";
+import { queryCkan } from "./clients/ckan.js";
+const server = new McpServer({
+    name: "opendata-cat",
+    version: "0.0.1",
+});
+// Tool 1: search_datasets
+server.tool("search_datasets", "Cerca datasets de dades obertes catalanes per text lliure. Retorna nom, descripció, portal i formats.", {
+    query: z.string().describe("Text de cerca (ex: 'qualitat aire', 'pressupostos')"),
+    portal: z.string().optional().describe("Filtrar per portal: 'generalitat', 'barcelona' o 'diba'"),
+    category: z.string().optional().describe("Filtrar per categoria"),
+    limit: z.number().optional().default(20).describe("Nombre màxim de resultats (defecte: 20)"),
+}, async ({ query, portal, category, limit }) => {
+    const result = await searchDatasets(query, portal, category, limit);
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify(result, null, 2),
+            }],
+    };
+});
+// Tool 2: get_dataset_info
+server.tool("get_dataset_info", "Retorna totes les metadades d'un dataset: camps, tipus, descripció, endpoint API, llicència.", {
+    dataset_id: z.string().describe("ID del dataset (ex: 'generalitat:gn9e-3qhr')"),
+}, async ({ dataset_id }) => {
+    const dataset = await getDatasetInfo(dataset_id);
+    if (!dataset) {
+        return { content: [{ type: "text", text: `Dataset '${dataset_id}' no trobat.` }] };
+    }
+    return { content: [{ type: "text", text: JSON.stringify(dataset, null, 2) }] };
+});
+// Tool 3: list_dataset_fields
+server.tool("list_dataset_fields", "Llista els camps d'un dataset amb el seu nom, tipus i descripció.", {
+    dataset_id: z.string().describe("ID del dataset"),
+}, async ({ dataset_id }) => {
+    const dataset = await getDatasetInfo(dataset_id);
+    if (!dataset) {
+        return { content: [{ type: "text", text: `Dataset '${dataset_id}' no trobat.` }] };
+    }
+    return { content: [{ type: "text", text: JSON.stringify(dataset.fields, null, 2) }] };
+});
+// Tool 4: query_dataset
+server.tool("query_dataset", "Executa una consulta contra un dataset i retorna files de dades reals del portal origen.", {
+    dataset_id: z.string().describe("ID del dataset a consultar"),
+    filters: z.record(z.string(), z.string()).optional().describe("Filtres clau-valor (ex: {\"ciutat\": \"Barcelona\"})"),
+    search: z.string().optional().describe("Cerca de text lliure dins el dataset"),
+    limit: z.number().optional().default(20).describe("Files a retornar (defecte: 20, màxim: 100)"),
+    offset: z.number().optional().default(0).describe("Desplaçament per paginació"),
+}, async ({ dataset_id, filters, search, limit, offset }) => {
+    const dataset = await getDatasetInfo(dataset_id);
+    if (!dataset) {
+        return { content: [{ type: "text", text: `Dataset '${dataset_id}' no trobat.` }] };
+    }
+    try {
+        let results;
+        if (dataset.api_type === "socrata") {
+            results = await querySocrata(dataset.api_endpoint, filters, search, limit, offset);
+        }
+        else {
+            const data = await queryCkan(dataset.api_endpoint, filters, search, limit, offset);
+            results = data.records;
+        }
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({ dataset: dataset.name, count: results.length, data: results }, null, 2),
+                }],
+        };
+    }
+    catch (err) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Error consultant ${dataset.name}: ${err instanceof Error ? err.message : String(err)}`,
+                }],
+        };
+    }
+});
+// Tool 5: list_portals
+server.tool("list_portals", "Llista els portals de dades obertes catalans disponibles amb estadístiques.", {}, async () => {
+    const portals = [
+        { id: "generalitat", name: "Generalitat de Catalunya", url: "https://analisi.transparenciacatalunya.cat", api_type: "socrata" },
+        { id: "barcelona", name: "Ajuntament de Barcelona", url: "https://opendata-ajuntament.barcelona.cat", api_type: "ckan" },
+        { id: "diba", name: "Diputació de Barcelona", url: "https://dadesobertes.diba.cat", api_type: "ckan" },
+    ];
+    const counts = await Promise.all(portals.map(async (p) => {
+        const result = await searchDatasets("", p.id, undefined, 1);
+        return { ...p, dataset_count: result.total };
+    }));
+    return { content: [{ type: "text", text: JSON.stringify(counts, null, 2) }] };
+});
+// Tool 6: list_categories
+server.tool("list_categories", "Llista totes les categories i temes de datasets disponibles amb comptadors per portal. Útil per saber quins tipus de dades hi ha.", {}, async () => {
+    const cats = await getCategories();
+    return { content: [{ type: "text", text: JSON.stringify(cats, null, 2) }] };
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch(console.error);

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@opendata.cat/mcp-server",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "0.0.1",
+  "description": "Servidor MCP per consultar les dades obertes públiques de Catalunya",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "opendata-cat-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "files": [
+    "dist/"
+  ],
+  "keywords": [
+    "mcp",
+    "opendata",
+    "catalunya",
+    "dades-obertes"
+  ],
+  "author": "opendata.cat",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xaviviro/Opendata.cat-MCP-Server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/xaviviro/Opendata.cat-MCP-Server/issues"
+  },
+  "homepage": "https://github.com/xaviviro/Opendata.cat-MCP-Server#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "typescript": "^6.0.2"
+  }
+}