Data.gov.il

Acesse dados abertos do governo israelense no portal data.gov.il.

Documentação

data-gov-il-mcp

Servidor Model Context Protocol (MCP) de nível de produção para Dados Abertos do Governo de Israel, disponíveis em data.gov.il.

Este servidor oferece a clientes compatíveis com MCP acesso estruturado a conjuntos de dados, recursos, tags, organizações e registros tabulares do governo israelense por meio da API oficial CKAN. Ele é escrito em TypeScript, valida entradas e saídas com Zod, retorna respostas de ferramentas em formato JSON e suporta tanto transporte local stdio quanto transporte remoto Streamable HTTP.

Destaques

Área	Status
Ferramentas MCP	9 ferramentas por padrão, 10 com Sampling opcional habilitado
Recursos MCP	5 recursos estáticos + 1 modelo de recurso de conjunto de dados
Prompts MCP	3 prompts de domínio com preenchimento de argumentos
Descoberta	Snapshot do catálogo em memória com normalização em hebraico, correspondência difusa, ranqueamento de tags e co-ocorrência
Transportes	`stdio` e Streamable HTTP
Autenticação	`none`, autenticação por bearer token de API, OAuth 2.1 JWT/JWKS
Reforço HTTP	Helmet, CORS, limitação de taxa, IDs de requisição, validação de Host/Origin
Respostas	`structuredContent` além de JSON idêntico em `content[0].text`
Configuração em tempo de execução	Orientada por ambiente, validada na inicialização com Zod

Início Rápido

Claude Desktop / Stdio Local

Use o pacote publicado diretamente:

{
  "mcpServers": {
    "data-gov-il": {
      "command": "npx",
      "args": ["-y", "data-gov-il-mcp"]
    }
  }
}

Streamable HTTP

npm install -g data-gov-il-mcp
data-gov-il-mcp-http

Em seguida, configure seu cliente MCP:

{
  "mcpServers": {
    "data-gov-il": {
      "url": "http://localhost:3664/mcp"
    }
  }
}

Docker

docker run -p 3664:3664 ghcr.io/davidosherproceed/data-gov-il-mcp:latest

Para desenvolvimento local:

npm install
npm run build
npm run start:stdio
# or
npm run start:http

Camada de Descoberta de Catálogo

O servidor inclui um snapshot do catálogo em src/data/catalog/catalog.snapshot.json. O snapshot é gerado a partir do data.gov.il e incluído no build. Na inicialização, ele é validado e indexado em memória.

A camada de descoberta alimenta:

find_datasets busca catálogo-primeiro com fallback ao vivo para CKAN.
list_all_datasets enumeração local instantânea com filtro opcional por organização.
list_organizations lista local instantânea de organizações com contagens de conjuntos de dados.
list_available_tags e search_tags a partir de dados reais de tags/facetas do CKAN.
Preenchimentos dinâmicos para datagov://dataset/{id}.
Recursos datagov://tags e datagov://catalog/stats.

Ela inclui:

Normalização em hebraico, incluindo remoção de nikud e normalização de letras finais.
Tokenização e índices de trigramas para correspondência difusa e tolerância a erros de digitação.
Mapas de conjuntos de dados, tags e organizações.
Índices de tag-para-conjunto de dados e organização-para-conjunto de dados.
Co-ocorrência de tags para sugestões de tags relacionadas.
Ranqueamento ponderado entre sinais exatos, de token, de tag, de organização e difusos.

Atualize o snapshot:

npm run catalog:refresh
npm run build

Um fluxo de trabalho agendado do GitHub Actions (.github/workflows/catalog-refresh.yml) atualiza o snapshot e abre um PR quando os dados do catálogo mudam.

Mais detalhes: docs/catalog-discovery-layer.md.

Ferramentas

Todas as respostas bem-sucedidas de ferramentas retornam:

structuredContent: o objeto JSON tipado.
content[0].text: o mesmo objeto serializado como JSON para clientes somente texto.

Ferramentas Padrão

Ferramenta	Finalidade
`find_datasets`	Ferramenta principal de descoberta de conjuntos de dados. Usa o catálogo local primeiro e, em seguida, fallback ao vivo para CKAN quando necessário.
`get_dataset_info`	Metadados CKAN completos de um conjunto de dados, incluindo tags e recursos.
`list_all_datasets`	Resumos instantâneos de conjuntos de dados com base no catálogo, opcionalmente filtrados por organização.
`list_resources`	Lista arquivos/datastores dentro de um conjunto de dados e identifica recursos `datastore_active`.
`search_records`	Consulta registros do datastore CKAN com busca em texto completo, filtros, campos, ordenação, paginação e valores distintos.
`list_organizations`	Organizações com base no catálogo, com títulos em hebraico e contagens de conjuntos de dados.
`get_organization_info`	Metadados de organização CKAN ao vivo.
`list_available_tags`	Tags do catálogo ranqueadas, com contagens de conjuntos de dados e tags relacionadas.
`search_tags`	Busca difusa de tags com sugestões de tags relacionadas.

Ferramentas Opcionais

Ferramenta	Habilitada Por	Finalidade
`summarize_dataset`	`MCP_ENABLE_SAMPLING=true`	Solicita Sampling MCP de clientes compatíveis para produzir um resumo legível do conjunto de dados. Retorna aos metadados quando Sampling não está disponível.

Elicitação em `find_datasets`

find_datasets pode opcionalmente expor um parâmetro interactive:

{
  "query": "תחבורה",
  "interactive": true
}

Isso só é registrado quando:

MCP_ENABLE_ELICITATION=true

Quando habilitado, clientes compatíveis podem exibir um formulário de esclarecimento para buscas amplas. Por exemplo, o servidor pode pedir ao usuário para restringir muitos conjuntos de dados correspondentes por organização publicadora. Se o cliente não suportar Elicitação, o usuário recusar ou a requisição expirar, a ferramenta retorna aos resultados normais de busca.

Isso está desabilitado por padrão porque o suporte a Elicitação varia entre clientes MCP.

Recursos

URI	Tipo	Descrição
`datagov://organizations`	JSON estático	Lista de organizações do CKAN, em cache.
`datagov://tags`	JSON estático	Tags ranqueadas do snapshot do catálogo incluído.
`datagov://featured`	JSON estático	Conjuntos de dados de alto valor selecionados, com valores `resource_id` prontos para uso e esquemas de campos.
`datagov://guide`	Texto estático	Guia de uso para ferramentas, recursos e fluxos de trabalho recomendados.
`datagov://catalog/stats`	JSON estático	Metadados do snapshot: horário de geração, contagem de conjuntos de dados, contagem de tags, contagem de organizações, principais organizações.
`datagov://dataset/{id}`	Modelo JSON	Metadados completos do conjunto de dados por slug ou ID. Inclui preenchimentos dinâmicos e lista de recursos com base no catálogo.

O servidor também implementa assinaturas de recursos de forma mínima e compatível com padrões:

Anuncia resources.subscribe.
Trata resources/subscribe e resources/unsubscribe.
Envia notifications/resources/updated apenas para recursos aos quais um cliente assinou.
Não consulta o CKAN em tempo real.

Prompts

Prompt	Argumento	Finalidade
`food-nutrition-analysis`	`analysis_type`	Preços de alimentos, nutrição, kosher, segurança, importação/exportação.
`environmental-sustainability-analysis`	`analysis_focus`	Qualidade do ar, construções verdes, resíduos, água, locais contaminados.
`real-estate-market-analysis`	`market_focus`	Habitação, renovação urbana, habitação subsidiada, análise de cidade/propriedade.

Os argumentos dos prompts usam preenchimentos MCP. As sugestões de foco de domínio são selecionadas e os preenchimentos de organização têm base no catálogo.

Recursos Opcionais de Cliente MCP

Esses recursos estão desabilitados por padrão. Habilite-os apenas quando seu cliente MCP de destino os suportar e você quiser que o servidor os exponha.

Variável	Padrão	Efeito
`MCP_ENABLE_ELICITATION`	`false`	Adiciona `interactive` a `find_datasets` e permite formulários de esclarecimento iniciados pelo servidor. Funciona em clientes como Cursor e Claude Code.
`MCP_ENABLE_SAMPLING`	`false`	Registra `summarize_dataset`, que solicita geração de modelo no lado do cliente por meio de Sampling MCP.

O suporte do cliente varia:

Cursor suporta Elicitação, mas atualmente não expõe Sampling.
Claude Code suporta Elicitação em versões recentes.
Claude Desktop suporta muitos recursos MCP, mas o suporte a Elicitação não é confiável/disponível.
A disponibilidade de Sampling varia; o servidor sempre retorna com segurança.

Configuração

Copie .env.example para .env:

cp .env.example .env

Núcleo

Variável	Padrão	Descrição
`TRANSPORT`	`stdio`	Transporte padrão ao usar o ponto de entrada genérico. Binários dedicados também estão disponíveis.
`PORT`	`3664`	Porta HTTP.
`HOST`	`0.0.0.0`	Host de bind HTTP.
`CORS_ORIGIN`	`*`	Origens CORS permitidas. Evite curinga em implantações de navegador em produção.
`LOG_LEVEL`	`info`	`fatal`, `error`, `warn`, `info`, `debug` ou `trace`.
`NODE_ENV`	`production`	`development`, `production` ou `test`.

CKAN

Variável	Padrão	Descrição
`CKAN_BASE_URL`	`https://data.gov.il/api/3/action`	URL base da API de ações CKAN.
`CKAN_TIMEOUT_MS`	`10000`	Timeout padrão de requisições CKAN.
`CKAN_SEARCH_TIMEOUT_MS`	`15000`	Timeout para requisições mais pesadas de datastore/busca.
`CACHE_TTL_MS`	`300000`	TTL padrão de cache.
`CACHE_MAX_ITEMS`	`500`	Máximo de entradas por cache em memória.

Reforço HTTP

Variável	Padrão	Descrição
`TRUST_PROXY`	`false`	Confiar em cabeçalhos de proxy reverso. Defina ao usar nginx/Caddy/ALB.
`RATE_LIMIT_WINDOW_MS`	`60000`	Janela de limitação de taxa. Defina `0` para desabilitar.
`RATE_LIMIT_MAX`	`120`	Requisições por IP por janela. Defina `0` para desabilitar.
`ALLOWED_HOSTS`	vazio	Lista de permissões de Host para proteção contra rebinding de DNS. Padrão: loopback/hosts locais quando não definido.
`ALLOWED_ORIGINS`	vazio	Lista de permissões de Origin do navegador. Retorna a `CORS_ORIGIN` quando apropriado.

Autenticação

Variável	Padrão	Descrição
`AUTH_MODE`	`none`	`none`, `apikey` ou `oauth`.
`API_KEYS`	vazio	Tokens bearer separados por vírgula para `AUTH_MODE=apikey`.
`OAUTH_ISSUER`	não definido	Emissor JWT esperado para `AUTH_MODE=oauth`.
`OAUTH_AUDIENCE`	não definido	Audiência JWT esperada para `AUTH_MODE=oauth`.
`OAUTH_JWKS_URI`	não definido	URL JWKS para verificação JWT.
`OAUTH_RESOURCE_SERVER`	não definido	URL canônica de recurso MCP para metadados de recurso protegido OAuth. Geralmente inclui `/mcp`.

Identidade do Serviço

Variável	Padrão	Descrição
`SERVICE_NAME`	padrão do pacote/servidor	Substituição do nome do servidor MCP.
`SERVICE_VERSION`	versão do pacote	Substituição da versão do servidor MCP.
`SERVICE_DESCRIPTION`	descrição integrada	Substituição da descrição semântica do servidor MCP.

Fluxos de Trabalho Recomendados

Encontrar e Consultar um Conjunto de Dados

Use find_datasets com termos naturais em hebraico ou inglês.
Use get_dataset_info ou list_resources para um conjunto de dados escolhido.
Escolha um recurso com datastore_active=true.
Use search_records com limit=5 primeiro para inspecionar campos.
Adicione filters, fields, sort, distinct ou paginação conforme necessário.

Exemplo de fluxo:

find_datasets({ "query": "מחיר למשתכן" })
get_dataset_info({ "dataset": "mechir-lamishtaken" })
search_records({
  "resource_id": "7c8255d0-49ef-49db-8904-4cf917586031",
  "limit": 5,
  "include_total": true
})

Descobrir Tags

search_tags({ "keyword": "דיור", "limit": 5 })
find_datasets({ "query": "תחבורה", "tags": "תחבורה ציבורית" })

Usar Descoberta Interativa

Requer:

MCP_ENABLE_ELICITATION=true

Em seguida, um agente pode chamar:

find_datasets({ "query": "תחבורה", "interactive": true })

Clientes compatíveis podem exibir um formulário pedindo ao usuário para restringir os resultados.

Usar Resumos no Lado do Cliente

Requer:

MCP_ENABLE_SAMPLING=true

Em seguida:

summarize_dataset({ "dataset": "mechir-lamishtaken", "language": "he" })

Se Sampling não estiver disponível, a ferramenta retorna os metadados do conjunto de dados e sampling.used=false.

Desenvolvimento

npm install

# Type-check
npm run typecheck

# Lint
npm run lint

# Test
npm test

# Build
npm run build

# Refresh local catalog snapshot
npm run catalog:refresh

Execute localmente:

# stdio
npm run build
npm run start:stdio

# HTTP
npm run build
npm run start:http

Habilite recursos opcionais localmente:

MCP_ENABLE_ELICITATION=true MCP_ENABLE_SAMPLING=true npm run start:http

No PowerShell:

$env:MCP_ENABLE_ELICITATION="true"
$env:MCP_ENABLE_SAMPLING="true"
npm run start:http

Estrutura do Projeto

src/
  auth/           Authentication providers and Express middleware
  bin/            stdio and HTTP entry points
  cache/          In-memory TTL/LRU cache
  catalog/        Snapshot validation, indexing, fuzzy search, CatalogService
  ckan/           Typed CKAN API client and CKAN response types
  config/         Zod env config, constants, server identity
  core/           Dependency container, MCP server factory, lifecycle
  data/catalog/   Committed catalog snapshot artifact
  formatting/     JSON response builders and guidance text
  observability/  Pino logger
  prompts/        MCP prompt definitions, templates, registration
  resources/      MCP resources, templates, subscriptions
  services/       Domain services for CKAN data access
  tools/          MCP tool definitions and Zod schemas
  transports/     stdio and Streamable HTTP transports
tests/
  fixtures/       Test fixtures
  unit/           Unit tests
scripts/
  refresh-catalog.ts
docs/
  catalog-discovery-layer.md
  MIGRATION.md

Docker

docker build -t data-gov-il-mcp .
docker run -p 3664:3664 data-gov-il-mcp

Com recursos opcionais:

docker run -p 3664:3664 \
  -e MCP_ENABLE_ELICITATION=true \
  -e MCP_ENABLE_SAMPLING=true \
  data-gov-il-mcp

Qualidade

Espera-se que o projeto passe:

npm run typecheck
npm run lint
npm test
npm run build

A implementação atual inclui cobertura de testes unitários para análise de ambiente, provedores de autenticação, erros CKAN, cache, formatação, lógica de normalização/correspondência difusa/índice/busca de texto do catálogo, validação de snapshot, serviços, recursos, assinaturas e proteção de Host/Origin HTTP.

Licença

MIT

Data.gov.il

Documentação

data-gov-il-mcp

Destaques

Início Rápido

Claude Desktop / Stdio Local

Streamable HTTP

Docker

Camada de Descoberta de Catálogo

Ferramentas

Ferramentas Padrão

Ferramentas Opcionais

Elicitação em find_datasets

Recursos

Prompts

Recursos Opcionais de Cliente MCP

Configuração

Núcleo

CKAN

Reforço HTTP

Autenticação

Identidade do Serviço

Fluxos de Trabalho Recomendados

Encontrar e Consultar um Conjunto de Dados

Descobrir Tags

Usar Descoberta Interativa

Usar Resumos no Lado do Cliente

Desenvolvimento

Estrutura do Projeto

Docker

Qualidade

Licença

Elicitação em `find_datasets`