Weather MCP Server + Agent + Web UI
Проект уже интегрирован как единый стек:
- FastMCP сервер с MCP tools,
- FastAPI backend + встроенный минимальный frontend,
- CLI/daemon агент на openai-agents,
- storage по умолчанию в SQLite (с опциональным JSON backend).
Архитектура
src/weather_mcp/client.py— HTTP-клиент внешнего weather API.src/weather_mcp/tools.py— MCP tools (get_weather,schedule,run_scheduled_jobs,get_weather_summaryи др.).src/weather_mcp/scheduler_store.py— storage/scheduler слой (scheduled_jobs,weather_records) + JSON fallback.src/weather_agent/web.py— FastAPI endpoints + UI dashboard.src/weather_agent/daemon.py— 24/7 daemon, периодически запускающий due jobs.src/weather_agent/service.py— чат runtime для OpenAI agent + MCP.
MCP инструменты
get_weather
Вход:
- city или latitude/longitude
- units (по умолчанию metric)
Поведение:
- получает погоду через внешний API,
- нормализует ответ,
- сохраняет snapshot в storage,
- возвращает JSON:```json
{
"location": "Warsaw, Mazowieckie, Poland",
"temperature": 12.3,
"feels_like": 10.8,
"humidity": 81,
"wind_speed": 4.2,
"condition": "пасмурно",
"source": "open-meteo",
"collected_at": "2026-03-12T10:00:00+00:00",
"units": "metric"
}
### `schedule`
Вход:
- `target` (`get_weather`)
- `params` (аргументы для `get_weather`)
- `mode`: `once` · `interval` · `cron`
- `run_at` (для `once`)
- `every_seconds` или `every` (для `interval`)
- поддерживаются секунды и минуты: `300`, `90s`, `5m`, `2 минуты`
- `cron` (для `cron`)
- `enabled`
- `timezone`
Возвращает:```json
{
"job_id": "...",
"target": "get_weather",
"mode": "interval",
"next_run_at": "...",
"status": "scheduled"
}
run_scheduled_jobs
- Берёт due jobs из storage,
- выполняет
get_weather, - сохраняет результаты,
- пересчитывает
next_run_at, - возвращает результат выполнения.
get_weather_summary
Фильтры:
- location
- date_from
- date_to
Агрегаты:
- records_count
- min/max/avg temperature
- avg humidity
- top_conditions
- период наблюдения
Web API + UI
Запуск:```bash
uv run weather-web
Открыть: `http://127.0.0.1:8008`
UI включает:
- ручной вызов `get_weather`,
- создание schedule,
- запуск due jobs,
- просмотр jobs,
- очистку БД (jobs + records),
- просмотр records,
- summary по location/period.
Примечания по UI:
- поле интервала принимает секунды и минуты (`300`, `90s`, `5m`);
- после отправки запроса в чат и после операций с расписанием список текущих `jobs` обновляется автоматически.
Доступные endpoints:
- `POST /api/weather`
- `POST /api/schedule`
- `POST /api/schedules/run-due`
- `GET /api/schedules`
- `GET /api/records`
- `GET /api/summary`
- `POST /api/storage/clear`
- `POST /api/chat`
- `GET /healthz`
## 24/7 сценарий
1. Создать расписание (`schedule`) через UI или MCP.
2. Запустить daemon:```bash
uv run weather-summary-daemon
- Daemon циклически вызывает
run_scheduled_jobsи печатает сводку.
Storage
По умолчанию SQLite:
- scheduled_jobs
- weather_records
Опционально JSON backend:
- единый JSON файл (jobs + records)
Конфигурация (.env)
См. .env.example. Ключевые переменные:
- OPENAI_API_KEY
- OPENAI_MODEL
- WEATHER_API_KEY
- WEATHER_API_BASE_URL
- WEATHER_GEOCODING_URL
- WEATHER_STORAGE_BACKEND (sqlite/json)
- DATABASE_URL
- WEATHER_JSON_PATH
- SCHEDULER_TICK_SECONDS
- SCHEDULER_MAX_JOBS
- SUMMARY_DAEMON_POLL_SECONDS
- SUMMARY_DAEMON_MAX_JOBS
- APP_TIMEZONE
Локальный запуск```bash
uv sync
cp .env.example .env
заполнить OPENAI_API_KEY
uv run weather-mcp-server
или
uv run weather-web
или
uv run weather-agent
или
uv run weather-summary-daemon
## Тесты и линт```bash
uv run ruff check .
uv run pytest
