# Servidor MCP de divisas y clima con cliente OpenAI Responses

Proyecto Python con un servidor MCP basado en FastMCP y un cliente CLI que usa la API Responses de OpenAI para llamar herramientas MCP de conversión de monedas, geocodificación y clima.

## Estructura

```text
├── server/
│   ├── __init__.py
│   ├── mcp_server.py
│   ├── currency_tools.py
│   ├── weather_tools.py
│   ├── geocoding_tools.py
│   └── api_clients.py
├── client/
│   ├── __init__.py
│   ├── openai_client.py
│   └── cli_interface.py
├── config/
│   ├── __init__.py
│   └── settings.py
├── main_server.py
├── main_client.py
├── requirements.txt
├── .env.example
└── README.md
```

## APIs utilizadas

- ExchangeRate-API: conversión de monedas y tasas actuales. Requiere `API_KEY_EXCHANGE`.
- Open-Meteo Forecast API: clima actual y pronóstico. No requiere API key.
- Open-Meteo Geocoding API: ciudad a coordenadas. No requiere API key.

## Herramientas MCP

1. `convert_currency(amount, from_currency, to_currency)`
2. `get_exchange_rates(base_currency, target_currencies=None)`
3. `geocode_city(city_name, count=1, language="es")`
4. `get_current_weather(latitude, longitude)`
5. `get_weather_forecast(latitude, longitude, forecast_days=5)`

## Instalación

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
```

En Windows PowerShell:

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
copy .env.example .env
```

Editar `.env` y configurar:

```env
OPENAI_API_KEY=tu_openai_api_key_aqui
API_KEY_EXCHANGE=tu_api_key_exchange_aqui
```

## Ejecución

Terminal 1:

```bash
python main_server.py
```

El servidor MCP queda disponible por defecto en:

```text
http://127.0.0.1:8000/mcp
```

Terminal 2:

```bash
python main_client.py
```

## Uso CLI

Consultas de ejemplo:

```text
Convierte 100 USD a EUR.
¿Cuál es el clima actual en Madrid?
Dame el pronóstico del tiempo para Nueva York.
¿Qué coordenadas tiene Tokio?
```

Comandos especiales:

```text
/salir
/ayuda
/monedas
```

## Flujo geocodificación → clima

Para una pregunta como:

```text
¿Cuál es el clima actual en Madrid?
```

El modelo debe llamar de forma secuencial:

1. `geocode_city("Madrid")`
2. `get_current_weather(latitude, longitude)`
3. Responder con temperatura, humedad, viento, descripción y zona horaria.

Para pronóstico:

1. `geocode_city("Nueva York")`
2. `get_weather_forecast(latitude, longitude, forecast_days=5)`
3. Responder con el resumen diario.

## Configuración principal

```env
OPENAI_MODEL=gpt-4o-mini
MCP_HOST=127.0.0.1
MCP_PORT=8000
MCP_PATH=/mcp
MCP_PUBLIC_URL=http://127.0.0.1:8000/mcp
API_TIMEOUT_SECONDS=10
API_RETRY_ATTEMPTS=3
DEFAULT_FORECAST_DAYS=5
LOG_LEVEL=INFO
```

`MCP_PUBLIC_URL` permite indicar la URL que se pasa a OpenAI Responses. Para un entorno local de evaluación se usa `http://127.0.0.1:8000/mcp`. Si se ejecuta desde un entorno donde OpenAI no pueda alcanzar `localhost`, debe usarse una URL accesible hacia el servidor MCP local.

## Manejo de errores

El proyecto valida:

- Cantidades positivas en conversiones.
- Códigos de moneda ISO de tres letras incluidos en la lista soportada.
- Nombres de ciudad no vacíos y con caracteres válidos.
- Latitud entre -90 y 90.
- Longitud entre -180 y 180.
- Pronóstico entre 1 y 16 días.

También gestiona:

- Timeouts HTTP.
- Errores de red.
- Códigos HTTP inválidos.
- Respuestas JSON inválidas.
- Errores de API de ExchangeRate-API y Open-Meteo.
- Reintentos en llamadas HTTP externas y en OpenAI Responses.

## Prueba rápida de herramientas

Con el servidor activo, iniciar el cliente y ejecutar:

```text
¿Qué coordenadas tiene Tokio?
```

Resultado esperado: el modelo llama a `geocode_city` y devuelve latitud, longitud, país y zona horaria.

Para una conversión:

```text
Convierte 100 USD a EUR.
```

Resultado esperado: el modelo llama a `convert_currency` y devuelve cantidad convertida, tasa utilizada y actualización de la API.