# Asistente de Monedas y Clima — Servidor MCP + Cliente OpenAI

Proyecto que expone un servidor **MCP** (Model Context Protocol) con 5
herramientas que integran dos APIs públicas — **ExchangeRate-API**
(conversión de monedas) y **Open-Meteo** (geocodificación y clima) — y
un cliente que usa la **API Responses de OpenAI** con soporte nativo
para herramientas MCP remotas, expuesto a través de una interfaz de
línea de comandos (CLI) en lenguaje natural.

## Arquitectura

```
Usuario (CLI) → Cliente OpenAI (Responses API) → Servidor MCP local → APIs externas
                                                    (ExchangeRate-API, Open-Meteo)
```

El modelo decide qué herramientas llamar y en qué orden. Para
preguntas de clima, sigue este flujo:

1. `geocode_city("Madrid")` → obtiene latitud/longitud
2. `get_current_weather(lat, lon)` → obtiene el clima actual
3. El modelo redacta la respuesta final combinando ambos resultados

## Estructura del proyecto

```
├── server/
│   ├── mcp_server.py           # Servidor MCP con las 5 herramientas (FastMCP)
│   ├── currency_tools.py       # Lógica de conversión de monedas
│   ├── weather_tools.py        # Lógica de clima actual y pronóstico
│   ├── geocoding_tools.py      # Lógica de geocodificación
│   └── api_clients.py          # Clientes HTTP de bajo nivel para las APIs
├── client/
│   ├── openai_client.py        # Cliente OpenAI (Responses API + MCP remoto)
│   └── cli_interface.py        # Interfaz de línea de comandos
├── config/
│   └── settings.py             # Configuración centralizada (.env)
├── main_server.py               # Punto de entrada del servidor
├── main_client.py                # Punto de entrada del cliente
├── requirements.txt
├── .env.example
└── README.md
```

## Herramientas del servidor MCP

| Herramienta | API | Descripción |
|---|---|---|
| `convert_currency(amount, from_currency, to_currency)` | ExchangeRate-API | Convierte una cantidad entre dos divisas |
| `get_exchange_rates(base_currency, symbols?)` | ExchangeRate-API | Tasas de cambio de una moneda base frente a varias monedas |
| `geocode_city(city_name)` | Open-Meteo | Nombre de ciudad → coordenadas, país y zona horaria |
| `get_current_weather(latitude, longitude)` | Open-Meteo | Clima actual (temperatura, humedad, viento, descripción) |
| `get_weather_forecast(latitude, longitude, days?)` | Open-Meteo | Pronóstico de 1 a 16 días |

## Requisitos previos

- Python 3.10 o superior
- Una API key gratuita de [ExchangeRate-API](https://www.exchangerate-api.com/)
- Una API key de [OpenAI](https://platform.openai.com/) con acceso a un
  modelo compatible con Responses API + MCP remoto (`gpt-4.1`, `gpt-4o`,
  `gpt-5` o similar)
- Open-Meteo **no** requiere API key

## Instalación

1. Clona o descarga este proyecto y entra en la carpeta:

   ```bash
   cd mcp_project
   ```

2. Crea un entorno virtual (recomendado):

   ```bash
   python3 -m venv venv
   source venv/bin/activate   # En Windows: venv\Scripts\activate
   ```

3. Instala las dependencias:

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

4. Copia el fichero de variables de entorno y complétalo con tus claves:

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

   Edita `.env` y define, como mínimo:

   ```env
   API_KEY_EXCHANGE=tu_api_key_de_exchangerate
   OPENAI_API_KEY=tu_api_key_de_openai
   ```

## Uso

### 1. Arrancar el servidor MCP

En una terminal:

```bash
python main_server.py
```

Por defecto el servidor escucha en `http://127.0.0.1:8000/mcp`. Verás
un mensaje de log confirmando el arranque y las herramientas
registradas.

### 2. Arrancar el cliente CLI

En **otra** terminal (con el mismo entorno virtual activado):

```bash
python main_client.py
```

Aparecerá un menú de bienvenida. Ejemplos de preguntas que puedes
escribir directamente en lenguaje natural:

```
Tú: Convierte 100 USD a EUR
Tú: ¿Cuál es el clima actual en Madrid?
Tú: Dame el pronóstico del tiempo para Nueva York
Tú: ¿Qué coordenadas tiene Tokio?
Tú: Dame las tasas de cambio del USD frente a EUR, GBP y JPY
```

### Comandos especiales

| Comando | Acción |
|---|---|
| `/ayuda` | Muestra las herramientas disponibles y ejemplos de uso |
| `/monedas` | Lista códigos de moneda comunes soportados |
| `/salir` | Cierra el programa |

## Configuración avanzada

Todas las variables se leen desde `.env` (ver `.env.example`):

| Variable | Descripción | Valor por defecto |
|---|---|---|
| `MCP_HOST` | Host del servidor MCP | `127.0.0.1` |
| `MCP_PORT` | Puerto del servidor MCP | `8000` |
| `MCP_TRANSPORT` | Transporte MCP (`streamable-http`, `sse`, `stdio`) | `streamable-http` |
| `LOG_LEVEL` | Nivel de logging | `INFO` |
| `API_KEY_EXCHANGE` | API key de ExchangeRate-API | *(obligatoria)* |
| `BASE_URL_EXCHANGE` | URL base de ExchangeRate-API | `https://v6.exchangerate-api.com/v6` |
| `BASE_URL_WEATHER` | URL base de Open-Meteo (clima) | `https://api.open-meteo.com/v1` |
| `BASE_URL_GEOCODING` | URL base de Open-Meteo (geocodificación) | `https://geocoding-api.open-meteo.com/v1` |
| `OPENAI_API_KEY` | API key de OpenAI | *(obligatoria)* |
| `OPENAI_MODEL` | Modelo de OpenAI a usar | `gpt-4.1` |
| `HTTP_TIMEOUT_SECONDS` | Timeout de peticiones HTTP | `10` |
| `MAX_RETRIES` | Reintentos ante fallos de conectividad | `3` |

## Manejo de errores

- **Servidor MCP**: cada herramienta valida sus parámetros de entrada
  (montos negativos, códigos de moneda inválidos, coordenadas fuera de
  rango, ciudades vacías) y captura errores de red, timeouts y códigos
  de estado HTTP de las APIs externas, devolviendo un mensaje de error
  claro en lugar de propagar una excepción sin control.
- **Cliente OpenAI**: implementa reintentos con backoff exponencial
  ante errores de conectividad (`APIConnectionError`, `APITimeoutError`)
  y límites de uso (`RateLimitError`), y reporta errores irrecuperables
  de forma clara en la CLI.
- **CLI**: captura ciudades no encontradas, entradas vacías e
  interrupciones de teclado (`Ctrl+C`) sin cerrar el programa
  abruptamente.

## Notas

- Open-Meteo es completamente gratuita y no requiere autenticación.
- ExchangeRate-API requiere una API key gratuita (plan "Free") que
  puedes obtener en su web.
- El servidor debe estar corriendo **antes** de iniciar el cliente.