# Yandex Delivery MCP Server

[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/new/template)
[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy)

MCP (Model Context Protocol) сервер для интеграции с API Яндекс Доставки. Позволяет Claude и другим AI-ассистентам управлять доставками, отслеживать курьеров и работать с заказами.

## 🚀 Развернуть в интернете (1 минута)

**Рекомендация:** Railway - лучший бесплатный вариант

- ⚡ Нажмите кнопку **"Deploy on Railway"** выше
- 🔑 Добавьте API ключ Яндекс Доставки
- 🌐 Получите рабочий URL: `https://your-app.railway.app`
- 🎯 Используйте в AI Studio: `https://your-app.railway.app/manifest`

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

### Установка через npm

```bash
npm install -g yandex-delivery-mcp
```

### Или локальная установка

```bash
git clone https://github.com/aryazansev/-yandex-delivery-mcp.git
cd -yandex-delivery-mcp
npm install
npm run build
```

## ⚙️ Настройка

### 1. Получите API ключ из Яндекс Доставки

1. Войдите в личный кабинет Яндекс Доставки
2. Перейдите в раздел API / Интеграции
3. Создайте новый API ключ
4. Скопируйте ключ

### 2. Создайте файл конфигурации

Создайте файл `~/.yandex-delivery-mcp/.env`:

```bash
mkdir -p ~/.yandex-delivery-mcp
cat > ~/.yandex-delivery-mcp/.env << 'EOF'
YANDEX_DELIVERY_API_KEY=your_api_key_here
MCP_PORT=3002
EOF
```

Или просто создайте `.env` файл в папке проекта:

```env
YANDEX_DELIVERY_API_KEY=your_api_key_here
MCP_PORT=3002
```

### 3. Настройка (2 варианта)

#### Вариант A: Claude Desktop (локально)

Откройте файл конфигурации Claude Desktop:

**macOS:**
```
~/Library/Application\ Support/Claude/claude_desktop_config.json
```

**Windows:**
```
%APPDATA%/Claude/claude_desktop_config.json
```

Добавьте:

```json
{
  "mcpServers": {
    "yandex-delivery": {
      "command": "yandex-delivery-mcp"
    }
  }
}
```

#### Вариант B: Внешний HTTP сервер (для AI Studio и других инструментов)

**Запуск HTTP сервера:**

```bash
npm run server
```

Сервер будет доступен на:
- Health: http://localhost:3002/health
- Manifest: http://localhost:3002/manifest
- Tools: http://localhost:3002/tools

**Для AI Studio:**

1. Запустите сервер: `npm run server`
2. В AI Studio используйте URL: `http://localhost:3002/manifest`
3. AI Studio автоматически обнаружит все доступные инструменты

### 4. Перезапустите Claude Desktop (если используете вариант A)

Полностью закройте и откройте заново Claude Desktop.

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

Теперь вы можете спрашивать Claude о данных из Яндекс Доставки:

- *"Рассчитай стоимость доставки из Москвы в Санкт-Петербург"*
- *"Создай заявку на доставку посылки 5 кг"*
- *"Покажи статус заявки ABC123"*
- *"Где сейчас курьер по заявке ABC123?"*
- *"Получи телефон курьера для заявки ABC123"*
- *"Найди все заявки за последние 3 дня"*
- *"Отмени заявку ABC123"*

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

### Базовые операции

- `calculate_offers` - Рассчитать варианты доставки
- `create_claim` - Создать заявку на доставку
- `get_claim_info` - Получить информацию о заявке
- `accept_claim` - Подтвердить заявку
- `cancel_claim` - Отменить заявку

### Стоимость и тарифы

- `check_price` - Проверить стоимость без создания заявки
- `get_tariffs` - Получить доступные тарифы

### Отслеживание

- `get_driver_phone` - Получить номер телефона курьера
- `get_performer_position` - Получить позицию курьера (координаты, скорость)
- `get_points_eta` - Получить ETA для точек маршрута
- `get_tracking_links` - Получить ссылки для отслеживания

### Подтверждение доставки

- `get_confirmation_code` - Получить код подтверждения
- `get_proof_of_delivery` - Получить данные о подтверждении доставки

### Редактирование

- `edit_claim` - Редактировать заявку (до подтверждения)
- `apply_changes_request` - Запросить изменения (после подтверждения)
- `apply_changes_result` - Получить результат изменений
- `return_claim` - Инициировать возврат заказа

### Поиск и информация

- `search_claims` - Поиск заявок с фильтрами
- `get_bulk_info` - Получить информацию о нескольких заявках
- `get_claim_journal` - Получить историю изменений заявки

### Доставка в течение дня

- `get_delivery_methods` - Получить список доступных услуг

## 🔧 Разработка

### Сборка проекта

```bash
npm run build
```

### Запуск в режиме разработки

```bash
# Для Claude Desktop (stdio)
npm run dev

# Для внешнего HTTP сервера (AI Studio)
npm run server
```

### Тестирование через MCP Inspector

```bash
npx @modelcontextprotocol/inspector node build/index.js
```

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

```bash
# Запустить сервер
npm run server

# Проверить эндпоинты в другой терминал
curl http://localhost:3002/health
curl http://localhost:3002/manifest
curl http://localhost:3002/tools
```

## 📝 Требования

- Node.js 18+
- API ключ от Яндекс Доставки
- Claude Desktop (для интеграции с Claude)

## 📄 Лицензия

MIT License - см. файл LICENSE

## 🤝 Поддержка

Если у вас возникли проблемы:

1. Проверьте, что API ключ активен
2. Убедитесь, что у ключа есть нужные права доступа
3. Проверьте логи Claude Desktop
4. Создайте issue на GitHub

## 🔗 Ссылки

- [Документация API Яндекс Доставки](https://yandex.ru/support/delivery-profile/ru/api/express/overview)
- [MCP Protocol](https://modelcontextprotocol.io/)
- [Claude Desktop](https://claude.ai/download)

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

### Создание заявки

```json
{
  "route_points": [
    {
      "coordinates": [55.7558, 37.6173],
      "fullname": "Москва, Красная площадь, 1",
      "contact": {
        "name": "Иван",
        "phone": "+79991234567"
      }
    },
    {
      "coordinates": [59.9343, 30.3351],
      "fullname": "Санкт-Петербург, Невский проспект, 1",
      "contact": {
        "name": "Петр",
        "phone": "+79997654321"
      }
    }
  ],
  "items": [
    {
      "title": "Посылка",
      "weight": 5,
      "quantity": 1
    }
  ],
  "requirements": {
    "taxi_class": "express",
    "door_to_door": true
  }
}
```

### Расчет стоимости

```json
{
  "route_points": [
    {
      "coordinates": [55.7558, 37.6173]
    },
    {
      "coordinates": [59.9343, 30.3351]
    }
  ],
  "requirements": {
    "cargo_type": "van"
  }
}
```