Toronto Open Data Tools

Consulte, analise e recupere conjuntos de dados do portal de dados abertos de Toronto, alimentado por CKAN.

Documentação

Toronto MCP Server: Toronto Open Data Tools

Este projeto implementa um servidor Model Context Protocol (MCP) para Toronto Open Data, implantável em Cloudflare Workers. Ele expõe um conjunto abrangente de ferramentas para consultar, analisar e recuperar conjuntos de dados de forma inteligente do portal de dados abertos de Toronto, baseado em CKAN, tornando-os acessíveis a clientes compatíveis com MCP, como Claude Desktop, Cursor e outros assistentes de IA.

🚀 Servidor ao Vivo

Implantado em: https://toronto-mcp.s-a62.workers.dev

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

O que ele faz?

Fornece um servidor MCP remoto expondo ferramentas para os Dados Abertos de Toronto via API CKAN
Descobre inteligentemente conjuntos de dados relevantes usando pontuação avançada de relevância
Analisa padrões de atualização de dados com rastreamento abrangente de frequência de atualização
Fornece insights profundos sobre a estrutura dos dados, incluindo análise de campos e informações de esquema
Permite consultas em linguagem natural dos mais de 500 conjuntos de dados abertos de Toronto
Suporta análise abrangente de dados combinando múltiplas dimensões analíticas

🛠️ Recursos

Ferramentas Básicas CKAN

list_datasets: Listar todos os conjuntos de dados disponíveis
search_datasets: Pesquisar conjuntos de dados por palavra-chave
get_package: Recuperar metadados completos de um conjunto de dados
get_first_datastore_resource_records: Obter registros do primeiro recurso ativo
get_resource_records: Obter registros de um recurso específico por ID

🧠 Ferramentas Avançadas de Análise

find_relevant_datasets: Encontrar e classificar conjuntos de dados de forma inteligente usando pontuação de relevância (título, descrição, tags, organização)
analyze_dataset_updates: Analisar frequências de atualização com categorização (diária, semanal, mensal, trimestral, anual, irregular)
analyze_dataset_structure: Análise aprofundada da estrutura do conjunto de dados com definições de campos, tipos de dados, contagens de registros e pré-visualizações opcionais de dados
get_data_categories: Explorar todas as organizações e grupos de tópicos disponíveis
get_dataset_insights: Análise abrangente combinando classificação de relevância, frequência de atualização e insights sobre a estrutura dos dados

💡 Casos de Uso

Para Assistentes de IA e Pesquisadores

"Quais dados de tráfego estão disponíveis em Toronto?" → Conjuntos de dados classificados com pontuações de relevância e frequências de atualização
"Quão atualizados estão os dados ambientais de Toronto?" → Análise de frequência de atualização em conjuntos de dados ambientais
"Quais campos existem no conjunto de dados de licenças de construção?" → Análise completa do esquema com tipos de dados e registros de exemplo
"Dê-me insights sobre os dados orçamentários de Toronto" → Análise abrangente com relevância, atualidade e estrutura
"Quais conjuntos de dados são atualizados diariamente?" → Filtragem e categorização baseadas em frequência

Para Cientistas de Dados e Analistas

Descobrir conjuntos de dados relevantes para questões de pesquisa específicas
Avaliar qualidade e confiabilidade dos dados por meio de padrões de atualização
Entender a estrutura dos dados antes de uma análise detalhada
Encontrar conjuntos de dados relacionados em diferentes departamentos municipais
Avaliar completude dos dados e disponibilidade de campos

🏗️ Stack Tecnológica

Cloudflare Workers: Plataforma de implantação serverless
Model Context Protocol (MCP): Padrão para integrações de ferramentas de IA
TypeScript: Segurança de tipos e desenvolvimento moderno
Zod: Validação de parâmetros em tempo de execução
API CKAN: Integração direta com Toronto Open Data

📁 Estrutura do Projeto

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

🚀 Início Rápido

1. Implante Sua Própria Instância

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

2. Teste a Implantação

# Install testing dependencies
npm install tsx

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

3. Conecte ao Claude Desktop

Crie ou edite ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Reinicie o Claude Desktop e comece a fazer perguntas sobre os dados abertos de Toronto!

🧪 Testes e Validação

Teste Rápido de Conectividade

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

Framework de Testes Automatizados

# Run mock tests (validates framework)
npm test

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

Testes Manuais no Claude Desktop

Experimente estas consultas de teste para verificar a funcionalidade:

Pesquisa Básica: "Encontre conjuntos de dados sobre estacionamento em Toronto"
Análise de Atualização: "Com que frequência Toronto atualiza os dados de tráfego?"
Estrutura de Dados: "Quais campos existem nos dados de licenças de construção de Toronto?"
Abrangente: "Dê-me insights sobre os dados ambientais de Toronto"
Categorias: "Quais departamentos fornecem dados abertos em Toronto?"

📊 Métricas de Sucesso

Seu servidor MCP está funcionando corretamente quando:

✅ Claude seleciona consistentemente as ferramentas apropriadas para as consultas
✅ Os resultados incluem pontuações de relevância e classificações
✅ As informações de frequência de atualização são categorizadas corretamente
✅ A análise da estrutura de dados mostra informações completas dos campos
✅ Os tempos de resposta são inferiores a 10 segundos para consultas complexas
✅ O tratamento de erros fornece mensagens úteis

📚 Documentação

📘 Guia de Exemplos de Uso

Exemplos concretos de como usar cada ferramenta MCP, incluindo parâmetros JSON e respostas esperadas. Essencial para entender as capacidades das ferramentas e os padrões de integração.

📊 Guia de Avaliação e Testes

Estratégias abrangentes de teste, métricas de qualidade e critérios de avaliação. Inclui consultas de teste manuais, benchmarks de desempenho e métricas de sucesso para validar a funcionalidade do servidor MCP.

🧪 Framework de Testes Automatizados

Framework de testes em TypeScript para validação programática, monitoramento de desempenho e garantia de qualidade automatizada. Inclui casos de teste executáveis e padrões de integração CI/CD.

⚙️ Configuração do Claude Desktop

Configuração pronta para uso do servidor MCP para integração com Claude Desktop.

🎯 Exemplo de Uso das Ferramentas

Consultas em Linguagem Natural (via Assistente 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"

Chamadas Diretas de Ferramentas (para desenvolvedores)

// 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 Disponíveis

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

🌟 Recursos Principais

Pontuação Inteligente de Relevância

Algoritmo ponderado: Título (10pts) > Descrição (5pts) > Tags (3pts) > Organização (2pts)
Classificação sensível ao contexto: Combina a intenção do usuário com conjuntos de dados apropriados
Suporte a múltiplas palavras-chave: Lida com consultas complexas de forma eficaz

Análise Abrangente de Atualizações

Categorização de frequência: Diária, semanal, mensal, trimestral, anual, irregular
Inferência de metadados: Analisa padrões quando cronogramas explícitos não estão disponíveis
Avaliação de qualidade: Identifica conjuntos de dados desatualizados versus ativamente mantidos

Insights Profundos sobre a Estrutura de Dados

Análise completa do esquema: Nomes de campos, tipos, restrições
Estatísticas de registros: Contagens, completude, indicadores de qualidade de dados
Dados de exemplo: Pré-visualizações opcionais para avaliação rápida
Suporte a múltiplos recursos: Lida com conjuntos de dados com múltiplos arquivos/formatos

🚀 Extensão

Para adicionar mais ferramentas ou fontes de dados:

Edite src/ckanTools.ts para adicionar novas funções de ferramentas
Registre novas ferramentas em src/index.ts
Atualize as definições de tipos e esquemas de validação
Adicione testes correspondentes no framework de testes

Exemplo:

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

🤝 Contribuição

Faça um fork do repositório
Crie um branch de funcionalidade
Adicione testes para novas funcionalidades
Garanta que todos os testes passem: npm test
Envie um pull request

📄 Licença

Licença MIT - consulte o arquivo LICENSE para obter detalhes.

Construído para descoberta inteligente de dados abertos • Desenvolvido com Toronto Open Data & API CKAN • Aprimorado para integração com assistentes de IA