Ассистент по финансам и погоде с MCP

Консольное приложение, объединяющее локальный сервер MCP с API Responses от OpenAI. Ассистент понимает запросы на естественном языке, обнаруживает инструменты, опубликованные сервером, и выполняет их для получения актуальных данных о валютах и погоде.

Проект интегрирует FastMCP, ExchangeRate-API и Open-Meteo. Также поддерживает цепочки вызовов: например, преобразует название города в координаты, а затем запрашивает текущую погоду или прогноз.

Функциональность

• Конвертация сумм между валютами по кодам ISO 4217.

• Запрос курсов обмена для базовой валюты.

• Геокодирование городов.

• Запрос текущей погоды и прогноза на 1–7 дней.

• Автоматическое обнаружение инструментов MCP клиентом.

• Интерактивный интерфейс терминала на русском языке.

• Повторные попытки при временных ошибках вызова OpenAI и обработка сетевых ошибок.

Related MCP server: Weather MCP Server

Архитектура

Usuario
  |
  v
CLI (main_client.py)
  |
  v
Cliente OpenAI Responses <----> Servidor MCP local (FastMCP)
                                      |
                                      +--> ExchangeRate-API
                                      +--> Open-Meteo

Сервер предоставляется через транспорт HTTP по адресу http://127.0.0.1:8000/mcp/ по умолчанию. Клиент подключается к этому URL, загружает пять доступных инструментов и передаёт их результаты модели для формирования окончательного ответа.

Инструменты MCP

Требования

• Python 3.10 или выше.

• Ключ API OpenAI с доступом к API Responses.

• Подключение к Интернету для обращения к OpenAI и внешним API.

• Ключ ExchangeRate-API необязателен. Без него используется открытая конечная точка.

Установка

Клонируйте репозиторий и создайте виртуальное окружение:

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

Активируйте виртуальное окружение:

# Windows PowerShell
.venv\Scripts\Activate.ps1

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

# macOS/Linux
source .venv/bin/activate

Установите зависимости:

python -m pip install -r requirements.txt

Настройка

Скопируйте пример файла конфигурации и заполните учётные данные. Файл .env является локальным и не должен включаться в репозиторий:

Copy-Item .env.example .env

В macOS или Linux:

cp .env.example .env

Полученный файл должен содержать следующие переменные:

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 необходим для использования клиента. Open-Meteo не требует учётных данных. Приложение использует тайм-аут 10 секунд для внешних HTTP-вызовов.

Использование

Сервер и клиент запускаются в отдельных терминалах. Сначала запустите сервер:

python main_server.py

В другом терминале с активированным виртуальным окружением запустите клиент:

python main_client.py

Тестирование

Модульные тесты покрывают логику валют, прогноза погоды, кодов WMO и обработку ошибок без вызова OpenAI или внешних API:

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

После этого можно вводить запросы, например:

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?

Доступные команды в CLI:

Структура проекта

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

Внешние API

• OpenAI Responses API: интерпретация запроса и выбор инструментов.

• ExchangeRate-API: курсы обмена и конвертация.

• Open-Meteo: геокодирование и метеорологические данные.

Результаты зависят от доступности, лимитов и условий использования этих сервисов. Использование OpenAI может повлечь затраты в зависимости от учётной записи и настроенной модели.