# avito-mcp

MCP-сервер для Avito API. Даёт Claude доступ к объявлениям, статистике, переписке и автозагрузке.

## Переменные окружения

| Переменная | Обязательна | Что это |
|---|---|---|
| `AVITO_CLIENT_ID` | да | Из кабинета разработчика Авито |
| `AVITO_CLIENT_SECRET` | да | Там же |
| `MCP_SECRET` | да | Длинная случайная строка, становится частью URL коннектора |
| `AVITO_ACCOUNT` | нет | Короткий ключ кабинета, например `cheki` (по умолчанию `main`) |
| `AVITO_ACCOUNT_LABEL` | нет | Человеческое название кабинета, например `Чекинские берега` |
| `AVITO_USER_ID` | нет | Если не задан, берётся из `/core/v1/accounts/self` |
| `AVITO_REFRESH_TOKEN` | нет | Нужен, если мессенджер не работает на client_credentials |

## Несколько кабинетов Авито

Один сервер умеет работать с несколькими аккаунтами. Второй и последующие
задаются теми же переменными с суффиксом `_2`, `_3`, … до `_9`:

```
AVITO_CLIENT_ID_2=...
AVITO_CLIENT_SECRET_2=...
AVITO_ACCOUNT_2=dolina
AVITO_ACCOUNT_LABEL_2=Светлая долина
```

У всех инструментов появляется параметр `account` — ключ кабинета (`cheki`,
`dolina`, …). Если настроен один аккаунт, параметр можно не указывать. Если
аккаунтов несколько, а `account` не передан, инструмент вернёт ошибку со
списком доступных ключей — так исключается случайная работа не по тому
кабинету. Список кабинетов отдаёт инструмент `avito_accounts`.

Токены и профили кэшируются отдельно на каждый аккаунт.

Альтернатива суффиксам — одна переменная `AVITO_ACCOUNTS` с JSON-массивом
(имеет приоритет над суффиксами):

```json
[{"key":"cheki","label":"Чекинские берега","client_id":"...","client_secret":"..."},
 {"key":"dolina","label":"Светлая долина","client_id":"...","client_secret":"..."}]
```

Сгенерировать секрет:

```
node -e "console.log(require('crypto').randomBytes(24).toString('hex'))"
```

## Запуск локально

```
npm install
AVITO_CLIENT_ID=... AVITO_CLIENT_SECRET=... MCP_SECRET=... npm start
```

Проверка: `curl http://localhost:3000/` должен вернуть `{"service":"avito-mcp","status":"ok"}`.

## Деплой на Railway

1. Запушить репозиторий на GitHub.
2. В Railway создать сервис из этого репозитория.
3. В Variables добавить переменные из таблицы выше.
4. Сгенерировать публичный домен в Settings → Networking.

URL коннектора: `https://<домен>/mcp/<MCP_SECRET>`

## Подключение в Claude

Настройки → Коннекторы → добавить кастомный коннектор, вставить URL.

## Инструменты

Служебный: `avito_accounts` — список подключённых кабинетов.

Чтение: `avito_whoami`, `avito_balance`, `avito_items_list`, `avito_item_info`,
`avito_item_stats`, `avito_chats_list`, `avito_chat_messages`,
`avito_autoload_reports`.

Запись: `avito_send_message`, `avito_update_price`, `avito_mark_read`.

Запасной: `avito_request` — сырой вызов любого метода API.

## Что API не умеет

Править заголовки, описания, фото и характеристики объявлений через REST нельзя.
Только цена (`avito_update_price`). Остальное — через Автозагрузку, то есть через
XML/CSV-фид. `avito_autoload_reports` показывает результаты последних выгрузок.