Toronto Open Data Tools

Consulta, analiza y recupera conjuntos de datos del portal de datos abiertos de Toronto impulsado por CKAN.

Documentación

Toronto MCP Server: Toronto Open Data Tools

Este proyecto implementa un servidor de Model Context Protocol (MCP) para Toronto Open Data, desplegable en Cloudflare Workers. Expone un conjunto completo de herramientas para consultar, analizar y recuperar conjuntos de datos de forma inteligente desde el portal de datos abiertos de Toronto basado en CKAN, haciéndolos accesibles a clientes compatibles con MCP como Claude Desktop, Cursor y otros asistentes de IA.

🚀 Servidor en Vivo

Desplegado en: https://toronto-mcp.s-a62.workers.dev

SSE Endpoint: https://toronto-mcp.s-a62.workers.dev/sse (para Claude Desktop)
MCP Endpoint: https://toronto-mcp.s-a62.workers.dev/mcp (para otros clientes)

¿Qué hace?

Proporciona un servidor MCP remoto que expone herramientas para los datos abiertos de Toronto a través de la API de CKAN
Descubre inteligentemente conjuntos de datos relevantes mediante puntuación avanzada de relevancia
Analiza patrones de actualidad de los datos con seguimiento exhaustivo de la frecuencia de actualización
Proporciona información detallada sobre la estructura de los datos, incluido el análisis de campos e información de esquemas
Permite consultas en lenguaje natural de los más de 500 conjuntos de datos abiertos de Toronto
Admite análisis de datos exhaustivos que combinan múltiples dimensiones analíticas

🛠️ Características

Herramientas Básicas de CKAN

list_datasets: Listar todos los conjuntos de datos disponibles
search_datasets: Buscar conjuntos de datos por palabra clave
get_package: Recuperar metadatos completos de un conjunto de datos
get_first_datastore_resource_records: Obtener registros del primer recurso activo
get_resource_records: Obtener registros de un recurso específico por ID

🧠 Herramientas de Análisis Avanzado

find_relevant_datasets: Encontrar y clasificar conjuntos de datos de forma inteligente mediante puntuación de relevancia (título, descripción, etiquetas, organización)
analyze_dataset_updates: Analizar frecuencias de actualización con categorización (diaria, semanal, mensual, trimestral, anual, irregular)
analyze_dataset_structure: Análisis profundo de la estructura de los conjuntos de datos con definiciones de campos, tipos de datos, recuentos de registros y vistas previas opcionales de datos
get_data_categories: Explorar todas las organizaciones y grupos temáticos disponibles
get_dataset_insights: Análisis exhaustivo que combina clasificación por relevancia, frecuencia de actualización e información sobre la estructura de los datos

💡 Casos de Uso

Para Asistentes de IA e Investigadores

"¿Qué datos de tráfico están disponibles en Toronto?" → Conjuntos de datos clasificados con puntuaciones de relevancia y frecuencias de actualización
"¿Qué tan actualizados están los datos ambientales de Toronto?" → Análisis de frecuencia de actualización en conjuntos de datos ambientales
"¿Qué campos tiene el conjunto de datos de permisos de construcción?" → Análisis completo del esquema con tipos de datos y registros de muestra
"Dame información sobre los datos presupuestarios de Toronto" → Análisis exhaustivo con relevancia, actualidad y estructura
"¿Qué conjuntos de datos se actualizan a diario?" → Filtrado y categorización basados en la frecuencia

Para Científicos de Datos y Analistas

Descubrir conjuntos de datos relevantes para preguntas de investigación específicas
Evaluar la calidad y fiabilidad de los datos mediante patrones de actualización
Comprender la estructura de los datos antes de un análisis detallado
Encontrar conjuntos de datos relacionados en diferentes departamentos de la ciudad
Evaluar la completitud de los datos y la disponibilidad de campos

🏗️ Stack Tecnológico

Cloudflare Workers: Plataforma de despliegue serverless
Model Context Protocol (MCP): Estándar para integraciones de herramientas de IA
TypeScript: Seguridad de tipos y desarrollo moderno
Zod: Validación de parámetros en tiempo de ejecución
CKAN API: Integración directa con Toronto Open Data

📁 Estructura del Proyecto

toronto-mcp/
├── src/
│   ├── index.ts                 # MCP server setup and routing
│   └── ckanTools.ts            # Toronto Open Data tools implementation
├── test-runner.ts              # Automated testing framework
├── test-deployment.ts          # Deployment validation script
├── claude-mcp-config.json      # Claude Desktop configuration
├── evaluation-guide.md         # Comprehensive testing strategies
├── example-usage.md            # Usage examples and patterns
├── testing-guide.md            # Automated testing documentation
└── README.md                   # This file

🚀 Inicio Rápido

1. Despliega Tu Propia Instancia

# Clone and deploy
git clone <your-repo>
cd toronto-mcp
npm install
wrangler deploy

2. Prueba el Despliegue

# Install testing dependencies
npm install tsx

# Test your deployment
npx tsx test-deployment.ts https://your-worker.workers.dev

3. Conéctate a Claude Desktop

Crea o edita ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "toronto-mcp": {
      "command": "npx",
      "args": ["mcp-remote", "https://toronto-mcp.s-a62.workers.dev/sse"]
    }
  }
}

Reinicia Claude Desktop y empieza a hacer preguntas sobre los datos abiertos de Toronto.

🧪 Pruebas y Validación

Prueba Rápida de Conectividad

npx tsx test-deployment.ts https://toronto-mcp.s-a62.workers.dev

Marco de Pruebas Automatizadas

# Run mock tests (validates framework)
npm test

# Test specific deployment
npm run test:deployment https://your-url.workers.dev

Pruebas Manuales en Claude Desktop

Prueba estas consultas de prueba para verificar la funcionalidad:

Búsqueda Básica: "Encuentra conjuntos de datos sobre estacionamiento en Toronto"
Análisis de Actualización: "¿Con qué frecuencia actualiza Toronto los datos de tráfico?"
Estructura de Datos: "¿Qué campos tiene el conjunto de datos de permisos de construcción de Toronto?"
Exhaustivo: "Dame información sobre los datos ambientales de Toronto"
Categorías: "¿Qué departamentos proporcionan datos abiertos en Toronto?"

📊 Métricas de Éxito

Tu servidor MCP funciona correctamente cuando:

✅ Claude selecciona consistentemente las herramientas adecuadas para las consultas
✅ Los resultados incluyen puntuaciones de relevancia y clasificaciones
✅ La información de frecuencia de actualización se categoriza correctamente
✅ El análisis de estructura de datos muestra información completa de los campos
✅ Los tiempos de respuesta son inferiores a 10 segundos para consultas complejas
✅ El manejo de errores proporciona mensajes útiles

📚 Documentación

📘 Guía de Ejemplos de Uso

Ejemplos concretos de cómo usar cada herramienta MCP, incluidos parámetros JSON y respuestas esperadas. Esencial para comprender las capacidades de las herramientas y los patrones de integración.

📊 Guía de Evaluación y Pruebas

Estrategias de prueba exhaustivas, métricas de calidad y criterios de evaluación. Incluye consultas de prueba manuales, puntos de referencia de rendimiento y métricas de éxito para validar la funcionalidad del servidor MCP.

🧪 Marco de Pruebas Automatizadas

Marco de pruebas TypeScript para validación programática, monitoreo de rendimiento y aseguramiento automatizado de la calidad. Incluye casos de prueba ejecutables y patrones de integración CI/CD.

⚙️ Configuración de Claude Desktop

Configuración de servidor MCP lista para usar para la integración con Claude Desktop.

🎯 Ejemplo de Uso de Herramientas

Consultas en Lenguaje Natural (a través del Asistente de IA)

"What traffic data is available in Toronto and how current is it?"
"Find housing development datasets with field information"
"Which Toronto datasets update daily?"
"Give me insights about budget and financial data"

Llamadas Directas a Herramientas (para desarrolladores)

// Intelligent dataset discovery
await find_relevant_datasets({
  query: "traffic accidents",
  maxResults: 5,
  includeRelevanceScore: true,
});

// Update frequency analysis
await analyze_dataset_updates({
  query: "transportation",
  groupByFrequency: true,
});

// Complete data structure analysis
await analyze_dataset_structure({
  packageId: "building-permits",
  includeDataPreview: true,
  previewLimit: 10,
});

// Comprehensive insights
await get_dataset_insights({
  query: "housing development",
  maxDatasets: 3,
  includeUpdateFrequency: true,
  includeDataStructure: true,
});

🔧 Scripts Disponibles

npm run dev           # Start development server
npm run deploy        # Deploy to Cloudflare Workers
npm run test          # Run automated tests
npm run test:deployment  # Test specific deployment
npm run lint:fix      # Fix linting issues
npm run format        # Format code

🌟 Características Clave

Puntuación Inteligente de Relevancia

Algoritmo ponderado: Título (10 pts) > Descripción (5 pts) > Etiquetas (3 pts) > Organización (2 pts)
Clasificación consciente del contexto: Relaciona la intención del usuario con los conjuntos de datos adecuados
Soporte de múltiples palabras clave: Maneja consultas complejas de manera efectiva

Análisis Exhaustivo de Actualizaciones

Categorización de frecuencia: Diaria, semanal, mensual, trimestral, anual, irregular
Inferencia de metadatos: Analiza patrones cuando no hay calendarios explícitos disponibles
Evaluación de calidad: Identifica conjuntos de datos desactualizados frente a los que se mantienen activamente

Información Profunda sobre la Estructura de Datos

Análisis completo del esquema: Nombres de campos, tipos, restricciones
Estadísticas de registros: Recuentos, completitud, indicadores de calidad de datos
Datos de muestra: Vistas previas opcionales para una evaluación rápida
Soporte de múltiples recursos: Maneja conjuntos de datos con múltiples archivos/formatos

🚀 Extensión

Para añadir más herramientas o fuentes de datos:

Edita src/ckanTools.ts para añadir nuevas funciones de herramientas
Registra nuevas herramientas en src/index.ts
Actualiza las definiciones de tipos y los esquemas de validación
Añade las pruebas correspondientes en el marco de pruebas

Ejemplo:

server.tool("new_analysis_tool", { param: z.string() }, async ({ param }) => {
  // Implementation
  return { content: [{ type: "text", text: result }] };
});

🤝 Contribuciones

Haz un fork del repositorio
Crea una rama de características
Añade pruebas para la nueva funcionalidad
Asegúrate de que todas las pruebas pasen: npm test
Envía un pull request

📄 Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles.

Construido para el descubrimiento inteligente de datos abiertos • Impulsado por Toronto Open Data y la API de CKAN • Mejorado para la integración con asistentes de IA