@opendata.cat/mcp-server 0.0.9 → 0.0.11

package/README.md

@@ -12,7 +12,7 @@
 
 # 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 publiques de Catalunya**. Cerca datasets, explora metadades i consulta dades reals de la Generalitat, l'Ajuntament de Barcelona i la Diputacio de Barcelona directament des del teu assistent d'IA.
+Servidor [MCP](https://modelcontextprotocol.io/) (Model Context Protocol) que connecta els models de llenguatge (Claude, ChatGPT, Gemini...) amb les **dades obertes publiques de Catalunya**. Cerca datasets, explora metadades i consulta dades reals de 7 portals catalans directament des del teu assistent d'IA.
 
 Un projecte d'**[opendata.cat](https://opendata.cat)** — associacio sense anim de lucre fundada el 2012 que promou la transparencia, la difusio i l'estandarditzacio de les dades obertes a Catalunya. Inspirat en el projecte [datagouv-mcp](https://github.com/datagouv/datagouv-mcp) del govern frances.
 
@@ -26,18 +26,20 @@ Un projecte d'**[opendata.cat](https://opendata.cat)** — associacio sense anim
 | [Consorci AOC](https://dadesobertes.seu-e.cat) | ~893 | CKAN datastore |
 | [Ajuntament de Reus](https://opendata.reus.cat) | 119 | CKAN datastore |
 | [Ajuntament de Girona](https://www.girona.cat/opendata/) | 53 | CKAN datastore |
+| [FGC (Ferrocarrils)](https://dadesobertes.fgc.cat) | 50 | Opendatasoft |
 
 El Consorci AOC inclou datasets de les **diputacions de Tarragona, Girona i Lleida**, ajuntaments, consells comarcals i altres organismes publics catalans.
 
-**+2.700 datasets** de 6 portals. La majoria queryables amb filtres, cerca i paginacio.
+**+2.800 datasets** de 7 portals. La majoria queryables amb filtres, cerca i paginacio.
 
 El cataleg s'actualitza automaticament cada setmana. Cada endpoint es valida per assegurar que funciona.
 
 **Tipus d'acces:**
 - **Socrata**: consulta SoQL amb filtres i cerca (Generalitat)
-- **CKAN**: datastore_search amb filtres i cerca (Barcelona, AOC)
+- **CKAN**: datastore_search amb filtres i cerca (Barcelona, AOC, Reus, Girona)
 - **Diba REST**: API do.diba.cat amb paginacio i filtres (Diputacio BCN)
 - **CIDO JSON:API**: api.diba.cat per contractacions, normatives, subvencions, oposicions, convenis (Diputacio BCN)
+- **Opendatasoft**: API records amb filtres i cerca (FGC — horaris GTFS, trens temps real, estacions esqui)
 - **File download**: descarrega directa de CSV, JSON, XLSX o fitxers GIS
 - **Restricted**: requereix token d'autenticacio (4 datasets BSM)
 
@@ -89,6 +91,7 @@ Afegeix al fitxer `.vscode/mcp.json` del teu projecte:
 | `query_dataset` | Consulta dades reals directament al portal origen |
 | `list_portals` | Llista els portals disponibles amb estadistiques |
 | `list_categories` | Llista categories i temes disponibles amb comptadors |
+| `related_datasets` | Retorna datasets relacionats d'altres portals |
 
 ### search_datasets
 
@@ -96,7 +99,7 @@ Cerca datasets per text lliure.
 
 ```
 query: "qualitat aire"
-portal: "barcelona"        # opcional: generalitat, barcelona, diba
+portal: "barcelona"        # opcional: generalitat, barcelona, diba, aoc, reus, girona, fgc
 category: "Medi Ambient"   # opcional
 limit: 20                  # opcional (defecte: 20)
 ```
@@ -137,17 +140,33 @@ Llista els portals disponibles amb el nombre de datasets de cadascun. No requere
 
 Llista totes les categories i temes de datasets disponibles amb comptadors per portal. Ideal per descobrir quins tipus de dades hi ha.
 
+## Prompts disponibles
+
+Prompts predefinits que guien l'LLM pas a pas per fer analisis completes:
+
+| Prompt | Descripcio | Arguments |
+|--------|-----------|-----------|
+| `estat_embassaments` | Estat actual dels embassaments amb grafiques d'evolucio | — |
+| `trens_fgc_temps_real` | Retards, alertes i posicions dels trens FGC en temps real | — |
+| `qualitat_aire` | Analisi de la qualitat de l'aire amb comparativa OMS/UE | `lloc` (opcional) |
+| `accidents_transit` | Analisi d'accidents de transit amb punts negres i tendencies | `municipi` (opcional) |
+| `pressupostos_municipals` | Pressupostos municipals amb desglossament per partides | `municipi` (opcional) |
+| `compara_municipis` | Compara dos municipis en totes les dades disponibles | `municipi_a`, `municipi_b` |
+| `descobreix_dades` | Mapa complet de dades obertes sobre un tema | `tema` |
+| `analisi_bombers` | Actuacions dels Bombers: emergencies, distribucio, tendencies | `comarca` (opcional) |
+
 ## Exemples d'us
 
 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 te Girona?"*
-- *"Dona'm les ultimes dades de pressupostos municipals"*
-- *"Quin es l'estat dels embassaments de Catalunya?"*
-- *"Quines dades obertes hi ha sobre educacio a Catalunya?"*
-- *"Quins tipus de dades teniu disponibles?"*
+- *"Quin es l'estat dels embassaments de Catalunya?"* → prompt `estat_embassaments`
+- *"Hi ha algun tren de FGC amb retard ara mateix?"* → prompt `trens_fgc_temps_real`
+- *"Analitza la qualitat de l'aire a Terrassa"* → prompt `qualitat_aire`
+- *"Fes unes grafiques amb l'evolucio dels accidents de transit a Barcelona"* → prompt `accidents_transit`
+- *"Compara Girona i Tarragona en dades obertes"* → prompt `compara_municipis`
+- *"Quines dades obertes hi ha sobre educacio a Catalunya?"* → prompt `descobreix_dades`
+- *"Dona'm les ultimes dades de pressupostos de Reus"* → prompt `pressupostos_municipals`
+- *"Analitza les actuacions dels Bombers al Valles"* → prompt `analisi_bombers`
 
 ## Com funciona
 
@@ -175,6 +194,18 @@ Les contribucions son benvingudes! Per afegir un nou portal de dades obertes:
 
 ## Changelog
 
+### v0.0.11 (2026-04-13)
+- 8 prompts predefinits: embassaments, trens FGC temps real, qualitat aire, accidents, pressupostos, compara municipis, descobreix dades, bombers
+- Crawler incremental: UPSERT en lloc de TRUNCATE, no perd dades si un portal falla
+- Backup automatic despres de cada carrega
+
+### v0.0.10 (2026-04-13)
+- Afegeix portal FGC (Ferrocarrils de la Generalitat de Catalunya) — 50 datasets via Opendatasoft
+- Nou client Opendatasoft per consultar dades de transport, esqui, meteorologia, GTFS
+- list_portals ara llista els 7 portals (abans nomes 3)
+- Fix seguretat: validacio de claus de filtre SoQL contra injeccio
+- Cobertura total: ~2.800 datasets de 7 portals
+
 ### v0.0.7 (2026-04-13)
 - Afegeix portal Consorci AOC (~893 datasets de diputacions, ajuntaments, consells comarcals)
 - Cobertura total: ~2.600 datasets, ~2.400 queryables

package/dist/clients/opendatasoft.d.ts

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

package/dist/clients/opendatasoft.js

@@ -0,0 +1,20 @@
+export async function queryOpendatasoft(endpoint, filters, search, limit = 20, offset = 0) {
+    const url = new URL(endpoint);
+    if (filters && Object.keys(filters).length > 0) {
+        for (const [key, value] of Object.entries(filters)) {
+            url.searchParams.set(`refine.${key}`, value);
+        }
+    }
+    if (search)
+        url.searchParams.set("q", search);
+    url.searchParams.set("rows", String(Math.min(limit, 100)));
+    url.searchParams.set("start", String(offset));
+    const resp = await fetch(url.toString());
+    if (!resp.ok)
+        throw new Error(`Opendatasoft error ${resp.status}: ${resp.statusText}`);
+    const data = (await resp.json());
+    return {
+        records: data.records.map((r) => r.fields),
+        total: data.nhits,
+    };
+}

package/dist/clients/socrata.js

@@ -1,8 +1,12 @@
 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 "));
+        const clauses = Object.entries(filters)
+            .filter(([key]) => /^[a-zA-Z_][a-zA-Z0-9_-]*$/.test(key))
+            .map(([key, value]) => `\`${key}\`='${value.replace(/'/g, "''")}'`);
+        if (clauses.length > 0) {
+            url.searchParams.set("$where", clauses.join(" AND "));
+        }
     }
     if (search)
         url.searchParams.set("$q", search);

package/dist/index.js

@@ -9,14 +9,15 @@ import { querySocrata } from "./clients/socrata.js";
 import { queryCkan } from "./clients/ckan.js";
 import { queryDiba } from "./clients/diba.js";
 import { queryCido } from "./clients/cido.js";
+import { queryOpendatasoft } from "./clients/opendatasoft.js";
 const server = new McpServer({
     name: "opendata-cat",
-    version: "0.0.9",
+    version: "0.0.11",
 });
 // 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'"),
+    portal: z.string().optional().describe("Filtrar per portal: 'generalitat', 'barcelona', 'diba', 'aoc', 'reus', 'girona', 'fgc'"),
     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 }) => {
@@ -89,6 +90,10 @@ server.tool("query_dataset", "Executa una consulta contra un dataset i retorna f
             const data = await queryCkan(dataset.api_endpoint, filters, search, limit, offset);
             results = data.records;
         }
+        else if (dataset.api_type === "opendatasoft") {
+            const data = await queryOpendatasoft(dataset.api_endpoint, filters, search, limit, offset);
+            results = data.records;
+        }
         else {
             return {
                 content: [{
@@ -116,15 +121,21 @@ server.tool("query_dataset", "Executa una consulta contra un dataset i retorna f
 // 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" },
+        { id: "generalitat", name: "Generalitat de Catalunya", url: "https://analisi.transparenciacatalunya.cat", api: "Socrata" },
+        { id: "barcelona", name: "Ajuntament de Barcelona", url: "https://opendata-ajuntament.barcelona.cat", api: "CKAN" },
+        { id: "diba", name: "Diputació de Barcelona", url: "https://dadesobertes.diba.cat", api: "CKAN" },
+        { id: "aoc", name: "Consorci AOC (diputacions, ajuntaments, consells comarcals)", url: "https://dadesobertes.seu-e.cat", api: "CKAN" },
+        { id: "reus", name: "Ajuntament de Reus", url: "https://opendata.reus.cat", api: "CKAN" },
+        { id: "girona", name: "Ajuntament de Girona", url: "https://www.girona.cat/opendata/", api: "CKAN" },
+        { id: "fgc", name: "Ferrocarrils de la Generalitat de Catalunya", url: "https://dadesobertes.fgc.cat", api: "Opendatasoft" },
     ];
-    const counts = await Promise.all(portals.map(async (p) => {
-        const result = await searchDatasets("", p.id, undefined, 1);
-        return { ...p, dataset_count: result.total };
+    const cats = await getCategories();
+    const portalCounts = new Map(cats.portals.map((p) => [p.portal_id, p.total]));
+    const result = portals.map((p) => ({
+        ...p,
+        dataset_count: portalCounts.get(p.id) ?? 0,
     }));
-    return { content: [{ type: "text", text: JSON.stringify(counts, null, 2) }] };
+    return { content: [{ type: "text", text: JSON.stringify(result, 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 () => {
@@ -161,6 +172,149 @@ server.tool("related_datasets", "Retorna datasets relacionats d'ALTRES portals.
             }],
     };
 });
+// ===== PROMPTS =====
+server.prompt("estat_embassaments", "Analitza l'estat actual dels embassaments de Catalunya amb gràfiques d'evolució.", () => ({
+    messages: [{
+            role: "user",
+            content: {
+                type: "text",
+                text: "Consulta l'estat actual dels embassaments de les Conques Internes de Catalunya.\n\n"
+                    + "1. Usa search_datasets amb 'embassament' per trobar el dataset rellevant\n"
+                    + "2. Usa query_dataset per obtenir les últimes dades\n"
+                    + "3. Presenta una taula amb cada embassament: nom, volum actual (hm³), percentatge ple, i variació\n"
+                    + "4. Genera un gràfic ASCII o Markdown amb l'evolució dels nivells\n"
+                    + "5. Destaca embassaments en situació crítica (< 40%) i els que estan millor\n"
+                    + "6. Compara amb el dataset d'estat de sequera si n'hi ha\n\n"
+                    + "Mostra les dades de forma visual i fàcil d'entendre.",
+            },
+        }],
+}));
+server.prompt("trens_fgc_temps_real", "Consulta l'estat dels trens de FGC en temps real: retards, alertes i posicions.", () => ({
+    messages: [{
+            role: "user",
+            content: {
+                type: "text",
+                text: "Consulta l'estat en temps real dels trens de Ferrocarrils de la Generalitat de Catalunya (FGC).\n\n"
+                    + "1. Usa search_datasets amb portal 'fgc' per trobar els datasets GTFS Realtime\n"
+                    + "2. Consulta 'trip-updates' per veure retards actuals\n"
+                    + "3. Consulta 'vehicle-positions' per veure on són els trens\n"
+                    + "4. Consulta 'alerts' per veure si hi ha alertes de servei\n\n"
+                    + "Presenta un resum clar:\n"
+                    + "- Trens amb retard (quants minuts, quina línia)\n"
+                    + "- Alertes actives de servei\n"
+                    + "- Estat general: normal / amb incidències / interromput",
+            },
+        }],
+}));
+server.prompt("qualitat_aire", "Analitza la qualitat de l'aire a una estació o municipi de Catalunya.", { lloc: z.string().optional().describe("Nom del municipi o estació (ex: 'Barcelona', 'Sabadell')") }, ({ lloc }) => {
+    const filtreText = lloc ? ` a ${lloc}` : " a les principals estacions";
+    return {
+        messages: [{
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Analitza la qualitat de l'aire${filtreText}.\n\n`
+                        + "1. Usa search_datasets amb 'qualitat aire contaminació' per trobar els datasets rellevants\n"
+                        + "2. Consulta les últimes mesures disponibles"
+                        + (lloc ? ` filtrant per '${lloc}'` : "") + "\n"
+                        + "3. Presenta els nivells de: NO₂, PM10, PM2.5, O₃, SO₂ (els que hi hagi)\n"
+                        + "4. Compara amb els llindars de l'OMS i la normativa UE\n"
+                        + "5. Dona una valoració global: bona / acceptable / dolenta / molt dolenta\n"
+                        + "6. Si hi ha dades històriques, mostra la tendència recent\n\n"
+                        + "Usa taules i indicadors visuals per fer-ho entenedor.",
+                },
+            }],
+    };
+});
+server.prompt("accidents_transit", "Analitza les dades d'accidents de trànsit a Catalunya o a un municipi concret.", { municipi: z.string().optional().describe("Nom del municipi (ex: 'Barcelona', 'Hospitalet')") }, ({ municipi }) => {
+    const filtreText = municipi ? ` a ${municipi}` : " a Catalunya";
+    return {
+        messages: [{
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Analitza les dades d'accidents de trànsit${filtreText}.\n\n`
+                        + "1. Usa search_datasets amb 'accidents trànsit" + (municipi ? ` ${municipi}` : "") + "'\n"
+                        + "2. Consulta les dades més recents\n"
+                        + "3. Presenta: nombre total d'accidents, distribució per gravetat (mortals, ferits greus, lleus)\n"
+                        + "4. Si hi ha dades geolocalitzades, identifica els punts negres\n"
+                        + "5. Analitza tendències: augmenten o disminueixen?\n"
+                        + "6. Busca datasets relacionats amb related_datasets per completar l'anàlisi\n\n"
+                        + "Presenta conclusions clares amb dades concretes.",
+                },
+            }],
+    };
+});
+server.prompt("pressupostos_municipals", "Explora i compara els pressupostos municipals d'ajuntaments catalans.", { municipi: z.string().optional().describe("Nom del municipi") }, ({ municipi }) => {
+    const filtreText = municipi ? ` de ${municipi}` : "";
+    return {
+        messages: [{
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Explora els pressupostos municipals${filtreText}.\n\n`
+                        + "1. Usa search_datasets amb 'pressupost" + (municipi ? ` ${municipi}` : " municipal") + "'\n"
+                        + "2. Consulta les últimes dades de pressupost disponibles\n"
+                        + "3. Desglossa: ingressos vs despeses, partides principals\n"
+                        + "4. Si hi ha dades multi-any, mostra l'evolució\n"
+                        + "5. Destaca les partides més grans i les variacions significatives\n\n"
+                        + "Presenta les xifres en format comprensible (milions €) amb taules.",
+                },
+            }],
+    };
+});
+server.prompt("compara_municipis", "Compara dos municipis catalans en totes les dades obertes disponibles.", {
+    municipi_a: z.string().describe("Primer municipi"),
+    municipi_b: z.string().describe("Segon municipi"),
+}, ({ municipi_a, municipi_b }) => ({
+    messages: [{
+            role: "user",
+            content: {
+                type: "text",
+                text: `Compara els municipis de ${municipi_a} i ${municipi_b} amb totes les dades obertes disponibles.\n\n`
+                    + `1. Usa search_datasets per trobar datasets que incloguin '${municipi_a}'\n`
+                    + `2. Usa search_datasets per trobar datasets que incloguin '${municipi_b}'\n`
+                    + "3. Per cada tema comú (població, pressupost, equipaments, transport...), consulta les dades dels dos municipis\n"
+                    + "4. Presenta una taula comparativa amb les dades clau\n"
+                    + "5. Destaca les diferències més significatives\n\n"
+                    + "Organitza la comparativa per temes i indica la font de cada dada.",
+            },
+        }],
+}));
+server.prompt("descobreix_dades", "Explora quines dades obertes hi ha disponibles sobre un tema a Catalunya.", { tema: z.string().describe("Tema a explorar (ex: 'educació', 'medi ambient', 'turisme')") }, ({ tema }) => ({
+    messages: [{
+            role: "user",
+            content: {
+                type: "text",
+                text: `Explora totes les dades obertes disponibles sobre '${tema}' a Catalunya.\n\n`
+                    + `1. Usa search_datasets amb '${tema}' (limit: 50)\n`
+                    + "2. Agrupa els resultats per portal i categoria\n"
+                    + "3. Per als 3-5 datasets més rellevants, usa get_dataset_info per mostrar detalls (camps, tipus, actualització)\n"
+                    + "4. Usa related_datasets per descobrir dades complementàries\n"
+                    + "5. Suggereix 3 anàlisis interessants que es podrien fer creuant aquests datasets\n\n"
+                    + "L'objectiu és donar un mapa complet de quines dades existeixen i què es pot fer amb elles.",
+            },
+        }],
+}));
+server.prompt("analisi_bombers", "Analitza les actuacions dels Bombers de la Generalitat: tipus d'emergències, distribució territorial i tendències.", { comarca: z.string().optional().describe("Filtrar per comarca (ex: 'Barcelonès', 'Vallès Occidental')") }, ({ comarca }) => {
+    const filtreText = comarca ? ` a la comarca de ${comarca}` : "";
+    return {
+        messages: [{
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Analitza les actuacions dels Bombers de la Generalitat${filtreText}.\n\n`
+                        + "1. Usa search_datasets amb 'bombers actuacions emergències'\n"
+                        + "2. Consulta els datasets d'actuacions, GRAF i EAIC\n"
+                        + "3. Presenta: nombre total d'actuacions, distribució per tipus (incendis, rescats, inundacions...)\n"
+                        + "4. Si hi ha dades temporals, mostra estacionalitat (estiu = incendis?)\n"
+                        + "5. Identifica les zones amb més actuacions\n"
+                        + (comarca ? `6. Filtra específicament per la comarca de ${comarca}\n` : "")
+                        + "\nFes una anàlisi visual amb taules i percentatges.",
+                },
+            }],
+    };
+});
 async function main() {
     const mode = process.argv.includes("--http") ? "http" : "stdio";
     const port = parseInt(process.env.MCP_PORT || "3100", 10);
@@ -179,7 +333,7 @@ async function main() {
             // Health check
             if (req.url === "/health") {
                 res.writeHead(200, { "Content-Type": "application/json" });
-                res.end(JSON.stringify({ status: "ok", name: "opendata-cat", version: "0.0.9" }));
+                res.end(JSON.stringify({ status: "ok", name: "opendata-cat", version: "0.0.11" }));
                 return;
             }
             // MCP endpoint

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.0.9",
+  "version": "0.0.11",
   "description": "Servidor MCP per consultar les dades obertes públiques de Catalunya",
   "type": "module",
   "main": "dist/index.js",