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

├── 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

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

En Windows PowerShell:

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

Editar .env y configurar:

OPENAI_API_KEY=tu_openai_api_key_aqui
API_KEY_EXCHANGE=tu_api_key_exchange_aqui

Ejecución

Terminal 1:

python main_server.py

El servidor MCP queda disponible por defecto en:

http://127.0.0.1:8000/mcp

Terminal 2:

python main_client.py

Uso CLI

Consultas de ejemplo:

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:

/salir
/ayuda
/monedas

Flujo geocodificación → clima

Para una pregunta como:

¿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

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:

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

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.