mcp-chilegob-dataset 0.2.0 → 0.3.0

package/README.md

@@ -1,5 +1,10 @@
 # mcp-chilegob-dataset
 
+[![npm version](https://img.shields.io/npm/v/mcp-chilegob-dataset.svg)](https://www.npmjs.com/package/mcp-chilegob-dataset)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+> **English summary:** MCP server that exposes Chile's open government data portal ([datos.gob.cl](https://datos.gob.cl)) as tools for AI assistants. Search and read thousands of public datasets from Chilean government institutions — health, education, transport, environment, and more. No API key required.
+
 Servidor MCP que expone el portal de datos abiertos del gobierno de Chile — [datos.gob.cl](https://datos.gob.cl) — como herramientas para asistentes de inteligencia artificial.
 
 Construido con [Hono](https://hono.dev) y el [SDK de TypeScript del Model Context Protocol](https://github.com/modelcontextprotocol/typescript-sdk).
@@ -180,7 +185,7 @@ Lee filas tabulares de un recurso CKAN. Intenta primero el datastore y, si no es
   "parseable": false,
   "format": "XLS",
   "url": "https://datosabiertos.mineduc.cl/archivo.xls",
-  "message": "This resource is a XLS file and cannot be parsed automatically. Download it directly from the URL above."
+  "message": "This resource is a XLS file and cannot be parsed automatically. Download it directly from the URL provided."
 }
 ```
 
@@ -279,7 +284,8 @@ export function registerTuHerramienta(server: McpServer): void {
 - **Disponibilidad del datastore** — No todos los recursos tienen datastore habilitado en CKAN. `get_resource_data` intenta automáticamente descargar el archivo (CSV, TSV, JSON); los formatos binarios (XLS, PDF) requieren descarga manual desde la URL devuelta.
 - **Archivos grandes** — La descarga directa carga el archivo completo en memoria antes de paginar. Para archivos muy grandes (>100 MB) esto puede ser lento o fallar.
 - **Encoding** — Los archivos CSV de datos.gob.cl pueden estar en ISO-8859-1 (Latin-1). La herramienta intenta leerlos como UTF-8; si los caracteres aparecen corruptos, descarga el archivo directamente.
-- **Sin caché** — Cada llamada hace una solicitud en vivo a datos.gob.cl. No hay límites de tasa documentados.
+- **Caché en memoria (5 min)** — `search_datasets` y `get_dataset` usan caché en memoria con TTL de 5 minutos. `get_resource_data` siempre consulta en vivo. No hay límites de tasa documentados en datos.gob.cl.
+- **Timeout de red (10s)** — Todas las solicitudes a datos.gob.cl tienen un timeout de 10 segundos. Si el portal está lento o caído, las herramientas devuelven un error claro en lugar de colgar indefinidamente.
 - **Paquetes en alpha** — `@modelcontextprotocol/hono` y `@modelcontextprotocol/server` están en versión alpha.
 
 ---
@@ -290,7 +296,6 @@ Las contribuciones son bienvenidas. Algunas ideas:
 
 - [ ] Herramienta `list_organizations` — listar instituciones disponibles
 - [ ] Herramienta `get_resource_schema` — tipos y descripciones de columnas
-- [ ] Caché en memoria para reducir llamadas a la API
 - [ ] MCP Resources con URI templates (`datos-gob-cl://dataset/{id}`)
 
 Por favor, abre un issue antes de enviar un PR grande.

package/dist/ckan.js

@@ -1,25 +1,99 @@
 const CKAN_BASE = 'https://datos.gob.cl/api/3/action';
+const FETCH_TIMEOUT_MS = 10_000;
+const CACHE_TTL_MS = 5 * 60 * 1000;
+class TTLCache {
+    store = new Map();
+    get(key) {
+        const entry = this.store.get(key);
+        if (entry === undefined)
+            return undefined;
+        if (Date.now() > entry.expiresAt) {
+            this.store.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    set(key, value, ttlMs) {
+        this.store.set(key, { value, expiresAt: Date.now() + ttlMs });
+    }
+}
+export class NotParseableError extends Error {
+    format;
+    url;
+    constructor(format, url) {
+        super(`Format not parseable: ${format} (${url})`);
+        this.format = format;
+        this.url = url;
+        this.name = 'NotParseableError';
+    }
+}
+export class CkanHttpError extends Error {
+    statusCode;
+    statusText;
+    constructor(statusCode, statusText) {
+        super(`CKAN HTTP error: ${statusCode} ${statusText}`);
+        this.statusCode = statusCode;
+        this.statusText = statusText;
+        this.name = 'CkanHttpError';
+    }
+}
+export class CkanApiError extends Error {
+    errorType;
+    constructor(message, errorType) {
+        super(`CKAN API error: ${message}`);
+        this.errorType = errorType;
+        this.name = 'CkanApiError';
+    }
+}
 async function ckanAction(action, params) {
     const url = new URL(`${CKAN_BASE}/${action}`);
     for (const [key, value] of Object.entries(params)) {
         url.searchParams.set(key, String(value));
     }
-    const response = await fetch(url.toString());
-    if (!response.ok) {
-        throw new Error(`CKAN API error: ${response.status} ${response.statusText}`);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+        const response = await fetch(url.toString(), { signal: controller.signal });
+        if (!response.ok) {
+            throw new CkanHttpError(response.status, response.statusText);
+        }
+        const data = await response.json();
+        if (!data.success) {
+            const errorType = data.error?.__type ?? 'Unknown Error';
+            const message = data.error?.message ?? 'Unknown error';
+            throw new CkanApiError(message, errorType);
+        }
+        return data.result;
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === 'AbortError') {
+            throw new Error(`Request timed out after ${FETCH_TIMEOUT_MS / 1000}s`);
+        }
+        throw err;
     }
-    const data = await response.json();
-    if (!data.success) {
-        throw new Error(`CKAN error: ${data.error?.message ?? 'Unknown error'}`);
+    finally {
+        clearTimeout(timer);
     }
-    return data.result;
 }
+const searchCache = new TTLCache();
+const datasetCache = new TTLCache();
 export async function searchDatasets(query, limit = 10) {
+    const key = `search:${query}:${limit}`;
+    const cached = searchCache.get(key);
+    if (cached !== undefined)
+        return cached;
     const result = await ckanAction('package_search', { q: query, rows: limit });
+    searchCache.set(key, result.results, CACHE_TTL_MS);
     return result.results;
 }
 export async function getDataset(id) {
-    return ckanAction('package_show', { id });
+    const key = `dataset:${id}`;
+    const cached = datasetCache.get(key);
+    if (cached !== undefined)
+        return cached;
+    const dataset = await ckanAction('package_show', { id });
+    datasetCache.set(key, dataset, CACHE_TTL_MS);
+    return dataset;
 }
 export async function getResourceData(resourceId, limit = 50, offset = 0) {
     return ckanAction('datastore_search', {
@@ -35,9 +109,23 @@ const PARSEABLE_FORMATS = new Set(['CSV', 'TSV', 'JSON']);
 export async function fetchAndParseFile(url, format, limit, offset) {
     const normalizedFormat = format.toUpperCase().trim();
     if (!PARSEABLE_FORMATS.has(normalizedFormat)) {
-        throw new Error(`FORMAT_NOT_PARSEABLE:${normalizedFormat}:${url}`);
+        throw new NotParseableError(normalizedFormat, url);
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    let response;
+    try {
+        response = await fetch(url, { signal: controller.signal });
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === 'AbortError') {
+            throw new Error(`Request timed out after ${FETCH_TIMEOUT_MS / 1000}s`);
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timer);
     }
-    const response = await fetch(url);
     if (!response.ok) {
         throw new Error(`Failed to fetch file: ${response.status} ${response.statusText}`);
     }

package/dist/server.js

@@ -1,10 +1,13 @@
+import { createRequire } from 'node:module';
 import { McpServer } from '@modelcontextprotocol/server';
 import { registerSearchTool } from './tools/search.js';
 import { registerDatasetTool } from './tools/dataset.js';
 import { registerResourceTool } from './tools/resource.js';
+const _require = createRequire(import.meta.url);
+const { version } = _require('../package.json');
 export const server = new McpServer({
     name: 'datos-gob-cl',
-    version: '1.0.0',
+    version,
 });
 registerSearchTool(server);
 registerDatasetTool(server);

package/dist/stdio.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 import { StdioServerTransport } from '@modelcontextprotocol/server';
 import { server } from './server.js';
 const transport = new StdioServerTransport();

package/dist/tools/resource.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { getResourceData, getResource, fetchAndParseFile } from '../ckan.js';
+import { getResourceData, getResource, fetchAndParseFile, NotParseableError, CkanHttpError, CkanApiError } from '../ckan.js';
 export function registerResourceTool(server) {
     server.registerTool('get_resource_data', {
         title: 'Get Resource Data',
@@ -30,11 +30,10 @@ export function registerResourceTool(server) {
             };
         }
         catch (datastoreError) {
-            const dsMessage = datastoreError instanceof Error ? datastoreError.message : String(datastoreError);
-            const isNoDatastore = dsMessage.toLowerCase().includes('datastore') ||
-                dsMessage.includes('404') ||
-                dsMessage.toUpperCase().includes('NOT FOUND');
+            const isNoDatastore = (datastoreError instanceof CkanHttpError && datastoreError.statusCode === 404) ||
+                (datastoreError instanceof CkanApiError && datastoreError.errorType.toLowerCase().includes('not found'));
             if (!isNoDatastore) {
+                const dsMessage = datastoreError instanceof Error ? datastoreError.message : String(datastoreError);
                 return {
                     content: [{ type: 'text', text: `Error: ${dsMessage}` }],
                     isError: true,
@@ -62,23 +61,22 @@ export function registerResourceTool(server) {
             };
         }
         catch (fileError) {
-            const fileMessage = fileError instanceof Error ? fileError.message : String(fileError);
             // Format not parseable — return the URL so the AI can guide the user
-            if (fileMessage.startsWith('FORMAT_NOT_PARSEABLE:')) {
-                const [, fmt, url] = fileMessage.split(':');
+            if (fileError instanceof NotParseableError) {
                 return {
                     content: [{
                             type: 'text',
                             text: JSON.stringify({
                                 source: 'file',
                                 parseable: false,
-                                format: fmt,
-                                url,
-                                message: `This resource is a ${fmt} file and cannot be parsed automatically. Download it directly from the URL above.`,
+                                format: fileError.format,
+                                url: fileError.url,
+                                message: `This resource is a ${fileError.format} file and cannot be parsed automatically. Download it directly from the URL above.`,
                             }, null, 2),
                         }],
                 };
             }
+            const fileMessage = fileError instanceof Error ? fileError.message : String(fileError);
             return {
                 content: [{ type: 'text', text: `Error reading file: ${fileMessage}` }],
                 isError: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-chilegob-dataset",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "MCP server exposing Chile's open government dataset portal (datos.gob.cl / CKAN API v3)",
   "type": "module",
   "license": "MIT",
@@ -37,8 +37,7 @@
     "prepublishOnly": "tsc"
   },
   "dependencies": {
-    "@cfworker/json-schema": "^4.1.1",
-    "@hono/node-server": "^1.19.13",
+"@hono/node-server": "^1.19.13",
     "@modelcontextprotocol/hono": "^2.0.0-alpha.2",
     "@modelcontextprotocol/server": "^2.0.0-alpha.2",
     "hono": "^4.12.12",

package/src/ckan.ts

@@ -1,4 +1,54 @@
 const CKAN_BASE = 'https://datos.gob.cl/api/3/action'
+const FETCH_TIMEOUT_MS = 10_000
+const CACHE_TTL_MS = 5 * 60 * 1000
+
+class TTLCache<V> {
+  private readonly store = new Map<string, { value: V; expiresAt: number }>()
+
+  get(key: string): V | undefined {
+    const entry = this.store.get(key)
+    if (entry === undefined) return undefined
+    if (Date.now() > entry.expiresAt) {
+      this.store.delete(key)
+      return undefined
+    }
+    return entry.value
+  }
+
+  set(key: string, value: V, ttlMs: number): void {
+    this.store.set(key, { value, expiresAt: Date.now() + ttlMs })
+  }
+}
+
+export class NotParseableError extends Error {
+  constructor(
+    public readonly format: string,
+    public readonly url: string,
+  ) {
+    super(`Format not parseable: ${format} (${url})`)
+    this.name = 'NotParseableError'
+  }
+}
+
+export class CkanHttpError extends Error {
+  constructor(
+    public readonly statusCode: number,
+    public readonly statusText: string,
+  ) {
+    super(`CKAN HTTP error: ${statusCode} ${statusText}`)
+    this.name = 'CkanHttpError'
+  }
+}
+
+export class CkanApiError extends Error {
+  constructor(
+    message: string,
+    public readonly errorType: string,
+  ) {
+    super(`CKAN API error: ${message}`)
+    this.name = 'CkanApiError'
+  }
+}
 
 export interface CkanDataset {
   id: string
@@ -43,26 +93,51 @@ async function ckanAction<T>(action: string, params: Record<string, unknown>): P
     url.searchParams.set(key, String(value))
   }
 
-  const response = await fetch(url.toString())
-  if (!response.ok) {
-    throw new Error(`CKAN API error: ${response.status} ${response.statusText}`)
-  }
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS)
+  try {
+    const response = await fetch(url.toString(), { signal: controller.signal })
+    if (!response.ok) {
+      throw new CkanHttpError(response.status, response.statusText)
+    }
 
-  const data = await response.json() as { success: boolean; result: T; error?: { message: string } }
-  if (!data.success) {
-    throw new Error(`CKAN error: ${data.error?.message ?? 'Unknown error'}`)
-  }
+    const data = await response.json() as { success: boolean; result: T; error?: { __type: string; message?: string } }
+    if (!data.success) {
+      const errorType = data.error?.__type ?? 'Unknown Error'
+      const message = data.error?.message ?? 'Unknown error'
+      throw new CkanApiError(message, errorType)
+    }
 
-  return data.result
+    return data.result
+  } catch (err) {
+    if (err instanceof Error && err.name === 'AbortError') {
+      throw new Error(`Request timed out after ${FETCH_TIMEOUT_MS / 1000}s`)
+    }
+    throw err
+  } finally {
+    clearTimeout(timer)
+  }
 }
 
+const searchCache = new TTLCache<CkanDataset[]>()
+const datasetCache = new TTLCache<CkanDataset>()
+
 export async function searchDatasets(query: string, limit: number = 10): Promise<CkanDataset[]> {
+  const key = `search:${query}:${limit}`
+  const cached = searchCache.get(key)
+  if (cached !== undefined) return cached
   const result = await ckanAction<{ results: CkanDataset[] }>('package_search', { q: query, rows: limit })
+  searchCache.set(key, result.results, CACHE_TTL_MS)
   return result.results
 }
 
 export async function getDataset(id: string): Promise<CkanDataset> {
-  return ckanAction<CkanDataset>('package_show', { id })
+  const key = `dataset:${id}`
+  const cached = datasetCache.get(key)
+  if (cached !== undefined) return cached
+  const dataset = await ckanAction<CkanDataset>('package_show', { id })
+  datasetCache.set(key, dataset, CACHE_TTL_MS)
+  return dataset
 }
 
 export async function getResourceData(
@@ -92,12 +167,22 @@ export async function fetchAndParseFile(
   const normalizedFormat = format.toUpperCase().trim()
 
   if (!PARSEABLE_FORMATS.has(normalizedFormat)) {
-    throw new Error(
-      `FORMAT_NOT_PARSEABLE:${normalizedFormat}:${url}`
-    )
+    throw new NotParseableError(normalizedFormat, url)
   }
 
-  const response = await fetch(url)
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS)
+  let response: Response
+  try {
+    response = await fetch(url, { signal: controller.signal })
+  } catch (err) {
+    if (err instanceof Error && err.name === 'AbortError') {
+      throw new Error(`Request timed out after ${FETCH_TIMEOUT_MS / 1000}s`)
+    }
+    throw err
+  } finally {
+    clearTimeout(timer)
+  }
   if (!response.ok) {
     throw new Error(`Failed to fetch file: ${response.status} ${response.statusText}`)
   }

package/src/server.ts

@@ -1,11 +1,15 @@
+import { createRequire } from 'node:module'
 import { McpServer } from '@modelcontextprotocol/server'
 import { registerSearchTool } from './tools/search.js'
 import { registerDatasetTool } from './tools/dataset.js'
 import { registerResourceTool } from './tools/resource.js'
 
+const _require = createRequire(import.meta.url)
+const { version } = _require('../package.json') as { version: string }
+
 export const server = new McpServer({
   name: 'datos-gob-cl',
-  version: '1.0.0',
+  version,
 })
 
 registerSearchTool(server)

package/src/stdio.ts

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 import { StdioServerTransport } from '@modelcontextprotocol/server'
 import { server } from './server.js'
 

package/src/tools/resource.ts

@@ -1,6 +1,6 @@
 import type { McpServer } from '@modelcontextprotocol/server'
 import { z } from 'zod'
-import { getResourceData, getResource, fetchAndParseFile } from '../ckan.js'
+import { getResourceData, getResource, fetchAndParseFile, NotParseableError, CkanHttpError, CkanApiError } from '../ckan.js'
 
 export function registerResourceTool(server: McpServer): void {
   server.registerTool(
@@ -36,13 +36,12 @@ export function registerResourceTool(server: McpServer): void {
           }],
         }
       } catch (datastoreError) {
-        const dsMessage = datastoreError instanceof Error ? datastoreError.message : String(datastoreError)
         const isNoDatastore =
-          dsMessage.toLowerCase().includes('datastore') ||
-          dsMessage.includes('404') ||
-          dsMessage.toUpperCase().includes('NOT FOUND')
+          (datastoreError instanceof CkanHttpError && datastoreError.statusCode === 404) ||
+          (datastoreError instanceof CkanApiError && datastoreError.errorType.toLowerCase().includes('not found'))
 
         if (!isNoDatastore) {
+          const dsMessage = datastoreError instanceof Error ? datastoreError.message : String(datastoreError)
           return {
             content: [{ type: 'text', text: `Error: ${dsMessage}` }],
             isError: true,
@@ -71,25 +70,24 @@ export function registerResourceTool(server: McpServer): void {
           }],
         }
       } catch (fileError) {
-        const fileMessage = fileError instanceof Error ? fileError.message : String(fileError)
-
         // Format not parseable — return the URL so the AI can guide the user
-        if (fileMessage.startsWith('FORMAT_NOT_PARSEABLE:')) {
-          const [, fmt, url] = fileMessage.split(':')
+        if (fileError instanceof NotParseableError) {
           return {
             content: [{
               type: 'text',
               text: JSON.stringify({
                 source: 'file',
                 parseable: false,
-                format: fmt,
-                url,
-                message: `This resource is a ${fmt} file and cannot be parsed automatically. Download it directly from the URL above.`,
+                format: fileError.format,
+                url: fileError.url,
+                message: `This resource is a ${fileError.format} file and cannot be parsed automatically. Download it directly from the URL above.`,
               }, null, 2),
             }],
           }
         }
 
+        const fileMessage = fileError instanceof Error ? fileError.message : String(fileError)
+
         return {
           content: [{ type: 'text', text: `Error reading file: ${fileMessage}` }],
           isError: true,