Asistente de finanzas y clima con MCP

Aplicación de línea de comandos que combina un servidor local MCP 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, ExchangeRate-API y Open-Meteo. 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

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:

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

Activa el entorno virtual:

# Windows PowerShell
.venv\Scripts\Activate.ps1

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

# macOS/Linux
source .venv/bin/activate

Instala las dependencias:

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:

Copy-Item .env.example .env

En macOS o Linux:

cp .env.example .env

El archivo resultante debe contener estas variables:

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:

python main_server.py

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

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:

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

Después puedes escribir consultas como:

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

.
├── .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: interpretación de la consulta y selección de herramientas.
• ExchangeRate-API: tipos de cambio y conversiones.
• Open-Meteo: 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.