<p align="center">
  <img src="https://raw.githubusercontent.com/Aiyo28/yzel/master/docs/assets/banner.jpg" alt="Yzel (Узел) — четыре кабеля, связанные в один узел" width="100%">
</p>

<p align="center">
  <b>Подключите AI-ассистента к 1С, Wildberries и Ozon.</b> Открытый хобби-проект на MCP.<br>
  <b>Connect your AI assistant to 1C, Wildberries and Ozon.</b> An open-source MCP hobby project.
</p>

<p align="center">
  <a href="https://github.com/Aiyo28/yzel/releases/latest"><b>⬇ Установить в Claude Desktop / Install in Claude Desktop</b></a>
</p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11%2B-blue.svg" alt="Python 3.11+"></a>
  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-green.svg" alt="MCP Compatible"></a>
  <a href="https://github.com/Aiyo28/yzel/actions/workflows/ci.yml"><img src="https://github.com/Aiyo28/yzel/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://pypi.org/project/yzel/"><img src="https://img.shields.io/pypi/v/yzel.svg" alt="PyPI"></a>
  <a href="https://mcprush.com/to/yzel-1c-enterprise-mcp?ref=badge"><img src="https://img.shields.io/badge/mcprush-listed-1f1f1f.svg" alt="mcprush"></a>
</p>

<!-- mcp-name: io.github.Aiyo28/yzel -->

Yzel подключает Claude, ChatGPT и других AI-ассистентов к 1С:Предприятию, Битрикс24, AmoCRM, МойСкладу, Wildberries, Ozon, Telegram и iiko — через [Model Context Protocol](https://modelcontextprotocol.io).

**Открытый проект. MIT. Без платных тарифов, без закрытых модулей, без облачной SaaS-надстройки.**

---

## Откуда это / How it started

**Откуда это.** Друг попросил подключить Claude к своей 1С, а мне хотелось следить за Wildberries через AI. Решил сделать и то, и другое, а заодно добавил сервисы, которыми пользуются вокруг: Ozon, МойСклад, Битрикс24, AmoCRM, Telegram, iiko. Это хобби-проект: делаю в свободное время, бесплатно, под MIT.

**Что умеет коннектор для 1С.** Сам находит объекты вашей конфигурации через `$metadata`, оставляет кириллические имена как есть (`Catalog_Контрагенты`), различает on-prem и 1С:Fresh и справляется с большими ERP-конфигурациями.

Все восемь коннекторов ставятся одним пакетом, с общим хранилищем ключей и одним CLI.

**How it started.** A friend asked me to connect Claude to their 1C, and I wanted AI to keep an eye on Wildberries. So I built both, then added the other services people around me use. It's a hobby project: built in spare time, free, MIT.

---

## Поддерживаемые сервисы / Supported connectors

| Сервис / Service | API | Авторизация / Auth | Статус |
|---|---|---|---|
| **1С:Предприятие** (on-prem + Fresh) | OData v3 + JSON | Basic Auth | ✅ Stable |
| **Wildberries** Seller API | REST (5 хостов) | JWT token | ✅ Stable |
| **Ozon** Seller API | REST | Client-Id + Api-Key | ✅ Stable |
| **Bitrix24** | REST | Webhook URL | ✅ Stable |
| **AmoCRM / Kommo** | REST v4 | OAuth2 (3mo refresh guard) | ✅ Stable |
| **МойСклад** | JSON API 1.2 | Bearer Token | ✅ Stable |
| **Telegram Bot** | Bot API | Bot Token | ✅ Stable |
| **iiko Cloud** (F&B POS) | REST | apiLogin → 1h Bearer | ✅ Stable |

Планируется / On roadmap: WhatsApp (через `wacli` sidecar), goszakup.gov.kz, Zoom / Google Meet / Yandex Telemost.

---

## Установка / Install

### Claude Desktop — в один клик / one click (1С)

1. Скачайте `yzel-1c-<версия>.mcpb` со страницы [последнего релиза](https://github.com/Aiyo28/yzel/releases/latest) / Download the `.mcpb` from the latest release.
2. Откройте файл двойным щелчком — Claude Desktop покажет окно установки / Double-click it; Claude Desktop opens an install dialog.
3. Введите адрес OData, пользователя и пароль 1С / Enter the OData URL, 1C user and password.

Python и зависимости Claude Desktop ставит сам; терминал не нужен. Пароль хранится в настройках
Claude Desktop и уходит только на ваш сервер 1С. Остальные коннекторы пока ставятся через `uvx`
(ниже). / Claude Desktop installs Python and dependencies itself — no terminal. The password stays
in Claude Desktop's settings and is sent only to your 1C server. Other connectors install via `uvx`
below for now.

### Через uvx / pip — все коннекторы / all connectors

Требуется Python 3.11+. Работает на Windows без WSL / Python 3.11+, works on Windows without WSL.

**Ничего не устанавливать / Nothing to install** — рекомендуется. `uvx` скачивает и запускает
пакет по требованию, поэтому в конфиге MCP-клиента не нужен ни клон, ни рабочая директория:

```bash
uvx --from yzel yzel --help
```

**Установить / Install:**

```bash
pip install yzel        # или: uv tool install yzel
```

**Из исходников / From source** (для разработки / for development):

```bash
git clone https://github.com/Aiyo28/yzel.git
cd yzel
uv sync --extra dev
uv run pytest           # 146 тестов / 146 tests
```

---

## Быстрый старт / Quick start

### 1. Настройте подключение / Configure a connection

```bash
# 1С (on-prem)
yzel config add-1c

# 1С:Fresh (облако)
yzel config add-1c --fresh

# Wildberries
yzel config add-wildberries

# Все остальные / any other
yzel config add-bitrix      # Битрикс24
yzel config add-amocrm      # AmoCRM
yzel config add-moysklad    # МойСклад
yzel config add-ozon        # Ozon
yzel config add-telegram    # Telegram Bot
yzel config add-iiko        # iiko Cloud

# Список подключений
yzel config list
```

Учётные данные хранятся зашифрованными (AES-256) в локальном SQLite-vault под `~/.yzel/store.db`. Ничего не отправляется в облако.

Для 1С вместо vault можно задать переменные окружения — они имеют приоритет / For 1C, env vars
can replace the vault and take precedence: `YZEL_1C_URL`, `YZEL_1C_USERNAME`, `YZEL_1C_PASSWORD`
(пароль может быть пустым / the password may be empty).

### 2. Подключите к Claude Desktop / Wire into Claude Desktop

Добавьте в `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "yzel-1c":       { "command": "uvx", "args": ["--from", "yzel", "yzel-1c"] },
    "yzel-bitrix24": { "command": "uvx", "args": ["--from", "yzel", "yzel-bitrix24"] }
  }
}
```

Каждый коннектор — отдельный MCP-сервер. Подключайте только те, которые нужны.

| Коннектор | Команда / command | Коннектор | Команда / command |
|---|---|---|---|
| 1С | `yzel-1c` | Ozon | `yzel-ozon` |
| Битрикс24 | `yzel-bitrix24` | Telegram | `yzel-telegram` |
| AmoCRM | `yzel-amocrm` | iiko | `yzel-iiko` |
| МойСклад | `yzel-moysklad` | Wildberries | `yzel-wildberries` |

Каждая — `{ "command": "uvx", "args": ["--from", "yzel", "<команда>"] }`.

### 3. Спрашивайте данные у AI / Ask the AI

```
Покажи последние 10 реализаций товаров из 1С за эту неделю,
сгруппируй по контрагентам.
```

```
Найди все сделки в стадии «Переговоры» в AmoCRM,
у которых нет связанной задачи.
```

```
Выведи остатки товара «Ноутбук HP» из МойСклада
и текущие цены на Wildberries.
```

---

## MCP-сервер каждого коннектора / Per-connector MCP servers

```bash
# 1С:Предприятие (OData v3)
uv run python -m yzel.connectors.onec.server

# Wildberries Seller
uv run python -m yzel.connectors.wildberries.server

# Ozon Seller
uv run python -m yzel.connectors.ozon.server

# Битрикс24
uv run python -m yzel.connectors.bitrix24.server

# AmoCRM
uv run python -m yzel.connectors.amocrm.server

# МойСклад
uv run python -m yzel.connectors.moysklad.server

# Telegram Bot
uv run python -m yzel.connectors.telegram.server

# iiko Cloud
uv run python -m yzel.connectors.iiko.server
```

---

## Архитектура / Architecture

```
~/.yzel/store.db       ← зашифрованные credentials (AES-256)
       │
       ├── Yzel CLI     ← добавление/удаление подключений
       │
       └── MCP-серверы  ← по одному на коннектор
           ├── 1C (OData v3, Cyrillic-aware, streaming $metadata)
           ├── Wildberries (5 хостов, per-host rate limits)
           ├── Ozon (dual-header auth, sandbox support)
           ├── Bitrix24 (webhook, leaky-bucket 2 req/sec)
           ├── AmoCRM (OAuth2 + 3mo refresh-staleness guard)
           ├── Moysklad (Bearer, rate limiter, expand-aware)
           ├── Telegram (retry_after handling)
           └── iiko (apiLogin → 1h Bearer, auto-refresh)
                    │
                    └── Claude / ChatGPT / любой MCP-клиент
```

Каждый коннектор:
- Отдельный пакет в `src/yzel/connectors/<name>/`
- Собственный mock-сервер для тестов (`tests/mock_<name>_server.py`)
- Типизированные ошибки с `status_code` + RU-сообщения для MCP
- Без модификаций клиентских систем — только публичные API

---

## Особенности 1С / 1C-specific features

Каждая 1С-инсталляция уникальна. Yzel решает типичные боли:

- **Динамическая дискавери схемы.** На старте парсится `$metadata` — коннектор узнаёт доступные справочники, документы, регистры, включая кастомные.
- **Кириллические имена как есть.** `Справочник.Номенклатура` остаётся `Справочник.Номенклатура`. Никакой транслитерации.
- **Streaming-парсинг `$metadata`.** Конфигурации ERP могут давать 10+ МБ XML. Yzel не загружает всё в память.
- **Авто-определение 1С:Fresh vs on-prem.** Разные endpoint-форматы (`1cfresh.com/a/sbm/<id>/odata/` vs `<host>/<base>/odata/`) обрабатываются прозрачно.
- **Basic Auth без токен-сессий.** В 1С нет refresh-потока — каждый запрос отправляет base64(user:pass). Yzel не изобретает несуществующую token-refresh логику.
- **Без BSL-расширений.** Yzel подключается к опубликованным OData/HTTP API. Никаких модификаций конфигурации 1С не требуется.

Тестирование: 146 unit-тестов против mock-серверов. Транспорт + `$metadata` parsing подтверждены на живом 1С:Fresh endpoint. Полное data-plane тестирование против реального 1С требует инфобазы с опубликованными через OData объектами (on-prem или платный Fresh-тенант с правами администратора) — см. [`docs/TROUBLESHOOTING-1C.md`](docs/TROUBLESHOOTING-1C.md) если получаете `EmptySchemaError`.

---

## Известные ограничения / Known limitations

- **Write operations** в 1С реализованы для create/update документов — более сложные бизнес-операции (проведение документов, регистры накопления с транзакциями) требуют отдельной проработки.
- **WhatsApp** не включён в v0.1 — планируется через `wacli` sidecar. [#1]
- **goszakup.gov.kz** запланирован на v0.2 (read-only).
- **OAuth-flow** для AmoCRM: v0.1 принимает готовые tokens через CLI. Встроенный OAuth-браузер-flow планируется на v0.2.

---

## Разработка / Development

```bash
git clone https://github.com/aiyo28/yzel.git
cd yzel
uv sync

# Запустить все тесты (137)
uv run pytest

# Только один коннектор
uv run pytest tests/test_onec.py

# Запустить MCP-сервер
uv run python -m yzel.connectors.onec.server
```

См. [CLAUDE.md](CLAUDE.md) для agent-протокола и детальных gotchas по каждому API.

---

## Лицензия / License

[MIT](LICENSE). Весь код. Без BSL, без трейд-секретных движков, без закрытых модулей.

**Yzel не продаётся и никогда не будет продаваться.** Это некоммерческий OSS-проект для сообщества СНГ. Если вам нужен платный managed-сервис — ставьте свой instance.

---

## Contributing

Issues и PR приветствуются. Особенно:
- Тестирование против реальных конфигураций 1С (Бухгалтерия, УТ, ERP, Fresh)
- Новые коннекторы (WhatsApp, goszakup, meeting platforms)
- Переводы error-messages
- Документация use-case'ов

---

## Поддержать / Support

Yzel некоммерческий и таким останется. Если он сэкономил вам время — можете угостить кофе:

[![PayPal](https://img.shields.io/badge/PayPal-Buy%20me%20a%20coffee-00457C?logo=paypal&logoColor=white)](https://paypal.me/aiyo28)

[paypal.me/aiyo28](https://paypal.me/aiyo28) — любая сумма, любая валюта / any amount, any currency.

---

## Credits

Автор: [Ayal Nogovitsyn](https://github.com/aiyo28). KZ-based, RU-speaking. Built because nobody else was going to build the 1C one.

SEO hints для AI-поисковиков: MCP 1C, MCP Bitrix24, MCP AmoCRM, MCP Moysklad, MCP Wildberries, MCP Ozon, MCP Telegram, MCP iiko, Model Context Protocol Russia, Claude 1С интеграция, AI 1С коннектор, MCP-сервер Битрикс24, MCP-сервер AmoCRM.