Metadata-Version: 2.4
Name: dataprem-mcp
Version: 0.2.0
Summary: MCP server para acceder a datos públicos españoles (Catastro, BORME, CENDOJ, Licitaciones)
License-Expression: MIT
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Description-Content-Type: text/markdown

# DataPrem MCP Server

Servidor [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) que expone fuentes de datos públicos españoles a agentes de IA (Claude Desktop, Cursor, ChatGPT, etc.).

Es un cliente ligero de la [API REST de DataPrem](https://api.dataprem.com): cada tool MCP traduce a una llamada HTTPS a `api.dataprem.com` con tu API key.

## Estado de las tools (v0.2.0)

| Tool | Estado | Fuente real | Disponible |
|------|--------|-------------|:----------:|
| `dataprem_catastro_lookup` | **Live** | Sede Electrónica del Catastro vía API DataPrem | ✅ |
| `dataprem_borme_search` | Stub | Boletín Oficial Registro Mercantil | Fase 3 (TK-481) |
| `dataprem_cendoj_search` | Stub | Centro Documentación Judicial | Fase 4 (TK-487) |
| `dataprem_tenders_search` | Stub | Plataforma Contratación Sector Público | Fase 3 (TK-482) |

Los stubs devuelven datos de demostración con flag `_status: "stub"` en la respuesta — útiles para que el LLM aprenda la forma esperada de cada tool y para mockups de UX, pero no son datos reales.

## Cómo obtener una API key

Las tools "live" requieren un token Bearer válido de `api.dataprem.com`. Mientras estamos en pre-monetización (Fase 1), se emiten manualmente:

1. Pide acceso enviando un email a `hola@dataprem.com` indicando el caso de uso (B2B integrador, B2C profesional, etc.).
2. Recibirás un token con prefijo `dpa_…` y la URL del API.
3. Configúralo en el cliente MCP (ver siguiente sección).

En Fase 2 el portal `/account` (TK-477) permitirá generar y rotar tokens en autoservicio.

## Instalación

Requiere Python 3.11+.

```bash
# Vía PyPI (recomendado para clientes MCP)
uvx dataprem-mcp

# O instalación local para desarrollo
pip install -e ".[dev]"
```

## Configuración en Claude Desktop

Edita `claude_desktop_config.json` (Mac: `~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "dataprem": {
      "command": "uvx",
      "args": ["dataprem-mcp"],
      "env": {
        "DATAPREM_API_KEY": "dpa_TU_TOKEN_AQUI",
        "DATAPREM_API_URL": "https://api.dataprem.com"
      }
    }
  }
}
```

Reinicia Claude Desktop. Las cuatro tools deberían aparecer disponibles para el modelo.

### Configuración alternativa (desarrollo local)

```json
{
  "mcpServers": {
    "dataprem-dev": {
      "command": "python",
      "args": ["-m", "dataprem_mcp"],
      "cwd": "/ruta/a/dataprem-mcp",
      "env": {
        "DATAPREM_API_KEY": "dpa_dev_token",
        "DATAPREM_API_URL": "http://dataprem-api.dataprem-api.test:81"
      }
    }
  }
}
```

## Variables de entorno

| Variable | Default | Descripción |
|----------|---------|-------------|
| `DATAPREM_API_KEY` | _(vacío)_ | Token Bearer (`dpa_…`). **Obligatorio** para tools live. |
| `DATAPREM_API_URL` | `https://api.dataprem.com` | Base URL de la API. Cambiar para apuntar a entornos de desarrollo. |

## Tools — referencia

### `dataprem_catastro_lookup` ✅ Live

Consulta datos catastrales de un inmueble. Acepta dos modos:

**Por referencia catastral:**

| Parámetro | Tipo | Descripción |
|-----------|------|-------------|
| `refcat` | string | Referencia catastral (14, 18 o 20 caracteres) |

**Por dirección:**

| Parámetro | Tipo | Obligatorio | Descripción |
|-----------|------|:-----------:|-------------|
| `address` | string | sí | Dirección literal (tipo + nombre + número) |
| `city` | string | sí | Municipio |
| `province` | string | no | Provincia |

Devuelve la ficha catastral normalizada (clase, uso, superficies, año de construcción, dirección con códigos INE, desglose de construcciones por planta y uso). **No expone titular** por LOPD/GDPR.

### `dataprem_borme_search` (stub — Fase 3)

| Parámetro | Tipo | Obligatorio |
|-----------|------|:-----------:|
| `company_name` | string | sí |
| `date_from` | string YYYY-MM-DD | no |
| `date_to` | string YYYY-MM-DD | no |

### `dataprem_cendoj_search` (stub — Fase 4)

| Parámetro | Tipo | Obligatorio |
|-----------|------|:-----------:|
| `query` | string | sí |
| `court` | string | no |
| `date_from` | string YYYY-MM-DD | no |

### `dataprem_tenders_search` (stub — Fase 3)

| Parámetro | Tipo | Obligatorio |
|-----------|------|:-----------:|
| `query` | string | sí |
| `location` | string | no |
| `status` | `"open"` \| `"closed"` \| `"all"` | no |

## Forma de la respuesta

Todas las tools devuelven `dict`. Las **live** marcan éxito o error con `ok`:

```json
{ "ok": true, "data": { ... ficha catastral ... } }

{ "ok": false, "error": "unauthorized", "message": "API key invalid or revoked..." }
```

Las **stub** marcan su naturaleza con `_status` y la ETA real:

```json
{ "_status": "stub", "_eta_phase": "Fase 3 (TK-481)", "_message": "Datos de demostración...", ...datos demo... }
```

Códigos de error de las tools live:

| `error` | Significado |
|---------|-------------|
| `missing_api_key` | `DATAPREM_API_KEY` no está en el entorno |
| `invalid_request` | Faltan parámetros obligatorios |
| `unauthorized` | Token revocado o caducado |
| `not_found` | El upstream no encontró nada |
| `validation_error` | Catastro rechazó el input (RC mal formada, vía no existe, etc.) |
| `rate_limited` | Has agotado tu cuota mensual |
| `upstream_error` | Catastro o DataPrem no disponibles temporalmente |
| `upstream_unreachable` | No se puede contactar con `DATAPREM_API_URL` |

## Desarrollo

```bash
# Instalar dependencias dev
pip install -e ".[dev]"

# Ejecutar tests
pytest

# Ejecutar el server con un API key local
DATAPREM_API_KEY=dpa_xxx DATAPREM_API_URL=http://localhost python -m dataprem_mcp
```

## Licencia

MIT
