uruguay-mcp 0.1.0__tar.gz

uruguay_mcp-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+
+# uv
+.uv/
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.pyright/
+
+# Local data / cache
+*.sqlite
+*.db
+.cache/
+
+# Editors / OS
+.DS_Store
+.idea/
+.vscode/

uruguay_mcp-0.1.0/EXAMPLES.md

@@ -0,0 +1,282 @@
+# Ejemplos de uso de uruguay_mcp
+
+`uruguay_mcp` expone solo **5 meta-herramientas**. Todo dato concreto se alcanza a
+través de ellas: primero `discover_tools` (o `plan_query`) para encontrar la
+herramienta adecuada y su esquema, luego `call_tool` para ejecutarla, o
+`execute_batch` para correr varias en paralelo.
+
+Meta-tools:
+
+- `list_modules()` — módulos disponibles y cuántas tools ofrece cada uno.
+- `discover_tools(query, module=None, limit=8)` — busca tools por necesidad.
+- `plan_query(goal)` — candidatos de varias fuentes para un objetivo amplio.
+- `call_tool(name, arguments)` — ejecuta una tool por nombre.
+- `execute_batch(calls)` — ejecuta `[{name, arguments}, ...]` en paralelo.
+
+Módulos cargados por defecto: `catalogodatos`, `bcu`, `ine`, `gubuy`,
+`montevideo`, `datastore` (31 data tools). Los nombres de tools usados abajo son
+los reales registrados en cada módulo.
+
+---
+
+## 1. Cotización del dólar (BCU)
+
+**Objetivo:** ¿A cuánto cerró el dólar en el último día hábil?
+
+```text
+discover_tools(query="cotización del dólar BCU", module="bcu")
+  -> sugiere bcu_cotizacion_usd
+
+call_tool("bcu_cotizacion_usd", {})
+```
+
+Sin `fecha`, usa el último cierre. Devuelve `compra` (TCC) y `venta` (TCV) del
+dólar billete (moneda 2225) envueltos en el sobre estándar (`data`, `api`,
+`url`, `cached`).
+
+---
+
+## 2. Serie de tipos de cambio en un rango (BCU)
+
+**Objetivo:** Tipo de cambio del dólar y el real entre dos fechas.
+
+```text
+call_tool("bcu_listar_monedas", {"grupo": 2})
+  -> tomar los códigos (ej. 2225 = dólar billete, 1001 = real)
+
+call_tool("bcu_cotizaciones", {
+  "monedas": [2225, 1001],
+  "fecha_desde": "2025-01-02",
+  "fecha_hasta": "2025-01-31",
+  "grupo": 2
+})
+```
+
+Primero `bcu_listar_monedas` para conocer los códigos numéricos, luego
+`bcu_cotizaciones` con el rango. Devuelve una fila por moneda y fecha con
+`compra`/`venta`/`arbitraje`.
+
+---
+
+## 3. Buscar y abrir un dataset del catálogo nacional (catalogodatos)
+
+**Objetivo:** Encontrar datos abiertos sobre presupuesto público.
+
+```text
+discover_tools(query="datasets de presupuesto datos abiertos")
+  -> catalogo_search_datasets
+
+call_tool("catalogo_search_datasets", {"query": "presupuesto", "rows": 10})
+  -> elegir un dataset y tomar su 'name'/'id'
+
+call_tool("catalogo_get_dataset", {"id": "presupuesto-nacional"})
+```
+
+`catalogo_get_dataset` devuelve los `resources`; quedate con el `resource_id`
+de uno que tenga datastore activo para el ejemplo 4.
+
+---
+
+## 4. Consultar registros tabulares de un recurso CKAN (catalogodatos)
+
+**Objetivo:** Leer filas de un recurso con datastore, filtrando por texto.
+
+```text
+call_tool("catalogo_query_datastore", {
+  "resource_id": "a1b2c3d4-0000-1111-2222-333344445555",
+  "query": "Montevideo",
+  "limit": 50,
+  "offset": 0
+})
+```
+
+`resource_id` sale del paso 3 (`catalogo_get_dataset`). Solo funciona sobre
+recursos con datastore activo; si no lo tienen, descargá el archivo desde su
+`url`.
+
+---
+
+## 5. Estudios estadísticos del INE (INE / ANDA)
+
+**Objetivo:** Hallar el estudio del censo y abrir su ficha.
+
+```text
+discover_tools(query="censo de población INE", module="ine")
+  -> ine_search_studies
+
+call_tool("ine_search_studies", {
+  "query": "censo", "rows": 10, "sort_by": "year", "sort_order": "desc"
+})
+  -> copiar el 'idno' ANDA (NO el id numérico)
+
+call_tool("ine_get_study", {"idno": "URY-INE-CENSO-2023-v01"})
+```
+
+Ojo: `ine_get_study` requiere el `idno` (cadena ANDA), no el id numérico que
+aparece en la búsqueda.
+
+---
+
+## 6. Datasets CKAN del INE
+
+**Objetivo:** Listar los datasets de datos abiertos publicados por el INE.
+
+```text
+call_tool("ine_list_ckan_datasets", {"query": "precios", "rows": 20})
+```
+
+Devuelve los datasets CKAN del INE (complementa a los estudios ANDA del
+ejemplo 5). Para leer las filas de uno de sus recursos, seguí con
+`catalogo_query_datastore` usando el `resource_id` correspondiente.
+
+---
+
+## 7. Servicios y APIs de gub.uy (gubuy)
+
+**Objetivo:** Ver qué servicios/APIs de gobierno existen sobre transporte.
+
+```text
+discover_tools(query="APIs de gobierno transporte gub.uy", module="gubuy")
+  -> gubuy_search_apis, gubuy_list_servicios
+
+execute_batch([
+  {"name": "gubuy_search_apis",    "arguments": {"query": "transporte", "rows": 10}},
+  {"name": "gubuy_list_servicios", "arguments": {"query": "transporte", "limit": 10}}
+])
+```
+
+`execute_batch` corre ambas en paralelo con aislamiento de errores. Tomá un
+`id`/`showcase_id` y profundizá con `gubuy_get_servicio` o
+`gubuy_servicio_datasets`.
+
+---
+
+## 8. Próximo ómnibus en una parada (montevideo, transporte)
+
+**Objetivo:** ¿Cuándo llega el 103 a una parada?
+
+```text
+discover_tools(query="cuándo llega el próximo bus a una parada", module="montevideo")
+  -> montevideo_list_busstops, montevideo_busstop_lines, montevideo_bus_eta
+
+call_tool("montevideo_list_busstops", {"query": "18 de Julio", "limit": 20})
+  -> tomar el busstop_id
+
+call_tool("montevideo_busstop_lines", {"busstop_id": 4567})
+  -> confirmar qué líneas pasan
+
+call_tool("montevideo_bus_eta", {"busstop_id": 4567, "lines": ["103"], "amount_per_line": 2})
+```
+
+`montevideo_bus_eta` exige `busstop_id` y al menos una línea. La unidad de
+`eta` no está documentada (segundos o minutos): se devuelve sin transformar.
+
+---
+
+## 9. Buses cerca de un punto en tiempo real (montevideo, transporte)
+
+**Objetivo:** Ver buses circulando cerca de una ubicación.
+
+```text
+call_tool("montevideo_buses_near", {
+  "lat": -34.9011, "lng": -56.1645, "radius_m": 500
+})
+```
+
+Devuelve posiciones GPS en tiempo real dentro del radio. Alternativa filtrada:
+`montevideo_bus_positions` por `lines`, `company` o `busstop_id`.
+
+---
+
+## 10. CRUZADO — Transporte + multas de tránsito de Montevideo
+
+**Objetivo:** Para un punto del centro, mostrar qué buses pasan cerca y, de
+paso, el panorama de multas de tránsito (SUCIVE) de ese año.
+
+```text
+discover_tools(query="buses cerca y multas de tránsito Montevideo", module="montevideo")
+  -> montevideo_buses_near, montevideo_multas_transito
+
+execute_batch([
+  {"name": "montevideo_buses_near",
+   "arguments": {"lat": -34.9061, "lng": -56.1914, "radius_m": 400}},
+  {"name": "montevideo_multas_transito",
+   "arguments": {"year": 2018}}
+])
+```
+
+Dos fuentes distintas dentro del mismo módulo, resueltas en paralelo:
+tiempo real de transporte + el índice estadístico de multas. `multas_transito`
+devuelve archivos anuales descargables y tablas de referencia (ordenanzas,
+tipos de vehículo): son datos AGREGADOS, no una consulta de deuda por
+matrícula.
+
+---
+
+## 11. CRUZADO — BCU + dataset del catálogo (tipo de cambio para contextualizar)
+
+**Objetivo:** Cruzar la cotización oficial del dólar con un dataset de precios
+o presupuesto del catálogo nacional para análisis monetario.
+
+```text
+plan_query(goal="contextualizar precios en pesos con el tipo de cambio del dólar")
+  -> candidatos: bcu_cotizacion_usd, catalogo_search_datasets, catalogo_query_datastore
+
+execute_batch([
+  {"name": "bcu_cotizacion_usd",      "arguments": {}},
+  {"name": "catalogo_search_datasets","arguments": {"query": "índice de precios", "rows": 5}}
+])
+  -> con un resource_id del resultado del catálogo:
+
+call_tool("catalogo_query_datastore", {
+  "resource_id": "ipc-0000-1111-2222-333344445555",
+  "limit": 100
+})
+```
+
+`plan_query` propone tools de **dos módulos** (`bcu` + `catalogodatos`). Se trae
+el dólar y el dataset en paralelo con `execute_batch`, y luego se leen las filas
+del recurso para convertir/contextualizar montos.
+
+---
+
+## 12. CRUZADO — Dos tablas CKAN para un JOIN lógico
+
+**Objetivo:** Combinar dos recursos CKAN (uno del catálogo nacional, otro del
+portal de Montevideo) para relacionar registros — un JOIN hecho del lado del
+cliente con los resultados de dos datastores.
+
+```text
+discover_tools(query="consultar registros de un recurso CKAN", limit=8)
+  -> catalogo_query_datastore, montevideo_query_datastore
+
+# Tabla A: recurso del catálogo nacional
+call_tool("catalogo_query_datastore", {
+  "resource_id": "padron-organismos-0000-1111-2222-3333",
+  "limit": 500
+})
+
+# Tabla B: recurso del portal de Montevideo
+call_tool("montevideo_query_datastore", {
+  "resource_id": "arbolado-publico-aaaa-bbbb-cccc-dddd",
+  "limit": 500
+})
+```
+
+Cada `*_query_datastore` devuelve registros de su portal CKAN respectivo;
+el JOIN (por una clave común, ej. `organismo` o `barrio`) se arma combinando
+los dos resultados. Para empujar el JOIN a un motor SQL real usá el módulo
+`datastore` (cargado por defecto): `datastore_load_ckan_resource` para subir
+cada recurso a una tabla SQLite y `datastore_sql` para el JOIN con SELECT.
+
+---
+
+## Notas
+
+- Toda respuesta de data tool viene en el sobre estándar: `data`, `api`, `url`,
+  `cached` (y `error` ante fallos).
+- `discover_tools` devuelve el esquema de argumentos de cada candidato: leelo
+  antes de armar el `arguments` de `call_tool`.
+- `execute_batch` aísla errores por llamada: una falla no aborta el resto.
+- Los `resource_id` y `busstop_id` de los ejemplos son ilustrativos; obtenelos
+  siempre del paso de búsqueda/listado previo.

uruguay_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 uruguay-mcp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

uruguay_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: uruguay-mcp
+Version: 0.1.0
+Summary: MCP server for Uruguay's open government data (national catalog, BCU, INE, Montevideo, gub.uy)
+Author: uruguay-mcp contributors
+License: MIT
+License-File: LICENSE
+Keywords: bcu,ckan,ine,mcp,montevideo,open-data,uruguay
+Requires-Python: >=3.11
+Requires-Dist: aiocache>=0.12
+Requires-Dist: fastmcp>=2.3.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic-settings>=2.3
+Requires-Dist: pydantic>=2.7
+Requires-Dist: structlog>=24.1
+Requires-Dist: tenacity>=8.3
+Requires-Dist: zeep>=4.2
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<img src="https://flagcdn.com/w160/uy.png" alt="Bandera de Uruguay" width="120" />
+
+# 🇺🇾 uruguay-mcp
+
+**Structured AI-agent access to Uruguay's open government data**
+<br>
+*Acceso estructurado de agentes de IA a los datos abiertos del Estado uruguayo*
+
+[![PyPI](https://img.shields.io/pypi/v/uruguay-mcp?color=blue&label=PyPI)](https://pypi.org/project/uruguay-mcp/)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
+[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-7C3AED)](https://modelcontextprotocol.io/)
+[![Tests](https://img.shields.io/badge/tests-69%20passing-brightgreen)](#development)
+[![Coverage](https://img.shields.io/badge/coverage-86%25-brightgreen)](#development)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+🌎 **[Español](README.es.md)** · **English**
+
+</div>
+
+---
+
+An [MCP](https://modelcontextprotocol.io/) server that gives AI agents structured
+access to **Uruguay's open government data** — the national data catalog, the
+Central Bank, the statistics institute, Montevideo's city data & realtime
+transport, and the gub.uy service catalog — behind a single **meta-discovery**
+layer.
+
+## ✨ Why a meta-discovery layer?
+
+Instead of flooding the model with hundreds of tool definitions, the server
+exposes **five meta-tools**. The model searches for what it needs, then invokes
+the matching data tool by name. The prompt-visible surface stays constant no
+matter how many data sources are added.
+
+| Meta-tool | Purpose |
+|---|---|
+| `discover_tools(query, module?, limit?)` | Rank data tools relevant to a natural-language need (returns their argument schemas) |
+| `call_tool(name, arguments)` | Invoke a data tool by name (validates arguments) |
+| `list_modules()` | List data-source modules and their tool counts |
+| `plan_query(goal)` | Surface candidate tools for a multi-step goal |
+| `execute_batch(calls)` | Run several calls concurrently with per-call error isolation |
+
+Every tool returns a unified envelope: `{ "_meta": { source, cached, lang, timestamp }, "data": ... }`.
+
+> At a glance: **5 meta-tools + 31 data tools across 6 modules**, plus **17
+> prompts** and **11 resources**.
+
+## 📚 Data sources (modules)
+
+| | Module | Source | Protocol | Tools |
+|---|---|---|---|:--:|
+| 🏛️ | `catalogodatos` | [catalogodatos.gub.uy](https://catalogodatos.gub.uy) — national CKAN catalog (~2680 datasets, 72 orgs) | CKAN REST | 5 |
+| 💵 | `bcu` | Banco Central del Uruguay — exchange rates | SOAP (`zeep`) | 4 |
+| 📊 | `ine` | Instituto Nacional de Estadística — ANDA / microdata | REST | 3 |
+| 🌐 | `gubuy` | gub.uy public API / service catalog | CKAN REST | 4 |
+| 🚌 | `montevideo` | Intendencia de Montevideo — city CKAN + realtime transport | CKAN + REST | 11 |
+| 🗄️ | `datastore` | Cross-source SQLite workspace — load CSV/CKAN data, run read-only SQL JOINs | local SQLite | 4 |
+
+The transport surface of `montevideo` needs OAuth2 credentials
+(`URUGUAY_MCP_MVD_CLIENT_ID` / `URUGUAY_MCP_MVD_CLIENT_SECRET`); without them the
+transport tools return a typed `validation_error` while the CKAN tools work
+unauthenticated.
+
+## 🧩 Prompts & Resources
+
+Each module also registers reusable **prompts** (parameterized Spanish
+instruction templates) and **resources** (static reference docs under the
+`uru://<module>/<path>` URI scheme), exposed natively through FastMCP.
+
+- **17 prompts** — e.g. `bcu_cotizacion_dolar_hoy`, `catalogo_buscar_por_tema`,
+  `ine_buscar_estudios`, `montevideo_proximo_bus`, `datastore_unir_dos_fuentes`.
+- **11 resources** — e.g. `uru://bcu/codigos-moneda`,
+  `uru://catalogodatos/guia-de-uso`, `uru://montevideo/credenciales-transporte`.
+
+See **[EXAMPLES.md](EXAMPLES.md)** for end-to-end usage scenarios, including
+cross-source ones via `plan_query` / `execute_batch` and SQL JOINs through the
+`datastore` module.
+
+## 🚀 Quick start
+
+```bash
+# Run directly from PyPI (once published)
+uvx uruguay-mcp
+
+# …or install it
+pip install uruguay-mcp        # or: uv pip install uruguay-mcp
+uruguay-mcp
+```
+
+### One-command install into Claude
+
+```bash
+uruguay-mcp install
+```
+
+Merges the server into Claude Desktop's config (preserving existing
+`mcpServers` and unrelated keys) and prints a ready-to-paste snippet for Claude
+Code / Cursor. Restart the client afterwards.
+
+### Claude Desktop config (manual)
+
+```json
+{
+  "mcpServers": {
+    "uruguay-mcp": { "command": "uruguay-mcp" }
+  }
+}
+```
+
+### Run options
+
+```bash
+uruguay-mcp                          # stdio (default)
+uruguay-mcp --transport sse --port 8000
+uruguay-mcp --modules catalogodatos,bcu   # load only some modules
+uruguay-mcp --verbose                # INFO logs   (--debug for DEBUG)
+```
+
+## ⚙️ Configuration
+
+All via `URUGUAY_MCP_*` environment variables:
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `URUGUAY_MCP_LANG` | `es` | Language for human-facing strings (`es`/`en`) |
+| `URUGUAY_MCP_HTTP_TIMEOUT` | `30` | HTTP timeout (seconds) |
+| `URUGUAY_MCP_CACHE_TTL` | `900` | Response cache TTL (seconds) |
+| `URUGUAY_MCP_RATE_LIMIT_RPS` | `5` | Max requests/sec per host |
+| `URUGUAY_MCP_MODULES` | _(all)_ | Comma-separated module allowlist |
+| `URUGUAY_MCP_MVD_CLIENT_ID` | _(unset)_ | OAuth2 client id for the Montevideo transport API |
+| `URUGUAY_MCP_MVD_CLIENT_SECRET` | _(unset)_ | OAuth2 client secret for the Montevideo transport API |
+
+## 🏗️ Architecture
+
+```
+src/uruguay_mcp/
+├── server.py            # FastMCP wiring; meta-tools + registered prompts + resources
+├── cli.py               # `uruguay-mcp` / `uruguay-mcp install`; -v/--debug logging
+├── meta/                # discovery layer
+│   ├── tools.py         # the 5 meta-tools
+│   └── search.py        # BM25-lite ranking over the registry
+├── shared/              # reused by every module
+│   ├── config.py        # env-driven settings (URUGUAY_MCP_*)
+│   ├── http.py          # async client: retries (tenacity) + per-host rate limit
+│   ├── cache.py         # async TTL cache
+│   ├── envelope.py      # unified {_meta, data} response (+ UTC timestamp)
+│   ├── i18n.py          # es/en messages
+│   ├── errors.py        # typed, localized errors
+│   └── registry.py      # tool/prompt/resource registry; @tool/@prompt/@resource
+└── modules/             # one self-contained package per data source
+    ├── catalogodatos/   ├── bcu/      ├── ine/
+    ├── gubuy/           ├── montevideo/   └── datastore/
+```
+
+Each module package is independent (`constants` · `schemas` · `client` ·
+`tools` · optional `prompts`/`resources`). Importing the package self-registers
+everything it offers.
+
+## 🛠️ Development
+
+```bash
+uv venv && uv pip install -e ".[dev]"
+
+uv run pytest                  # 69 unit tests (HTTP mocked, offline) · 86% coverage
+uv run pytest -m integration   # hits live government APIs
+uv run ruff check src tests
+uv run pyright
+```
+
+## 🙌 Acknowledgements
+
+Built on data published by **AGESIC**, **BCU**, **INE** and the **Intendencia de
+Montevideo** under Uruguay's open-data law (Nº 18.381). This project is an
+independent client and is not affiliated with those institutions.
+
+## 📄 License
+
+[MIT](LICENSE)