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
• Una API key de OpenAI 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:

   cd mcp_project
   

2. Crea un entorno virtual (recomendado):

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

3. Instala las dependencias:

   pip install -r requirements.txt
   

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

   cp .env.example .env
   

   Edita .env y define, como mínimo:

   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:

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):

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.