🌤️ MCP Сервер Погоды с Deepseek

Простой MCP сервер для получения погоды через OpenWeatherMap API с использованием Deepseek API в качестве интерфейса и поддержкой модульной архитектуры.

📋 Что это делает?

• 🌍 Получает текущую погоду для любого города через OpenWeatherMap API

• 📅 Показывает прогноз погоды на несколько дней

• 🤖 Использует Deepseek для естественного общения и вызова инструментов с реальными данными

• 📦 Интегрирован с удалённой PostgreSQL базой и FastAPI для работы с данными о начислениях

• 🔧 Реализует протокол MCP для подключения AI к внешним данным

• 🏗️ Модульная архитектура с асинхронными операциями

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

🚀 Быстрый старт

1. Установка зависимостей

2. Настройка API ключей и подключений

Создайте файл .env в корне проекта:

Получение API ключей:

• OpenWeatherMap:

  1. Зарегистрируйтесь на https://openweathermap.org

  2. Перейдите в раздел API Keys

  3. Скопируйте ключ (бесплатный план: 1000 запросов/день)

• Deepseek:

  1. Зарегистрируйтесь на https://platform.deepseek.com

  2. Создайте новый API ключ

  3. Пополните баланс (бесплатный кредит ~$5)

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

4. (Опционально) Работа через удалённый API для начислений

Deepseek может запрашивать данные о начислениях через REST API (FastAPI) — если у вас уже развернут удалённый API, укажите его базовый URL в переменной ACCRUALS_API_URL.

Убедитесь, что удалённая база и API содержат необходимые данные — локальные утилиты для загрузки Excel (modules/db_loader.py) удалены из репозитория. После настройки ACCRUALS_API_URL Deepseek сможет запрашивать статистику и списки начислений у удалённого сервера.

Теперь в клиенте Deepseek можно спрашивать о начислениях (см. примеры ниже).

💬 Примеры использования

Работа с погодой

После запуска deepseek_client.py просто спрашивайте о погоде на естественном языке:

Работа с данными о начислениях (Ozon)

После запуска API (см. раздел "Запуск API для работы с БД") можно запрашивать данные:

🔧 Описание модулей

modules/config.py

Отвечает за: конфигурацию приложения, загрузку переменных окружения, валидацию ключей API.

Основные компоненты:

• Config - класс с константами конфигурации

• validate() - проверяет наличие критических переменных окружения

• get_config_summary() - возвращает сводку конфигурации для логирования

modules/weather_api.py

Отвечает за: взаимодействие с OpenWeatherMap API для получения данных о погоде.

Основные функции:

• make_weather_request() - вспомогательная функция для HTTP запросов к API

• get_current_weather() - получает текущую погоду для города

• get_forecast() - получает прогноз на несколько дней

• format_day_forecast() - форматирует прогноз на один день

modules/deepseek_api.py

Отвечает за: взаимодействие с Deepseek API для обработки запросов пользователя с использованием инструментов (функций).

Основные функции:

• get_weather_tools() - возвращает определение инструментов для Deepseek

• call_deepseek_with_tools() - вызывает Deepseek с поддержкой инструментов (function calling)

• process_deepseek_response() - обрабатывает ответ от Deepseek, выполняет вызовы инструментов

• get_weather_response() - главная функция для получения ответа о погоде

Поддерживаемые инструменты:

• Погода: get_current_weather, get_forecast

• Файлы: read_file, create_file, update_file, append_to_file, delete_file, list_files

modules/file_api.py

Отвечает за: безопасную работу с файлами по определённому пути.

Основные функции:

• read_file() - чтение содержимого файла

• create_file() - создание нового файла

• update_file() - обновление содержимого файла

• append_to_file() - добавление содержимого в файл

• delete_file() - удаление файла

• list_files() - просмотр содержимого директории

• is_path_safe() - проверка безопасности пути (предотвращает path traversal атаки)

Примеры команд для Deepseek:

• "Создай файл test.txt с текстом 'Hello World'"

• "Прочитай содержимое файла README.md"

• "Обнови файл config.py на новый код"

• "Покажи список файлов в папке modules"

• "Добавь новую строку в файл notes.txt"

• "Удали временный файл temp.txt"

server.py

Отвечает за: запуск MCP сервера с инструментами для интеграции с другими приложениями.

Основные инструменты MCP:

• current_weather() - инструмент для получения текущей погоды

• weather_forecast() - инструмент для получения прогноза

Для запуска только MCP сервера (для интеграции с другими приложениями):

Удалённые локальные модули

Ранее в репозитории были утилиты для локальной загрузки данных и локальный API:

• modules/db.py — локальная SQLAlchemy модель и хелперы для создания таблиц

• modules/db_loader.py — скрипт загрузки Excel (pandas → БД)

• modules/api.py — FastAPI приложение для доступа к данным о начислениях

Эти файлы удалены из текущего репозитория в пользу использования удалённых сервисов (базы данных и API). Если вам нужно восстановить локальную загрузку или локальный API, можно восстановить соответствующие модули и добавить в requirements.txt зависимости: pandas, openpyxl, sqlalchemy, psycopg2-binary, uvicorn.

deepseek_client.py

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

Основные функции:

• chat_with_deepseek() - интерактивный цикл чата с естественным языком

• main() - инициализация и запуск приложения

Для запуска полного приложения:

Это команда, которая вам нужна! Она запускает интерактивный чат с Deepseek, который использует реальные данные о погоде из OpenWeatherMap API и может запрашивать данные о начислениях (если API запущен).

🌐 Схема взаимодействия

🔌 Добавление новых функций

Чтобы добавить новый инструмент (например, получение качества воздуха):

1. Добавьте функцию в модуль

2. Добавьте определение инструмента в

3. Добавьте обработку в

4. Добавьте инструмент в MCP сервер

📊 Логирование

Приложение использует встроенный модуль logging для отслеживания всех операций. Логи записываются в файл app.log и выводятся в консоль.

Уровни логирования:

• DEBUG - подробная информация для отладки

• INFO - основная информация о работе

• WARNING - предупреждения

• ERROR - ошибки

• CRITICAL - критические ошибки

Уровень логирования можно настроить через переменную окружения LOG_LEVEL в .env.

🧪 Тестирование только сервера

Если хотите протестировать MCP сервер без клиента:

🐛 Поиск и решение проблем

Ошибка: "OPENWEATHER_API_KEY не найден"

Решение: Убедитесь, что файл .env находится в корне проекта и содержит OPENWEATHER_API_KEY=ваш_ключ

Ошибка: "Не удалось получить погоду для города"

Решение:

• Проверьте написание названия города

• Убедитесь, что у вас есть интернет подключение

• Проверьте, не исчерпан ли лимит бесплатного плана OpenWeatherMap

Ошибка: "Ошибка при обращении к Deepseek API"

Решение:

• Проверьте, что DEEPSEEK_API_KEY скопирован правильно

• Убедитесь, что на вашем счёте есть баланс для API запросов

• Проверьте статус Deepseek API на https://status.deepseek.com/

📝 Лицензия

Этот проект лицензирован под MIT License.

🤝 Контрибьютинг

Приветствуются pull requests! Для больших изменений сначала откройте issue для обсуждения.

🛠️ Доступные инструменты

get_current_weather

Получает текущую погоду для города

Параметры:

• city (обязательный): Название города

• units (опционально): "metric" или "imperial"

get_forecast

Получает прогноз погоды на несколько дней

Параметры:

• city (обязательный): Название города

• days (опционально): Количество дней (1-5)

• units (опционально): "metric" или "imperial"

🌐 Архитектура с удалённым FastAPI

Проект использует двухуровневую архитектуру:

Локальный слой (ваша машина)

• deepseek_client.py - интерактивный чат с Deepseek

• modules/deepseek_api.py - интеграция с Deepseek для обработки запросов

• modules/weather_api.py - получение данных о погоде

• modules/file_api.py - файловые операции

Удалённый слой (другой хост 192.168.0.137:8000)

• fastapi_udalennii/app/main.py - REST API для работы с начислениями (accruals)

• fastapi_udalennii/app/models.py - SQLAlchemy таблицы (users, accruals)

• fastapi_udalennii/app/crud.py - операции БД

• fastapi_udalennii/app/schemas.py - валидация данных (Pydantic)

База данных (PostgreSQL)

• Хост: 192.168.0.134:5432

• База: mydb

• Пользователь: asx

Схема взаимодействия:

Новые endpoints в FastAPI:

После развёртывания на удалённом сервере (см. DEPLOYMENT_INSTRUCTIONS.md) доступны:

Accruals endpoints:

• POST /accruals/ - создание новой записи о начислении

• GET /accruals/ - получение списка с фильтрацией

Stats endpoints:

• GET /stats/summary - общая статистика по всем начислениям

• GET /stats/accruals - статистика с фильтрацией

Примеры запросов:

⚙️ Развёртывание и обновления

Для развёртывания обновлённого FastAPI на удалённом сервере смотрите инструкции в DEPLOYMENT_INSTRUCTIONS.md.

Краткая схема:

1. Синхронизация кода через rsync

2. Активация venv на удалённом сервере

3. Установка зависимостей (если добавлены новые)

4. Запуск миграций Alembic

5. Перезагрузка FastAPI сервиса

⚠️ Важные замечания

1. Не используйте - это сломает STDIO транспорт

2. Храните - добавьте в .gitignore

3. Лимиты API:

   • OpenWeatherMap Free: 1000 запросов/день

   • Deepseek: зависит от вашего плана

4. Стоимость Deepseek: Более дешевая чем OpenAI

5. Миграции БД: После обновления FastAPI кода обязательно запустите alembic upgrade head

🐛 Решение проблем

Ошибка: "OPENWEATHER_API_KEY не найден"

• Проверьте, что файл .env создан и содержит ключ

• Убедитесь, что файл находится в той же папке, что и скрипты

Ошибка: "Не удалось получить погоду"

• Проверьте правильность написания города

• Попробуйте английское название города

Сервер не запускается

• Убедитесь, что виртуальное окружение активировано

• Проверьте, что все зависимости установлены

📚 Полезные ссылки

• MCP Documentation

• OpenWeatherMap API

• Канал "Черный треугольник"