mcp-chilegob-dataset 0.3.0 → 0.3.2

package/README.md

@@ -23,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.
 

package/dist/ckan.js

@@ -83,8 +83,9 @@ export async function searchDatasets(query, limit = 10) {
     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;
+    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}`;
@@ -105,7 +106,30 @@ export async function getResourceData(resourceId, limit = 50, offset = 0) {
 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)) {
@@ -127,7 +151,7 @@ export async function fetchAndParseFile(url, format, limit, offset) {
         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') {
         const json = await response.json();
@@ -141,7 +165,9 @@ export async function fetchAndParseFile(url, format, limit, offset) {
         return { fields, records: page, total: rows.length, source: 'file' };
     }
     // 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() !== '');
     if (lines.length === 0) {

package/dist/server.js

@@ -3,6 +3,8 @@ 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({
@@ -12,3 +14,5 @@ export const server = new McpServer({
 registerSearchTool(server);
 registerDatasetTool(server);
 registerResourceTool(server);
+registerOrganizationsTool(server);
+registerSchemaTool(server);

package/dist/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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-chilegob-dataset",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "MCP server exposing Chile's open government dataset portal (datos.gob.cl / CKAN API v3)",
   "type": "module",
   "license": "MIT",
@@ -34,10 +34,12 @@
     "build": "tsc",
     "start": "node dist/index.js",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "tsc"
+    "prepublishOnly": "npm run build",
+    "postbuild": "node scripts/add-shebang.mjs",
+    "test": "vitest run"
   },
   "dependencies": {
-"@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",
@@ -46,6 +48,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

@@ -119,16 +119,29 @@ async function ckanAction<T>(action: string, params: Record<string, unknown>): P
   }
 }
 
-const searchCache = new TTLCache<CkanDataset[]>()
+export interface CkanOrganization {
+  name: string
+  title: string
+  description: string | null
+  package_count: number
+}
+
+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<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<{ results: CkanDataset[] }>('package_search', { q: query, rows: limit })
-  searchCache.set(key, result.results, CACHE_TTL_MS)
-  return result.results
+  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> {
@@ -156,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,
@@ -184,7 +236,7 @@ export async function fetchAndParseFile(
     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') {
@@ -202,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

@@ -3,6 +3,8 @@ 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 }
@@ -15,3 +17,5 @@ export const server = new McpServer({
 registerSearchTool(server)
 registerDatasetTool(server)
 registerResourceTool(server)
+registerOrganizationsTool(server)
+registerSchemaTool(server)

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/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 {