# Asistente de finanzas y clima con MCP

Aplicación de línea de comandos que combina un servidor local [MCP](https://modelcontextprotocol.io/)
con la API Responses de OpenAI. El asistente entiende consultas en lenguaje natural,
descubre las herramientas publicadas por el servidor y las ejecuta para consultar
datos actuales de divisas y meteorología.

El proyecto integra [FastMCP](https://gofastmcp.com/),
[ExchangeRate-API](https://www.exchangerate-api.com/) y
[Open-Meteo](https://open-meteo.com/). También admite llamadas encadenadas: por
ejemplo, convierte el nombre de una ciudad en coordenadas y después consulta su
clima actual o su previsión.

## Funcionalidades

- Conversión de cantidades entre monedas mediante códigos ISO 4217.
- Consulta de tipos de cambio para una moneda base.
- Geocodificación de ciudades.
- Consulta del clima actual y previsión de 1 a 7 días.
- Descubrimiento automático de herramientas MCP por parte del cliente.
- Interfaz interactiva de terminal en español.
- Reintentos ante errores temporales al llamar a OpenAI y control de errores de red.

## Arquitectura

```text
Usuario
  |
  v
CLI (main_client.py)
  |
  v
Cliente OpenAI Responses <----> Servidor MCP local (FastMCP)
                                      |
                                      +--> ExchangeRate-API
                                      +--> Open-Meteo
```

El servidor se expone mediante transporte HTTP en `http://127.0.0.1:8000/mcp/`
por defecto. El cliente se conecta a esa URL, carga las cinco herramientas
disponibles y entrega sus resultados al modelo para generar la respuesta final.

## Herramientas MCP

| Herramienta | Descripción |
| --- | --- |
| `convert_currency` | Convierte una cantidad entre dos monedas usando la tasa actual. |
| `get_exchange_rates` | Devuelve las tasas de una moneda base frente a una selección de monedas. |
| `geocode_city` | Obtiene las coordenadas, país y zona horaria de una ciudad. |
| `get_current_weather` | Consulta temperatura, sensación térmica, humedad, viento y estado meteorológico actual. |
| `get_weather_forecast` | Devuelve temperaturas, probabilidad de precipitación y estado meteorológico para los próximos días. |

## Requisitos

- Python 3.10 o superior.
- Una clave de API de OpenAI con acceso a la API Responses.
- Conexión a Internet para consultar OpenAI y las APIs externas.
- Una clave de ExchangeRate-API es opcional. Sin ella se utiliza su endpoint abierto.

## Instalación

Clona el repositorio y crea un entorno virtual:

```bash
git clone <URL_DEL_REPOSITORIO>
cd <NOMBRE_DEL_REPOSITORIO>
python -m venv .venv
```

Activa el entorno virtual:

```bash
# Windows PowerShell
.venv\Scripts\Activate.ps1

# Windows (cmd)
.venv\Scripts\activate.bat

# macOS/Linux
source .venv/bin/activate
```

Instala las dependencias:

```bash
python -m pip install -r requirements.txt
```

## Configuración

Copia el archivo de configuración de ejemplo y completa las credenciales. El
archivo `.env` es local y no debe incluirse en el repositorio:

```powershell
Copy-Item .env.example .env
```

En macOS o Linux:

```bash
cp .env.example .env
```

El archivo resultante debe contener estas variables:

```env
OPENAI_API_KEY=tu_clave_de_openai

# Opcional. Si se deja vacío se usa el endpoint abierto de ExchangeRate-API.
API_KEY_EXCHANGE=

# Opcionales.
MCP_HOST=127.0.0.1
MCP_PORT=8000
OPENAI_MODEL=gpt-4o-mini
```

`OPENAI_API_KEY` es necesaria para utilizar el cliente. Open-Meteo no requiere
credenciales. La aplicación utiliza un timeout de 10 segundos para las llamadas
HTTP externas.

## Uso

El servidor y el cliente se ejecutan en terminales independientes. Inicia primero
el servidor:

```bash
python main_server.py
```

En otra terminal, con el entorno virtual activado, inicia el cliente:

```bash
python main_client.py
```

## Pruebas

Las pruebas unitarias cubren la lógica de divisas, previsión meteorológica,
códigos WMO y saneamiento de errores sin llamar a OpenAI ni a las APIs externas:

```bash
python -m pip install -r requirements-dev.txt
python -m pytest
```

Después puedes escribir consultas como:

```text
Convierte 100 USD a EUR
¿Cuál es el clima actual en Madrid?
Dame la previsión del tiempo para Nueva York durante 5 días
¿Qué coordenadas tiene Tokio?
```

Comandos disponibles en la CLI:

| Comando | Acción |
| --- | --- |
| `/ayuda` | Muestra las herramientas y ejemplos de consulta. |
| `/monedas` | Muestra códigos de monedas habituales. |
| `/salir` | Cierra el cliente. |

## Estructura del proyecto

```text
.
├── .env.example          # Plantilla de configuración local
├── .gitignore            # Archivos excluidos del repositorio
├── client/
│   ├── cli_interface.py    # Interfaz interactiva de terminal
│   └── openai_client.py    # Orquestación OpenAI + MCP
├── config/
│   └── settings.py         # Variables de entorno y endpoints
├── server/
│   ├── api_clients.py      # Clientes HTTP para las APIs externas
│   ├── currency_tools.py   # Herramientas de divisas
│   ├── geocoding_tools.py  # Herramienta de geocodificación
│   ├── mcp_server.py       # Servidor FastMCP y registro de herramientas
│   └── weather_tools.py    # Herramientas meteorológicas
├── main_client.py          # Punto de entrada del cliente
├── main_server.py          # Punto de entrada del servidor
├── requirements.txt        # Dependencias de Python
└── README.md
```

## APIs externas

- [OpenAI Responses API](https://platform.openai.com/docs/api-reference/responses):
  interpretación de la consulta y selección de herramientas.
- [ExchangeRate-API](https://www.exchangerate-api.com/): tipos de cambio y conversiones.
- [Open-Meteo](https://open-meteo.com/): geocodificación y datos meteorológicos.

Los resultados dependen de la disponibilidad, límites y condiciones de uso de
estos servicios. El uso de OpenAI puede generar costes según la cuenta y el modelo
configurado.