# BDNS MCP Server

Servidor MCP (Model Context Protocol) para buscar ayudas y subvenciones públicas españolas usando la API del Sistema Nacional de Publicidad de Subvenciones y Ayudas Públicas (BDNS).

## Características

- 🔍 Búsqueda de ayudas con múltiples filtros
- 📋 Consulta de detalles completos de convocatorias
- 🆕 Listado de últimas ayudas publicadas
- 🗺️ Catálogo de regiones y tipos de beneficiario
- ⚡ Rate limiting automático (1 req/s)
- 🔄 Retry con backoff exponencial
- 🎯 Cache de regiones para búsquedas rápidas

## Instalación

### Requisitos

- Python 3.10 o superior
- pip

### Instalar desde el código fuente

```bash
# Clonar o descargar el repositorio
cd bdns-mcp

# Instalar en modo desarrollo
pip install -e .

# O instalar con dependencias de desarrollo
pip install -e ".[dev]"
```

## Configuración en Claude Desktop

Edita tu archivo de configuración de Claude Desktop:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

Añade la siguiente configuración:

```json
{
  "mcpServers": {
    "bdns": {
      "command": "python",
      "args": ["-m", "bdns_mcp.server"]
    }
  }
}
```

Si has instalado en un entorno virtual, especifica la ruta completa al Python del entorno:

```json
{
  "mcpServers": {
    "bdns": {
      "command": "/ruta/a/tu/venv/bin/python",
      "args": ["-m", "bdns_mcp.server"]
    }
  }
}
```

Reinicia Claude Desktop para aplicar los cambios.

## Herramientas Disponibles

### 1. `buscar_ayudas`

Busca convocatorias de ayudas con filtros.

**Parámetros:**
- `texto` (opcional): Texto a buscar en el título
- `tipo_busqueda` (opcional): 0=frase exacta, 1=todas las palabras, 2=alguna palabra (default: 2)
- `comunidad` (opcional): Nombre de comunidad autónoma (ej: "ARAGÓN", "CATALUÑA")
- `tipo_beneficiario` (opcional): "persona_fisica", "persona_juridica", "pyme", "autonomo", "gran_empresa"
- `tipo_administracion` (opcional): "estatal", "autonomica", "local", "otros"
- `fecha_desde` (opcional): Fecha inicio formato DD/MM/YYYY
- `fecha_hasta` (opcional): Fecha fin formato DD/MM/YYYY
- `solo_abiertas` (opcional): Solo convocatorias abiertas (default: false)
- `max_resultados` (opcional): Máximo resultados (default: 10, max: 50)

**Ejemplo de uso:**
```
Usuario: ¿Qué ayudas hay para autónomos en Aragón?
Claude: [usa buscar_ayudas con tipo_beneficiario="autonomo" y comunidad="ARAGÓN"]
```

### 2. `detalle_ayuda`

Obtiene información completa de una convocatoria.

**Parámetros:**
- `codigo_bdns` (requerido): Código BDNS de la convocatoria

**Ejemplo:**
```
Usuario: Dame más detalles de la ayuda 789012
Claude: [usa detalle_ayuda con codigo_bdns="789012"]
```

### 3. `ultimas_ayudas`

Lista las últimas convocatorias publicadas.

**Parámetros:**
- `comunidad` (opcional): Filtrar por comunidad autónoma
- `max_resultados` (opcional): Máximo resultados (default: 10, max: 20)

### 4. `listar_regiones`

Devuelve el catálogo completo de regiones disponibles.

### 5. `listar_tipos_beneficiario`

Devuelve los tipos de beneficiario disponibles.

## Ejemplos de Uso

### Búsqueda simple

```
Usuario: Busca ayudas para digitalización

Claude usa: buscar_ayudas(texto="digitalización")
```

### Búsqueda con filtros

```
Usuario: Ayudas para pymes en Cataluña con plazo abierto

Claude usa: buscar_ayudas(
    tipo_beneficiario="pyme",
    comunidad="CATALUÑA",
    solo_abiertas=true
)
```

### Consultar detalles

```
Usuario: Dame detalles de la convocatoria 654321

Claude usa: detalle_ayuda(codigo_bdns="654321")
```

### Últimas ayudas

```
Usuario: ¿Cuáles son las últimas ayudas publicadas en Madrid?

Claude usa: ultimas_ayudas(comunidad="MADRID")
```

## Tipos de Beneficiario

- **persona_fisica**: Personas físicas que no desarrollan actividad económica
- **persona_juridica**: Personas jurídicas que no desarrollan actividad económica
- **pyme**: PYME y personas físicas que desarrollan actividad económica (incluye autónomos)
- **autonomo**: Alias para "pyme"
- **gran_empresa**: Gran empresa
- **sin_especificar**: Sin información específica

## Tipos de Administración

- **estatal**: Administración del Estado
- **autonomica**: Comunidad Autónoma
- **local**: Entidad Local
- **otros**: Otros órganos

## API de Referencia

Este servidor utiliza la API pública del BDNS:
- **Base URL**: `https://www.infosubvenciones.es/bdnstrans/api`
- **Documentación**: `https://www.infosubvenciones.es/bdnstrans/doc/swagger`

## Desarrollo

### Ejecutar tests

```bash
pytest tests/
```

### Estructura del Proyecto

```
bdns-mcp/
├── pyproject.toml
├── README.md
├── ESPECIFICACION.md
├── src/
│   └── bdns_mcp/
│       ├── __init__.py
│       ├── server.py          # MCP server principal
│       ├── api_client.py      # Cliente HTTP para BDNS
│       ├── models.py          # Modelos Pydantic
│       └── catalogos.py       # Mapeos y catálogos
└── tests/
    └── test_api.py
```

## Limitaciones y Consideraciones

- La API pública del BDNS no requiere autenticación
- Rate limiting implementado: 1 petición por segundo
- Retry automático con backoff exponencial en caso de errores
- Cache de regiones para optimizar búsquedas
- Encoding UTF-8 para manejar caracteres especiales

## Licencia

MIT

## Contribuir

Las contribuciones son bienvenidas. Por favor, abre un issue o pull request.

## Soporte

Para problemas o preguntas, abre un issue en el repositorio.