mcp_training

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

Tú › ¿Qué tiempo hace en Madrid?

Modelo:
  En Madrid hay 24,3 °C, humedad del 41 % y cielo despejado.

  · get_lat_lon_from_city → get_current_weather

Как это работает

main_client.py ──> OpenAI (Responses API) ──> [túnel] ──> main_server.py (MCP)
   tu terminal        el modelo decide                     5 herramientas
                      qué herramientas usa                 sobre APIs públicas

Клиент не выполняет инструменты: он передаёт OpenAI публичный URL сервера MCP, и именно OpenAI перечисляет их, вызывает и связывает (город → координаты → погода). Поэтому сервер должен быть доступен из интернета: OpenAI подключается со своих серверов, а не с вашей машины.

Инструменты

Погода и геокодирование используют Open-Meteo (бесплатно, без ключа). Валюты используют ExchangeRate-API, который требует ключ, и поддерживают 20 валют (/monedas в CLI).

Структура

config/settings.py     configuración y logging (todo sale del .env)
server/                herramientas + clientes HTTP de las APIs externas
client/                cliente de OpenAI + interfaz de terminal
main_server.py         arranca el servidor MCP
main_client.py         arranca la conversación

Related MCP server: Python Weather MCP Server

Установка

Требуется Python 3.11+. С uv (рекомендуется):

git clone <url-del-repo>
cd mcp_training
uv sync

Или с pip и виртуальным окружением:

python -m venv .venv
.venv\Scripts\activate        # Windows;  en Linux/macOS: source .venv/bin/activate
pip install -r requirements.txt

Конфигурация

Скопируйте пример и заполните свои ключи:

cp .env.example .env

Только две переменные обязательны:

И третья, MCP_PUBLIC_URL, которая заполняется на следующем шаге. Всё остальное (модель, порт, транспорт, таймауты, уровень логирования) имеет разумные значения по умолчанию и описано в .env.example.

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

Потребуются три терминала: сервер, туннель и клиент.

1. Запустите сервер MCP

uv run python main_server.py

Он слушает на http://127.0.0.1:8002/mcp.

2. Опубликуйте сервер через туннель

OpenAI нужен публичный URL для доступа к серверу. С devtunnel:

devtunnel port create -p 8002 --allow-anonymous
devtunnel host

Скопируйте выведенный URL (https://xxxxxxx-8002.euw.devtunnels.ms) и поместите его в .env:

MCP_PUBLIC_URL=https://xxxxxxx-8002.euw.devtunnels.ms

Подойдёт любой туннель (ngrok, Cloudflare Tunnel…); важно только, чтобы URL был доступен извне. Клиент сам добавляет /mcp, если его нет.

3. Запустите клиент

uv run python main_client.py

Введите свой запрос и нажмите Enter. Разговор сохраняет контекст: после вопроса о Мадриде можно просто сказать «а завтра?».

Convierte 100 USD a EUR
¿Cuál es el clima actual en Madrid?
Dame el pronóstico del tiempo para Nueva York

Команды CLI:

Использование сервера без клиента

Сервер — это стандартный MCP: он подходит для любого совместимого клиента. Чтобы подключить его как подпроцесс (Claude Desktop, Claude Code…), установите MCP_TRANSPORT=stdio в .env; тогда ни туннель, ни порт не понадобятся.

Частые проблемы

Чтобы увидеть детали каждого вызова (аргументы, ответы, URL), установите LOG_LEVEL=DEBUG в .env. Логи идут в stderr, так что python main_client.py > charla.txt сохранит только разговор.