GovData MCP

GovData MCP

Um servidor Model Context Protocol (MCP) que permite que agentes de IA pesquisem, explorem e busquem conjuntos de dados abertos de portais oficiais de dados governamentais. Uma interface de ferramenta unificada para Estados Unidos, Reino Unido, Canadá e Austrália — com peculiaridades de cada portal (migrações de API, barreiras de autenticação, metadados bilíngues, flags obsoletas do DataStore) absorvidas por uma camada comum de adaptadores.

Projetado para o fluxo de trabalho típico de agentes: "Existe um conjunto de dados governamentais para X?" → encontrar candidatos → inspecionar os arquivos → visualizar linhas ou obter um link de download e seguir em frente.

Principais Recursos

• Quatro portais nacionais, uma interface. EUA (data.gov v4 / DCAT), Reino Unido (data.gov.uk / CKAN), Canadá (open.canada.ca / CKAN), Austrália (data.gov.au / CKAN + DataStore).
• Econômico em tokens por design. As descrições são limpas de HTML e truncadas, os resultados de busca são resumos compactos e arquivos grandes nunca são incorporados acidentalmente.
• Pré-visualização em nível de linha. Usa o CKAN DataStore quando disponível (Austrália) e, de forma transparente, recorre à leitura do início de arquivos CSV/TSV em todos os outros casos.
• Modos de falha amigáveis para agentes. Erros são retornados como texto acionável ("use get_download_link em vez disso", "tente novamente com dataset_id", "portais disponíveis: …") — nunca tracebacks brutos.
• Registro extensível. Adicionar outro portal baseado em CKAN é uma única entrada de configuração; portais não-CKAN se integram por meio de uma pequena classe de adaptador.
• Transporte duplo. stdio para clientes locais (Claude Desktop etc.), streamable-http sem estado para implantação serverless (Google Cloud Run).

Portais Suportados

Requisitos

• Python 3.11+
• Uma chave de API do api.data.gov para o portal dos EUA (gratuita; os outros portais não exigem credenciais)

Instalação

git clone https://github.com/YOUR_ORG/Gov-Stat-MCP-Server.git
cd Gov-Stat-MCP-Server

# pip
pip install -e ".[dev]"

# or conda
conda env create -f environment.yml
conda activate opendata-mcp

Copie .env.example para .env e defina sua chave:

DATAGOV_API_KEY=your-api-data-gov-key

Primeiros Passos

Configuração padrão para a maioria dos clientes MCP (transporte stdio):

{
  "mcpServers": {
    "govdata": {
      "command": "govdata-mcp",
      "env": {
        "DATAGOV_API_KEY": "your-api-data-gov-key"
      }
    }
  }
}

claude mcp add govdata -e DATAGOV_API_KEY=your-key -- govdata-mcp

MCP_TRANSPORT=http govdata-mcp

{
  "mcpServers": {
    "govdata": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Ferramentas

O fluxo de agente pretendido: list_portals → search_datasets → get_dataset → preview_resource / fetch_resource / get_download_link.

Configuração

Todas as configurações são variáveis de ambiente (ou um arquivo .env local):

Docker

make docker-build          # build image
make docker-run            # run on :8080, exactly as Cloud Run would

A imagem executa o transporte HTTP em modo sem estado e está pronta para plataformas serverless (script de implantação no Google Cloud Run incluído em deploy/).

Desenvolvimento

make run          # stdio mode
make run-http     # HTTP mode on :8080
make inspect      # MCP Inspector interactive UI (requires Node.js)
make test         # offline unit tests
make test-live    # live end-to-end tests against all four real portals
make lint         # ruff check + format check

A suíte ao vivo (pytest -m live) verifica a cadeia completa de busca → exploração → pré-visualização → busca de dados por país, além do comportamento específico de cada portal (normalização bilíngue do Canadá, consulta de recursos com escopo de conjunto de dados do Reino Unido, caminhos do DataStore da Austrália). Execute-a antes de implantar — portais governamentais mudam sem aviso.

Arquitetura

src/govdata_mcp/
├── server.py            # FastMCP instance + tool registration
├── config.py            # env-driven settings
├── ckan/                # generic async CKAN client, models, typed errors
├── portals/
│   ├── registry.py      # portal registry — single source of truth
│   ├── base.py          # Portal config + default (vanilla CKAN) adapter
│   ├── us.py            # data.gov v4 DCAT adapter (auth, cursor paging)
│   ├── uk.py            # dataset-scoped resource lookup
│   └── ca.py            # bilingual metadata normalization
├── tools/               # MCP tools: search, explore, fetch
└── utils/               # formatting (token economy), CSV-head preview

Adicionando um portal: para um portal CKAN padrão, adicione uma entrada Portal(...) em portals/registry.py — pronto. Para portais com peculiaridades, subclassifique PortalAdapter e sobrescreva os hooks específicos (normalize_dataset, build_search_params) ou, para APIs não-CKAN, os próprios métodos de operação (veja us.py para um adaptador personalizado completo).

TODO / Roadmap

• 🇨🇳 Suporte ao portal da China — não existe uma API nacional unificada de dados abertos; planejado como um adaptador personalizado direcionado aos dados do National Bureau of Statistics (por meio de um pacote de estatísticas existente) com degradação graciosa.
• 🇯🇵 Suporte ao portal do Japão — o e-Gov Data Portal (data.e-gov.go.jp) é compatível com CKAN e deve se encaixar no registro existente; a API de estatísticas mais rica do e-Stat (autenticação por app-ID, metadados em japonês) está planejada como um adaptador dedicado.
• Suíte de testes unitários offline com fixtures de portal gravadas (respx) para CI
• Tutorial de implantação no Google Cloud Run (o serviço está pronto para contêiner; script em deploy/)
• Filtros de busca por publicador/formato do US v4 (aguardando documentação da API)
• Mais portais CKAN (Nova Zelândia data.govt.nz é uma adição quase gratuita)
• Detecção de tipo de conteúdo para resgatar formatos de recurso rotulados incorretamente

Notas de Segurança

• Este servidor é somente leitura em relação aos portais — nenhuma ferramenta pode criar, modificar ou excluir nada.
• fetch_resource e preview_resource baixam de URLs contidas nos metadados do portal; o conteúdo é limitado em tamanho e verificado quanto a binários antes de ser retornado ao modelo, mas trate o conteúdo buscado como entrada não confiável.
• O servidor em si não tem autenticação. Para implantação remota, coloque-o atrás de um proxy autenticador ou autenticação em nível de plataforma (ex.: Cloud Run com --no-allow-unauthenticated).
• Mantenha DATAGOV_API_KEY em .env / gerenciador de segredos — nunca o envie para o repositório.

Licença

MIT