mcp-chilegob-dataset 0.2.1 → 0.3.1

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).
@@ -18,7 +23,17 @@ El **Model Context Protocol (MCP)** es un estándar abierto que permite a los as
 
 ## Instalación y uso rápido
 
-### Con Claude Desktop (recomendado)
+### Con Claude Code (un comando)
+
+```bash
+claude mcp add chilegob -- npx -y mcp-chilegob-dataset
+```
+
+Eso es todo. El servidor queda registrado globalmente en tu Claude Code. Reinicia la sesión y ya puedes usarlo.
+
+---
+
+### Con Claude Desktop
 
 **Paso 1** — Abre la configuración de Claude Desktop.
 
@@ -180,7 +195,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 +294,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 +306,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/src/ckan.js

@@ -0,0 +1,211 @@
+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 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;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+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 });
+    const value = { total: result.count, results: result.results };
+    searchCache.set(key, value, CACHE_TTL_MS);
+    return value;
+}
+export async function getDataset(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', {
+        resource_id: resourceId,
+        limit,
+        offset,
+    });
+}
+export async function getResource(resourceId) {
+    return ckanAction('resource_show', { id: resourceId });
+}
+export async function listOrganizations() {
+    return ckanAction('organization_list', { all_fields: true });
+}
+export async function getResourceSchema(resourceId) {
+    const result = await ckanAction('datastore_info', { id: resourceId });
+    return result.fields
+        .filter(field => field.id !== '_id')
+        .map(field => ({
+        id: field.id,
+        type: field.type,
+        label: field.info?.label ?? null,
+        description: field.info?.notes ?? null,
+    }));
+}
+const PARSEABLE_FORMATS = new Set(['CSV', 'TSV', 'JSON']);
+function decodeText(buffer, contentType) {
+    const charsetMatch = /charset=([^\s;]+)/i.exec(contentType);
+    const charset = (charsetMatch?.[1] ?? 'utf-8').replace(/^"|"$/g, '');
+    const text = new TextDecoder(charset).decode(buffer);
+    if (text.includes('\uFFFD') && charset.toLowerCase() === 'utf-8') {
+        return new TextDecoder('iso-8859-1').decode(buffer);
+    }
+    return text;
+}
+export async function fetchAndParseFile(url, format, limit, offset) {
+    const normalizedFormat = format.toUpperCase().trim();
+    if (!PARSEABLE_FORMATS.has(normalizedFormat)) {
+        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);
+    }
+    if (!response.ok) {
+        throw new CkanHttpError(response.status, response.statusText);
+    }
+    if (normalizedFormat === 'JSON') {
+        const json = await response.json();
+        const rows = Array.isArray(json)
+            ? json
+            : [{ data: json }];
+        const page = rows.slice(offset, offset + limit);
+        const fields = page.length > 0
+            ? Object.keys(page[0]).map(key => ({ id: key, type: 'text' }))
+            : [];
+        return { fields, records: page, total: rows.length, source: 'file' };
+    }
+    // CSV / TSV
+    const buffer = await response.arrayBuffer();
+    const contentType = response.headers.get('content-type') ?? '';
+    const text = decodeText(buffer, contentType);
+    const separator = normalizedFormat === 'TSV' ? '\t' : ',';
+    const lines = text.split(/\r?\n/).filter(l => l.trim() !== '');
+    if (lines.length === 0) {
+        return { fields: [], records: [], total: 0, source: 'file' };
+    }
+    const headers = parseDelimitedLine(lines[0], separator);
+    const dataLines = lines.slice(1);
+    const page = dataLines.slice(offset, offset + limit);
+    const records = page.map(line => {
+        const values = parseDelimitedLine(line, separator);
+        return Object.fromEntries(headers.map((h, i) => [h, values[i] ?? '']));
+    });
+    const fields = headers.map(h => ({ id: h, type: 'text' }));
+    return { fields, records, total: dataLines.length, source: 'file' };
+}
+function parseDelimitedLine(line, separator) {
+    const result = [];
+    let current = '';
+    let inQuotes = false;
+    for (let i = 0; i < line.length; i++) {
+        const char = line[i];
+        if (char === '"') {
+            if (inQuotes && line[i + 1] === '"') {
+                current += '"';
+                i++;
+            }
+            else {
+                inQuotes = !inQuotes;
+            }
+        }
+        else if (char === separator && !inQuotes) {
+            result.push(current);
+            current = '';
+        }
+        else {
+            current += char;
+        }
+    }
+    result.push(current);
+    return result;
+}

package/dist/{server.js → src/server.js}

@@ -1,11 +1,18 @@
+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';
+import { registerOrganizationsTool } from './tools/organizations.js';
+import { registerSchemaTool } from './tools/schema.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);
 registerResourceTool(server);
+registerOrganizationsTool(server);
+registerSchemaTool(server);

package/dist/{stdio.js → src/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/src/tools/organizations.js

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import { listOrganizations } from '../ckan.js';
+export function registerOrganizationsTool(server) {
+    server.registerTool('list_organizations', {
+        title: 'List Organizations',
+        description: 'List all government institutions (organizations) that publish datasets on datos.gob.cl. Use this to discover which institutions have data before searching.',
+        inputSchema: z.object({}),
+    }, async () => {
+        try {
+            const orgs = await listOrganizations();
+            const formatted = orgs
+                .filter(o => o.package_count > 0)
+                .sort((a, b) => b.package_count - a.package_count)
+                .map(o => ({
+                id: o.name,
+                title: o.title,
+                description: o.description?.slice(0, 150) ?? '',
+                dataset_count: o.package_count,
+            }));
+            return {
+                content: [{ type: 'text', text: JSON.stringify(formatted, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : String(error)}` }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/{tools → src/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/dist/src/tools/schema.js

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import { getResourceSchema } from '../ckan.js';
+export function registerSchemaTool(server) {
+    server.registerTool('get_resource_schema', {
+        title: 'Get Resource Schema',
+        description: 'Get the column schema (field names, types, and descriptions) for a CKAN datastore resource. Only works for resources that have datastore enabled (datastore_available: true from get_dataset). Use this before reading data to understand the structure.',
+        inputSchema: z.object({
+            resource_id: z.string().describe('UUID of the resource (from get_dataset)'),
+        }),
+    }, async ({ resource_id }) => {
+        try {
+            const fields = await getResourceSchema(resource_id);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(fields, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : String(error)}` }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/{tools → src/tools}/search.js

@@ -11,7 +11,7 @@ export function registerSearchTool(server) {
     }, async ({ query, limit }) => {
         try {
             const datasets = await searchDatasets(query, limit ?? 10);
-            const formatted = datasets.map(d => ({
+            const formatted = datasets.results.map(d => ({
                 id: d.name,
                 title: d.title,
                 description: d.notes?.slice(0, 200) ?? '',
@@ -19,7 +19,7 @@ export function registerSearchTool(server) {
                 resource_count: d.num_resources,
             }));
             return {
-                content: [{ type: 'text', text: JSON.stringify(formatted, null, 2) }],
+                content: [{ type: 'text', text: JSON.stringify({ total: datasets.total, returned: formatted.length, results: formatted }, null, 2) }],
             };
         }
         catch (error) {

package/dist/vitest.config.js

@@ -0,0 +1,6 @@
+import { defineConfig } from 'vitest/config';
+export default defineConfig({
+    test: {
+        environment: 'node',
+    },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-chilegob-dataset",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "MCP server exposing Chile's open government dataset portal (datos.gob.cl / CKAN API v3)",
   "type": "module",
   "license": "MIT",
@@ -34,10 +34,10 @@
     "build": "tsc",
     "start": "node dist/index.js",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "tsc"
+    "prepublishOnly": "tsc",
+    "test": "vitest run"
   },
   "dependencies": {
-    "@cfworker/json-schema": "^4.1.1",
     "@hono/node-server": "^1.19.13",
     "@modelcontextprotocol/hono": "^2.0.0-alpha.2",
     "@modelcontextprotocol/server": "^2.0.0-alpha.2",
@@ -47,6 +47,7 @@
   "devDependencies": {
     "@types/node": "^20.11.17",
     "tsx": "^4.7.1",
-    "typescript": "^5.8.3"
+    "typescript": "^5.8.3",
+    "vitest": "^4.1.4"
   }
 }

package/src/__tests__/ckan.test.ts

@@ -0,0 +1,122 @@
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import {
+  NotParseableError,
+  CkanHttpError,
+  CkanApiError,
+  fetchAndParseFile,
+} from '../ckan.ts'
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+describe('Error classes', () => {
+  it('NotParseableError sets format and url', () => {
+    const err = new NotParseableError('XLS', 'https://example.com/file.xls')
+    expect(err.format).toBe('XLS')
+    expect(err.url).toBe('https://example.com/file.xls')
+    expect(err.name).toBe('NotParseableError')
+    expect(err).toBeInstanceOf(Error)
+  })
+
+  it('CkanHttpError sets statusCode and statusText', () => {
+    const err = new CkanHttpError(404, 'Not Found')
+    expect(err.statusCode).toBe(404)
+    expect(err.statusText).toBe('Not Found')
+    expect(err.name).toBe('CkanHttpError')
+  })
+
+  it('CkanApiError sets errorType', () => {
+    const err = new CkanApiError('something failed', 'Validation Error')
+    expect(err.errorType).toBe('Validation Error')
+    expect(err.name).toBe('CkanApiError')
+  })
+})
+
+describe('fetchAndParseFile', () => {
+  it('throws NotParseableError for XLS format', async () => {
+    await expect(fetchAndParseFile('https://x.com/f.xls', 'XLS', 10, 0))
+      .rejects.toBeInstanceOf(NotParseableError)
+  })
+
+  it('throws NotParseableError for PDF format', async () => {
+    await expect(fetchAndParseFile('https://x.com/f.pdf', 'PDF', 10, 0))
+      .rejects.toBeInstanceOf(NotParseableError)
+  })
+
+  it('parses CSV and returns correct fields and records', async () => {
+    const csvContent = 'Region,Provincia,Comuna\nCOQUIMBO,ELQUI,LA SERENA\nATACAMA,COPIAPO,COPIAPO\n'
+    vi.spyOn(global, 'fetch').mockResolvedValueOnce(
+      new Response(csvContent, {
+        status: 200,
+        headers: { 'content-type': 'text/csv; charset=utf-8' },
+      })
+    )
+
+    const result = await fetchAndParseFile('https://x.com/data.csv', 'CSV', 10, 0)
+    expect(result.fields).toEqual([
+      { id: 'Region', type: 'text' },
+      { id: 'Provincia', type: 'text' },
+      { id: 'Comuna', type: 'text' },
+    ])
+    expect(result.records).toHaveLength(2)
+    expect(result.records[0]).toEqual({ Region: 'COQUIMBO', Provincia: 'ELQUI', Comuna: 'LA SERENA' })
+    expect(result.total).toBe(2)
+    expect(result.source).toBe('file')
+  })
+
+  it('respects limit and offset', async () => {
+    const lines = ['A,B', '1,2', '3,4', '5,6', '7,8'].join('\n')
+    vi.spyOn(global, 'fetch').mockResolvedValueOnce(
+      new Response(lines, { status: 200, headers: { 'content-type': 'text/csv' } })
+    )
+
+    const result = await fetchAndParseFile('https://x.com/data.csv', 'CSV', 2, 1)
+    expect(result.records).toHaveLength(2)
+    expect(result.records[0]).toEqual({ A: '3', B: '4' })
+    expect(result.total).toBe(4)
+  })
+
+  it('parses TSV and splits on tab', async () => {
+    const tsv = 'A\tB\n1\t2\n3\t4\n'
+    vi.spyOn(global, 'fetch').mockResolvedValueOnce(
+      new Response(tsv, { status: 200, headers: { 'content-type': 'text/tab-separated-values' } })
+    )
+    const result = await fetchAndParseFile('https://x.com/data.tsv', 'TSV', 10, 0)
+    expect(result.records[0]).toEqual({ A: '1', B: '2' })
+    expect(result.total).toBe(2)
+    expect(result.source).toBe('file')
+  })
+
+  it('parses JSON array and returns records', async () => {
+    const json = JSON.stringify([{ name: 'Chile', code: 'CL' }, { name: 'Peru', code: 'PE' }])
+    vi.spyOn(global, 'fetch').mockResolvedValueOnce(
+      new Response(json, { status: 200, headers: { 'content-type': 'application/json' } })
+    )
+    const result = await fetchAndParseFile('https://x.com/data.json', 'JSON', 10, 0)
+    expect(result.total).toBe(2)
+    expect(result.records[0]).toEqual({ name: 'Chile', code: 'CL' })
+    expect(result.fields).toEqual([{ id: 'name', type: 'text' }, { id: 'code', type: 'text' }])
+    expect(result.source).toBe('file')
+  })
+
+  it('returns empty result for empty CSV body', async () => {
+    vi.spyOn(global, 'fetch').mockResolvedValueOnce(
+      new Response('\n\n  \n', { status: 200, headers: { 'content-type': 'text/csv' } })
+    )
+    const result = await fetchAndParseFile('https://x.com/empty.csv', 'CSV', 10, 0)
+    expect(result.fields).toEqual([])
+    expect(result.records).toEqual([])
+    expect(result.total).toBe(0)
+  })
+
+  it('throws CkanHttpError with correct status on non-ok response', async () => {
+    vi.spyOn(global, 'fetch').mockResolvedValueOnce(
+      new Response('Not Found', { status: 404, statusText: 'Not Found' })
+    )
+    const err = await fetchAndParseFile('https://x.com/data.csv', 'CSV', 10, 0).catch(e => e)
+    expect(err).toBeInstanceOf(CkanHttpError)
+    expect(err.statusCode).toBe(404)
+    expect(err.statusText).toBe('Not Found')
+  })
+})

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,64 @@ 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
+  } 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)
   }
+}
 
-  return data.result
+export interface CkanOrganization {
+  name: string
+  title: string
+  description: string | null
+  package_count: number
 }
 
-export async function searchDatasets(query: string, limit: number = 10): Promise<CkanDataset[]> {
-  const result = await ckanAction<{ results: CkanDataset[] }>('package_search', { q: query, rows: limit })
-  return result.results
+export interface CkanSearchResult {
+  total: number
+  results: CkanDataset[]
+}
+
+const searchCache = new TTLCache<CkanSearchResult>()
+const datasetCache = new TTLCache<CkanDataset>()
+
+export async function searchDatasets(query: string, limit: number = 10): Promise<CkanSearchResult> {
+  const key = `search:${query}:${limit}`
+  const cached = searchCache.get(key)
+  if (cached !== undefined) return cached
+  const result = await ckanAction<{ count: number; results: CkanDataset[] }>('package_search', { q: query, rows: limit })
+  const value: CkanSearchResult = { total: result.count, results: result.results }
+  searchCache.set(key, value, CACHE_TTL_MS)
+  return value
 }
 
 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(
@@ -81,8 +169,47 @@ export async function getResource(resourceId: string): Promise<CkanResourceDetai
   return ckanAction<CkanResourceDetail>('resource_show', { id: resourceId })
 }
 
+export async function listOrganizations(): Promise<CkanOrganization[]> {
+  return ckanAction<CkanOrganization[]>('organization_list', { all_fields: true })
+}
+
+export interface CkanFieldSchema {
+  id: string
+  type: string
+  label: string | null
+  description: string | null
+}
+
+interface RawField {
+  id: string
+  type: string
+  info?: { label?: string; notes?: string }
+}
+
+export async function getResourceSchema(resourceId: string): Promise<CkanFieldSchema[]> {
+  const result = await ckanAction<{ id: string; fields: RawField[] }>('datastore_info', { id: resourceId })
+  return result.fields
+    .filter(field => field.id !== '_id')
+    .map(field => ({
+      id: field.id,
+      type: field.type,
+      label: field.info?.label ?? null,
+      description: field.info?.notes ?? null,
+    }))
+}
+
 const PARSEABLE_FORMATS = new Set(['CSV', 'TSV', 'JSON'])
 
+function decodeText(buffer: ArrayBuffer, contentType: string): string {
+  const charsetMatch = /charset=([^\s;]+)/i.exec(contentType)
+  const charset = (charsetMatch?.[1] ?? 'utf-8').replace(/^"|"$/g, '')
+  const text = new TextDecoder(charset).decode(buffer)
+  if (text.includes('\uFFFD') && charset.toLowerCase() === 'utf-8') {
+    return new TextDecoder('iso-8859-1').decode(buffer)
+  }
+  return text
+}
+
 export async function fetchAndParseFile(
   url: string,
   format: string,
@@ -92,14 +219,24 @@ 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}`)
+    throw new CkanHttpError(response.status, response.statusText)
   }
 
   if (normalizedFormat === 'JSON') {
@@ -117,7 +254,9 @@ export async function fetchAndParseFile(
   }
 
   // CSV / TSV
-  const text = await response.text()
+  const buffer = await response.arrayBuffer()
+  const contentType = response.headers.get('content-type') ?? ''
+  const text = decodeText(buffer, contentType)
   const separator = normalizedFormat === 'TSV' ? '\t' : ','
   const lines = text.split(/\r?\n/).filter(l => l.trim() !== '')
 

package/src/server.ts

@@ -1,13 +1,21 @@
+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'
+import { registerOrganizationsTool } from './tools/organizations.js'
+import { registerSchemaTool } from './tools/schema.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)
 registerDatasetTool(server)
 registerResourceTool(server)
+registerOrganizationsTool(server)
+registerSchemaTool(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/organizations.ts

@@ -0,0 +1,36 @@
+import type { McpServer } from '@modelcontextprotocol/server'
+import { z } from 'zod'
+import { listOrganizations } from '../ckan.js'
+
+export function registerOrganizationsTool(server: McpServer): void {
+  server.registerTool(
+    'list_organizations',
+    {
+      title: 'List Organizations',
+      description: 'List all government institutions (organizations) that publish datasets on datos.gob.cl. Use this to discover which institutions have data before searching.',
+      inputSchema: z.object({}),
+    },
+    async () => {
+      try {
+        const orgs = await listOrganizations()
+        const formatted = orgs
+          .filter(o => o.package_count > 0)
+          .sort((a, b) => b.package_count - a.package_count)
+          .map(o => ({
+            id: o.name,
+            title: o.title,
+            description: o.description?.slice(0, 150) ?? '',
+            dataset_count: o.package_count,
+          }))
+        return {
+          content: [{ type: 'text', text: JSON.stringify(formatted, null, 2) }],
+        }
+      } catch (error) {
+        return {
+          content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : String(error)}` }],
+          isError: true,
+        }
+      }
+    }
+  )
+}

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,

package/src/tools/schema.ts

@@ -0,0 +1,30 @@
+import type { McpServer } from '@modelcontextprotocol/server'
+import { z } from 'zod'
+import { getResourceSchema } from '../ckan.js'
+
+export function registerSchemaTool(server: McpServer): void {
+  server.registerTool(
+    'get_resource_schema',
+    {
+      title: 'Get Resource Schema',
+      description:
+        'Get the column schema (field names, types, and descriptions) for a CKAN datastore resource. Only works for resources that have datastore enabled (datastore_available: true from get_dataset). Use this before reading data to understand the structure.',
+      inputSchema: z.object({
+        resource_id: z.string().describe('UUID of the resource (from get_dataset)'),
+      }),
+    },
+    async ({ resource_id }) => {
+      try {
+        const fields = await getResourceSchema(resource_id)
+        return {
+          content: [{ type: 'text', text: JSON.stringify(fields, null, 2) }],
+        }
+      } catch (error) {
+        return {
+          content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : String(error)}` }],
+          isError: true,
+        }
+      }
+    }
+  )
+}

package/src/tools/search.ts

@@ -16,7 +16,7 @@ export function registerSearchTool(server: McpServer): void {
     async ({ query, limit }) => {
       try {
         const datasets = await searchDatasets(query, limit ?? 10)
-        const formatted = datasets.map(d => ({
+        const formatted = datasets.results.map(d => ({
           id: d.name,
           title: d.title,
           description: d.notes?.slice(0, 200) ?? '',
@@ -24,7 +24,7 @@ export function registerSearchTool(server: McpServer): void {
           resource_count: d.num_resources,
         }))
         return {
-          content: [{ type: 'text', text: JSON.stringify(formatted, null, 2) }],
+          content: [{ type: 'text', text: JSON.stringify({ total: datasets.total, returned: formatted.length, results: formatted }, null, 2) }],
         }
       } catch (error) {
         return {

package/dist/ckan.js

@@ -1,97 +0,0 @@
-const CKAN_BASE = 'https://datos.gob.cl/api/3/action';
-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 data = await response.json();
-    if (!data.success) {
-        throw new Error(`CKAN error: ${data.error?.message ?? 'Unknown error'}`);
-    }
-    return data.result;
-}
-export async function searchDatasets(query, limit = 10) {
-    const result = await ckanAction('package_search', { q: query, rows: limit });
-    return result.results;
-}
-export async function getDataset(id) {
-    return ckanAction('package_show', { id });
-}
-export async function getResourceData(resourceId, limit = 50, offset = 0) {
-    return ckanAction('datastore_search', {
-        resource_id: resourceId,
-        limit,
-        offset,
-    });
-}
-export async function getResource(resourceId) {
-    return ckanAction('resource_show', { id: resourceId });
-}
-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}`);
-    }
-    const response = await fetch(url);
-    if (!response.ok) {
-        throw new Error(`Failed to fetch file: ${response.status} ${response.statusText}`);
-    }
-    if (normalizedFormat === 'JSON') {
-        const json = await response.json();
-        const rows = Array.isArray(json)
-            ? json
-            : [{ data: json }];
-        const page = rows.slice(offset, offset + limit);
-        const fields = page.length > 0
-            ? Object.keys(page[0]).map(key => ({ id: key, type: 'text' }))
-            : [];
-        return { fields, records: page, total: rows.length, source: 'file' };
-    }
-    // CSV / TSV
-    const text = await response.text();
-    const separator = normalizedFormat === 'TSV' ? '\t' : ',';
-    const lines = text.split(/\r?\n/).filter(l => l.trim() !== '');
-    if (lines.length === 0) {
-        return { fields: [], records: [], total: 0, source: 'file' };
-    }
-    const headers = parseDelimitedLine(lines[0], separator);
-    const dataLines = lines.slice(1);
-    const page = dataLines.slice(offset, offset + limit);
-    const records = page.map(line => {
-        const values = parseDelimitedLine(line, separator);
-        return Object.fromEntries(headers.map((h, i) => [h, values[i] ?? '']));
-    });
-    const fields = headers.map(h => ({ id: h, type: 'text' }));
-    return { fields, records, total: dataLines.length, source: 'file' };
-}
-function parseDelimitedLine(line, separator) {
-    const result = [];
-    let current = '';
-    let inQuotes = false;
-    for (let i = 0; i < line.length; i++) {
-        const char = line[i];
-        if (char === '"') {
-            if (inQuotes && line[i + 1] === '"') {
-                current += '"';
-                i++;
-            }
-            else {
-                inQuotes = !inQuotes;
-            }
-        }
-        else if (char === separator && !inQuotes) {
-            result.push(current);
-            current = '';
-        }
-        else {
-            current += char;
-        }
-    }
-    result.push(current);
-    return result;
-}