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

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

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

- 🌍 Получает текущую погоду для любого города через OpenWeatherMap API
- 📅 Показывает прогноз погоды на несколько дней
- 🤖 Использует Deepseek для естественного общения и вызова инструментов с реальными данными
- 📦 Интегрирован с удалённой PostgreSQL базой и FastAPI для работы с данными о начислениях
- 🔧 Реализует протокол MCP для подключения AI к внешним данным
- 🏗️ Модульная архитектура с асинхронными операциями

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

```
OpenWeatherMap_MCP/
├── modules/                      # Пакет модулей приложения
│   ├── __init__.py              # Инициализация пакета модулей
│   ├── config.py                # Конфигурация (загрузка переменных окружения)
│   ├── weather_api.py           # Функции для работы с OpenWeatherMap API
│   ├── deepseek_api.py          # Функции для работы с Deepseek API
│   └── file_api.py              # Функции для файловых операций
├── fastapi_udalennii/            # Удалённый FastAPI проект (на другом хосте)
│   ├── app/
│   │   ├── main.py              # FastAPI приложение с endpoints
│   │   ├── models.py            # SQLAlchemy таблицы (users, accruals)
│   │   ├── schemas.py           # Pydantic схемы для валидации
│   │   ├── crud.py              # CRUD операции для БД
│   │   ├── db.py                # Подключение к БД
│   │   └── config.py            # Конфигурация
│   ├── alembic/                 # Миграции БД
│   │   └── versions/
│   │       ├── 0001_create_users_table.py
│   │       └── 0002_create_accruals_table.py
│   ├── requirements.txt          # Зависимости FastAPI
│   ├── .env                      # Конфиг БД для удалённого сервера
│   └── README.md                # Инструкции для удалённого FastAPI
├── deepseek_client.py            # Клиент для интерактивного чата с Deepseek
├── server.py                     # MCP сервер с инструментами погоды
├── test_project.py              # Тесты
├── .env                         # API ключи (не добавляйте в Git!)
├── requirements.txt             # Python зависимости для локального клиента
├── DEPLOYMENT_INSTRUCTIONS.md   # Инструкции по развёртыванию FastAPI
└── README.md                    # Эта инструкция
```

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

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

```bash
# Создайте виртуальное окружение
python3 -m venv venv

# Активируйте его
# На macOS/Linux:
source venv/bin/activate
# На Windows:
venv\Scripts\activate

# Установите зависимости
pip3 install -r requirements.txt
```

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

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

```bash
# ===== OpenWeatherMap =====
OPENWEATHER_API_KEY=ваш_ключ_здесь
OPENWEATHER_BASE_URL=https://api.openweathermap.org/data/2.5

# ===== Deepseek =====
DEEPSEEK_API_KEY=ваш_ключ_здесь

# ===== Database (PostgreSQL) =====
DATABASE_URL=postgresql://username:password@192.168.0.134:5432/mydb

# ===== Accruals API (Remote FastAPI) =====
ACCRUALS_API_URL=http://192.168.0.137:8000

# ===== File Operations =====
ALLOWED_BASE_DIR=/path/to/allowed/dir

# ===== Logging =====
LOG_LEVEL=INFO
```

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

- **OpenWeatherMap**:

  1. Зарегистрируйтесь на https://openweathermap.org
  2. Перейдите в раздел API Keys
  3. Скопируйте ключ (бесплатный план: 1000 запросов/день)

- **Deepseek**:
  1. Зарегистрируйтесь на https://platform.deepseek.com
  2. Создайте новый API ключ
  3. Пополните баланс (бесплатный кредит ~$5)

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

```bash
python3 deepseek_client.py
```

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

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

```
ACCRUALS_API_URL=http://192.168.0.137:8000
```

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

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

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

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

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

```
👤 Вы: Какая погода в Москве?
🤖 Deepseek: [Проверяет текущую погоду в Москве через API и показывает результат]

👤 Вы: А какой прогноз на 5 дней для Санкт-Петербурга?
🤖 Deepseek: [Показывает прогноз на 5 дней]

👤 Вы: Что лучше надеть в Лондоне сегодня?
🤖 Deepseek: [Проверяет погоду и дает рекомендации]

👤 Вы: выход
👋 До свидания!
```

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

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

```
👤 Вы: Покажи статистику по начислениям
🤖 Deepseek: [Запрашивает /stats/summary и показывает общую сводку: кол-во записей, платформы, типы]

👤 Вы: Сколько начислений по услугам доставки?
🤖 Deepseek: [Запрашивает /stats/accruals?service_group=Услуги+доставки и показывает статистику]

👤 Вы: Покажи список последних начислений с платформы Ozon
🤖 Deepseek: [Запрашивает /accruals?sales_platform=Ozon&limit=50 и показывает записи]

👤 Вы: выход
👋 До свидания!
```

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

### `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 сервера (для интеграции с другими приложениями):**

```bash
uv run mcp dev server.py
```

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

Ранее в репозитории были утилиты для локальной загрузки данных и локальный 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()` - инициализация и запуск приложения

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

```bash
python3 deepseek_client.py
```

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

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

```
Пользователь
    ↓
deepseek_client.py (chat_with_deepseek)
    ↓
modules/deepseek_api.py (get_weather_response)
    ↓
Deepseek API
    ├─ Анализирует запрос
    └─ Вызывает инструменты (function calling)
         ↓
    modules/weather_api.py
         ├─ get_current_weather()
         └─ get_forecast()
              ↓
         OpenWeatherMap API
              ↓
         Возвращает реальные данные о погоде
    ↓
Deepseek API (обработка результатов инструментов)
    ↓
Финальный ответ пользователю
```

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

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

1. **Добавьте функцию в модуль `modules/weather_api.py`:**

```python
async def get_air_quality(city: str) -> str:
    """Получить качество воздуха для города"""
    # Реализация...
    return result
```

2. **Добавьте определение инструмента в `modules/deepseek_api.py`:**

```python
def get_weather_tools() -> List[Dict[str, Any]]:
    tools = [
        # ... существующие инструменты ...
        {
            "type": "function",
            "function": {
                "name": "get_air_quality",
                "description": "Получить качество воздуха",
                # ... параметры ...
            }
        }
    ]
    return tools
```

3. **Добавьте обработку в `process_deepseek_response()`:**

```python
if tool_name == "get_air_quality":
    result = await get_air_quality(tool_args.get("city"))
```

4. **Добавьте инструмент в MCP сервер `server.py`:**

```python
@mcp.tool()
async def air_quality(city: str) -> str:
    """Инструмент MCP для получения качества воздуха"""
    return await get_air_quality(city)
```

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

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

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

- `DEBUG` - подробная информация для отладки
- `INFO` - основная информация о работе
- `WARNING` - предупреждения
- `ERROR` - ошибки
- `CRITICAL` - критические ошибки

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

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

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

```bash
# Используйте MCP Inspector
uv run mcp dev server.py

# Или установите в Claude Desktop
uv run mcp install server.py --name "Weather Service"
```

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

### Ошибка: "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

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

```
Пользователь
    ↓
deepseek_client.py
    ↓
Deepseek API (обработка запроса)
    ├─ Погода → modules/weather_api.py → OpenWeatherMap API
    ├─ Файлы → modules/file_api.py → локальная ФС
    └─ Начисления → httpx HTTP запрос → fastapi_udalennii (192.168.0.137:8000)
         ├─ GET /accruals/ → fastapi_udalennii/app/crud.py → PostgreSQL
         ├─ GET /stats/summary → fastapi_udalennii/app/crud.py → PostgreSQL
         └─ POST /accruals/ → fastapi_udalennii/app/crud.py → PostgreSQL
    ↓
Deepseek API (формирует ответ)
    ↓
Пользователю
```

### Новые endpoints в FastAPI:

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

**Accruals endpoints:**

- `POST /accruals/` - создание новой записи о начислении
- `GET /accruals/` - получение списка с фильтрацией

**Stats endpoints:**

- `GET /stats/summary` - общая статистика по всем начислениям
- `GET /stats/accruals` - статистика с фильтрацией

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

```bash
# Получить все начисления
curl http://192.168.0.137:8000/accruals/

# Получить начисления по платформе Ozon
curl "http://192.168.0.137:8000/accruals/?sales_platform=Ozon&limit=50"

# Получить статистику
curl http://192.168.0.137:8000/stats/summary

# Создать новое начисление
curl -X POST http://192.168.0.137:8000/accruals/ \
  -H "Content-Type: application/json" \
  -d '{
    "id_accrual": "ACC001",
    "accrual_date": "2025-12-08",
    "service_group": "Доставка",
    "accrual_type": "Комиссия",
    "sales_platform": "Ozon",
    "total_amount_rub": 1234.56
  }'
```

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

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

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

1. Синхронизация кода через `rsync`
2. Активация venv на удалённом сервере
3. Установка зависимостей (если добавлены новые)
4. Запуск миграций Alembic
5. Перезагрузка FastAPI сервиса

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

1. **Не используйте `print()` в server.py** - это сломает STDIO транспорт
2. **Храните `.env` в безопасности** - добавьте в `.gitignore`
3. **Лимиты API**:
   - OpenWeatherMap Free: 1000 запросов/день
   - Deepseek: зависит от вашего плана
4. **Стоимость Deepseek**: Более дешевая чем OpenAI
5. **Миграции БД**: После обновления FastAPI кода обязательно запустите `alembic upgrade head`

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

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

- Проверьте, что файл `.env` создан и содержит ключ
- Убедитесь, что файл находится в той же папке, что и скрипты

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

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

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

- Убедитесь, что виртуальное окружение активировано
- Проверьте, что все зависимости установлены

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

- [MCP Documentation](https://modelcontextprotocol.io/)
- [OpenWeatherMap API](https://openweathermap.org/api)
- [Канал "Черный треугольник"](https://t.me/black_triangle_tg)