@opendata.cat/mcp-server 0.0.12 → 0.0.14

package/README.md

@@ -193,6 +193,24 @@ Usuari → LLM → MCP opendata.cat → API opendata.cat (cataleg)
 
 No emmagatzema ni fa de proxy de dades. Cada consulta va directament a la font oficial.
 
+## API REST
+
+A mes del servidor MCP, opendata.cat ofereix una API REST publica per accedir al cataleg de datasets:
+
+| Endpoint | Descripcio |
+|----------|-----------|
+| `GET /api/datasets.php?q=...` | Cerca datasets per text lliure |
+| `GET /api/dataset.php?id=...` | Detall complet d'un dataset |
+| `GET /api/categories.php` | Categories i portals amb comptadors |
+| `GET /api/portals.php` | Portals de transparencia (1.769) |
+| `GET /api/stats.php` | Estadistiques agregades |
+| `GET /api/mcp-stats.php` | Metriques d'us del MCP |
+| `POST /api/mcp` | Servidor MCP (Streamable HTTP) |
+
+Documentacio interactiva (Swagger): **[opendata.cat/api/docs.html](https://opendata.cat/api/docs.html)**
+
+Especificacio OpenAPI: [`opendata.cat/api/openapi.json`](https://opendata.cat/api/openapi.json)
+
 ## Sobre opendata.cat
 
 [opendata.cat](https://opendata.cat) es una associacio catalana sense anim de lucre fundada el 2012 (registre 47468) dedicada a promoure la transparencia i l'acces a la informacio publica. Treballa en tres eixos: **estandarditzacio** de formats i protocols, **formacio** especialitzada per a professionals i administracions, i **collaboracio** publico-privada per a l'obertura de dades.
@@ -206,6 +224,13 @@ Les contribucions son benvingudes! Per afegir un nou portal de dades obertes:
 
 ## Changelog
 
+### v0.0.13 (2026-04-14)
+- Decodificador GTFS-RT integrat: trens FGC en temps real ara retornen dades reals (retards, alertes, posicions GPS)
+- Descodifica automaticament fitxers Protocol Buffers (.pb) de GTFS Realtime
+- API REST documentada amb Swagger UI a /api/docs.html (OpenAPI 3.1)
+- Instruccions per a models locals: LM Studio, Ollama (MCPHost) i Jan
+- Recomanacions de models oberts en catala (Softcatala): Qwen 3.5 9B, Gemma 3 12B
+
 ### v0.0.12 (2026-04-13)
 - 14 prompts predefinits (8 analisi + 6 descobriment)
 - Nous prompts: novetats, datasets_populars, explorar_portal, dades_municipi, datasets_temps_real, resum_portals

package/dist/clients/gtfsrt.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Descarrega i decodifica un fitxer GTFS-RT (.pb) des d'Opendatasoft.
+ * Retorna dades estructurades: trip updates, alertes o posicions de vehicles.
+ */
+export declare function decodeGtfsRt(endpoint: string, limit: number): Promise<{
+    type: string;
+    count: number;
+    data: Record<string, unknown>[];
+}>;

package/dist/clients/gtfsrt.js

@@ -0,0 +1,92 @@
+import GtfsRealtimeBindings from "gtfs-realtime-bindings";
+/**
+ * Descarrega i decodifica un fitxer GTFS-RT (.pb) des d'Opendatasoft.
+ * Retorna dades estructurades: trip updates, alertes o posicions de vehicles.
+ */
+export async function decodeGtfsRt(endpoint, limit) {
+    // 1. Obtenir file ID del record ODS
+    const resp = await fetch(endpoint + (endpoint.includes("?") ? "&" : "?") + "rows=1");
+    if (!resp.ok)
+        throw new Error(`ODS error ${resp.status}`);
+    const odsData = (await resp.json());
+    const file = odsData.records?.[0]?.fields?.file;
+    if (!file?.id)
+        throw new Error("No s'ha trobat el fitxer .pb");
+    // 2. Construir URL de descàrrega
+    const dsMatch = endpoint.match(/dataset=([^&]+)/);
+    const baseMatch = endpoint.match(/(https?:\/\/[^/]+)/);
+    if (!dsMatch || !baseMatch)
+        throw new Error("No s'ha pogut construir la URL de descàrrega");
+    const downloadUrl = `${baseMatch[1]}/explore/dataset/${dsMatch[1]}/files/${file.id}/download/`;
+    // 3. Descarregar i decodificar protobuf
+    const pbResp = await fetch(downloadUrl);
+    if (!pbResp.ok)
+        throw new Error(`Error descarregant .pb: ${pbResp.status}`);
+    const buf = Buffer.from(await pbResp.arrayBuffer());
+    const feed = GtfsRealtimeBindings.transit_realtime.FeedMessage.decode(buf);
+    // 4. Parsejar entitats segons tipus
+    const entities = feed.entity.slice(0, limit);
+    if (entities.some((e) => e.tripUpdate)) {
+        return {
+            type: "trip_updates",
+            count: feed.entity.length,
+            data: entities.filter((e) => e.tripUpdate).map((e) => {
+                const tu = e.tripUpdate;
+                const delays = (tu.stopTimeUpdate || []).map((su) => ({
+                    stop_id: su.stopId,
+                    arrival_delay_seconds: su.arrival?.delay ?? null,
+                    departure_delay_seconds: su.departure?.delay ?? null,
+                }));
+                return {
+                    trip_id: tu.trip?.tripId ?? null,
+                    route_id: tu.trip?.routeId ?? null,
+                    start_date: tu.trip?.startDate ?? null,
+                    start_time: tu.trip?.startTime ?? null,
+                    stops: delays,
+                    max_delay_seconds: Math.max(0, ...delays.map((d) => d.arrival_delay_seconds ?? d.departure_delay_seconds ?? 0)),
+                };
+            }),
+        };
+    }
+    if (entities.some((e) => e.alert)) {
+        return {
+            type: "alerts",
+            count: feed.entity.length,
+            data: entities.filter((e) => e.alert).map((e) => {
+                const a = e.alert;
+                return {
+                    header: a.headerText?.translation?.[0]?.text ?? null,
+                    description: a.descriptionText?.translation?.[0]?.text ?? null,
+                    cause: a.cause ?? null,
+                    effect: a.effect ?? null,
+                    active_periods: (a.activePeriod || []).map((p) => ({
+                        start: p.start ? new Date(Number(p.start) * 1000).toISOString() : null,
+                        end: p.end ? new Date(Number(p.end) * 1000).toISOString() : null,
+                    })),
+                    routes: (a.informedEntity || []).map((ie) => ie.routeId).filter(Boolean),
+                    stops: (a.informedEntity || []).map((ie) => ie.stopId).filter(Boolean),
+                };
+            }),
+        };
+    }
+    if (entities.some((e) => e.vehicle)) {
+        return {
+            type: "vehicle_positions",
+            count: feed.entity.length,
+            data: entities.filter((e) => e.vehicle).map((e) => {
+                const v = e.vehicle;
+                return {
+                    trip_id: v.trip?.tripId ?? null,
+                    route_id: v.trip?.routeId ?? null,
+                    latitude: v.position?.latitude ?? null,
+                    longitude: v.position?.longitude ?? null,
+                    speed_kmh: v.position?.speed != null ? Math.round(v.position.speed * 3.6) : null,
+                    bearing: v.position?.bearing ?? null,
+                    stop_id: v.stopId ?? null,
+                    timestamp: v.timestamp ? new Date(Number(v.timestamp) * 1000).toISOString() : null,
+                };
+            }),
+        };
+    }
+    return { type: "unknown", count: feed.entity.length, data: [] };
+}

package/dist/index.js

@@ -10,9 +10,10 @@ import { queryCkan } from "./clients/ckan.js";
 import { queryDiba } from "./clients/diba.js";
 import { queryCido } from "./clients/cido.js";
 import { queryOpendatasoft } from "./clients/opendatasoft.js";
+import { decodeGtfsRt } from "./clients/gtfsrt.js";
 const server = new McpServer({
     name: "opendata-cat",
-    version: "0.0.12",
+    version: "0.0.13",
 });
 // Tool 1: search_datasets
 server.tool("search_datasets", "Cerca datasets de dades obertes catalanes per text lliure. Retorna nom, descripció, portal i formats.", {
@@ -92,6 +93,25 @@ server.tool("query_dataset", "Executa una consulta contra un dataset i retorna f
         }
         else if (dataset.api_type === "opendatasoft") {
             const data = await queryOpendatasoft(dataset.api_endpoint, filters, search, limit, offset);
+            // Detect and decode GTFS-RT protobuf files
+            const first = data.records[0];
+            const fileField = first?.file;
+            if (fileField?.filename?.endsWith(".pb") || fileField?.filename?.endsWith(".pbf")) {
+                const decoded = await decodeGtfsRt(dataset.api_endpoint, limit);
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                dataset: dataset.name,
+                                format: "GTFS Realtime",
+                                type: decoded.type,
+                                total_entities: decoded.count,
+                                count: decoded.data.length,
+                                data: decoded.data,
+                            }, null, 2),
+                        }],
+                };
+            }
             results = data.records;
         }
         else {
@@ -451,7 +471,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.12" }));
+                res.end(JSON.stringify({ status: "ok", name: "opendata-cat", version: "0.0.13" }));
                 return;
             }
             // MCP endpoint

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.0.12",
+  "version": "0.0.14",
   "description": "Servidor MCP per consultar les dades obertes públiques de Catalunya",
   "type": "module",
   "main": "dist/index.js",
@@ -36,6 +36,7 @@
   "homepage": "https://github.com/xaviviro/Opendata.cat-MCP-Server#readme",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "gtfs-realtime-bindings": "^1.1.1",
     "zod": "^4.3.6"
   },
   "devDependencies": {