GovData MCP

GovData MCP

Un servidor de Model Context Protocol (MCP) que permite a los agentes de IA buscar, explorar y obtener conjuntos de datos abiertos de portales oficiales de datos gubernamentales. Una interfaz de herramientas unificada para Estados Unidos, Reino Unido, Canadá y Australia — con las particularidades de cada portal (migraciones de API, muros de autenticación, metadatos bilingües, indicadores DataStore obsoletos) absorbidas detrás de una capa de adaptadores común.

Diseñado para el flujo de trabajo típico de un agente: "¿Existe un conjunto de datos gubernamental para X?" → encontrar candidatos → inspeccionar los archivos → previsualizar filas u obtener un enlace de descarga y continuar.

Características principales

• Cuatro portales nacionales, una interfaz. EE. UU. (data.gov v4 / DCAT), Reino Unido (data.gov.uk / CKAN), Canadá (open.canada.ca / CKAN), Australia (data.gov.au / CKAN + DataStore).
• Económico en tokens por diseño. Las descripciones se limpian de HTML y se truncan, los resultados de búsqueda son resúmenes compactos y los archivos grandes nunca se incluyen en línea por accidente.
• Vista previa a nivel de fila. Utiliza CKAN DataStore cuando está disponible (Australia) y recurre de forma transparente a leer el inicio de archivos CSV/TSV en todos los demás casos.
• Modos de fallo aptos para agentes. Los errores se devuelven como texto accionable ("use get_download_link en su lugar", "reintente con dataset_id", "portales disponibles: …") — nunca rastreos de errores en bruto.
• Registro extensible. Añadir otro portal basado en CKAN es una única entrada de configuración; los portales que no usan CKAN se conectan mediante una pequeña clase adaptadora.
• Doble transporte. stdio para clientes locales (Claude Desktop, etc.), streamable-http sin estado para despliegue serverless (Google Cloud Run).

Portales compatibles

Requisitos

• Python 3.11+
• Una clave API de api.data.gov para el portal de EE. UU. (gratuita; los demás portales no necesitan credenciales)

Instalación

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 a .env y establezca su clave:

DATAGOV_API_KEY=your-api-data-gov-key

Primeros pasos

Configuración estándar para la mayoría de los 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"
    }
  }
}

Herramientas

El flujo de agente previsto: list_portals → search_datasets → get_dataset → preview_resource / fetch_resource / get_download_link.

Configuración

Todos los ajustes son variables de entorno (o un archivo .env local):

Docker

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

La imagen ejecuta el transporte HTTP en modo sin estado y está lista para plataformas serverless (script de despliegue en Google Cloud Run incluido en deploy/).

Desarrollo

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

La suite en vivo (pytest -m live) verifica la cadena completa de búsqueda → exploración → previsualización → obtención por país, más el comportamiento específico de cada portal (normalización bilingüe de Canadá, búsqueda de recursos con ámbito de conjunto de datos en el Reino Unido, rutas DataStore de Australia). Ejecútela antes de desplegar — los portales gubernamentales cambian sin previo aviso.

Arquitectura

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

Añadir un portal: para un portal CKAN estándar, añada una entrada Portal(...) a portals/registry.py — listo. Para portales con particularidades, cree una subclase de PortalAdapter y sobrescriba los enganches específicos (normalize_dataset, build_search_params) o, para APIs que no usan CKAN, los propios métodos de operación (consulte us.py para un adaptador personalizado completo).

TODO / Hoja de ruta

• 🇨🇳 Soporte del portal de China — no existe una API nacional unificada de datos abiertos; previsto como adaptador personalizado dirigido a los datos de la Oficina Nacional de Estadísticas (mediante un paquete de estadísticas existente) con degradación gradual.
• 🇯🇵 Soporte del portal de Japón — e-Gov Data Portal (data.e-gov.go.jp) es compatible con CKAN y debería encajar en el registro existente; la API de estadísticas e-Stat más rica (autenticación con app-ID, metadatos en japonés) está prevista como adaptador dedicado.
• Suite de pruebas unitarias sin conexión con fixtures de portal grabados (respx) para CI
• Tutorial de despliegue en Google Cloud Run (el servicio está listo para contenedores; script en deploy/)
• Filtros de búsqueda de editor/formato v4 de EE. UU. (pendiente de documentación de la API)
• Más portales CKAN (Nueva Zelanda data.govt.nz es una adición casi gratuita)
• Detección de tipo de contenido para rescatar formatos de recurso mal etiquetados

Notas de seguridad

• Este servidor es de solo lectura hacia los portales — ninguna herramienta puede crear, modificar o eliminar nada.
• fetch_resource y preview_resource descargan desde URL contenidas en los metadatos del portal; el contenido se limita en tamaño y se verifica que no sea binario antes de devolverse al modelo, pero trate el contenido obtenido como entrada no confiable.
• El servidor en sí no tiene autenticación. Para despliegue remoto, colóquelo detrás de un proxy autenticador o autenticación a nivel de plataforma (p. ej. Cloud Run con --no-allow-unauthenticated).
• Mantenga DATAGOV_API_KEY en .env / gestor de secretos — nunca lo confirme en el repositorio.

Licencia

MIT