Yzel — 1C:Enterprise

Yzel (Узел)

面向独联体业务工具的 MCP 连接器。 首个真正成熟的 1С MCP 服务，此外还将 7 个独联体业务系统集成在一个软件包中。

面向独联体业务工具的 MCP 连接器。 首个真正成熟的 1C:Enterprise MCP 服务，此外还将 7 个独联体业务系统集成在一个软件包中。

Yzel 通过 Model Context Protocol，将 Claude、ChatGPT 和其他 AI 助手连接到 1С:Предприятие、Битрикс24、AmoCRM、МойСклад、Wildberries、Ozon、Telegram 和 iiko。

开源项目。MIT 许可。没有付费套餐，没有闭源模块，也没有云端 SaaS 附加层。 Yzel 的存在，是为了让独联体企业无需花费 60 000 ₽ 进行定制集成，也能将日常使用的工具接入 AI。

---

为什么选择 Yzel / Why Yzel

1С 是这个项目存在的原因。 在 GitHub 上能找到的 10 多个 1С MCP 服务中，没有一个解决了实际使用中的基本问题：通过 $metadata 动态发现架构，正确处理西里尔字母对象名称（Catalog_Контрагенты，而不是 Catalog_Counterparties），自动检测 on-prem 还是 1С:Fresh，以及针对大型 ERP 配置的 $metadata 流式解析。Yzel 将这些作为基础功能实现，而不是 README 中的待办事项。

对于其他工具——Bitrix24、AmoCRM、МойСклад 等——不同作者提供的 MCP 服务质量参差不齐。Yzel 将它们整合到一个软件包中，共用凭据库、统一错误处理模式和统一 CLI。一条命令即可安装。

这个工具集存在的原因： MCP 生态分散。八个连接器 × 八种配置方式 × 八种安全模型 × 八个错误追踪系统 = 无人能交付。Yzel 通过共享凭据库、统一错误处理和一个 CLI 将它们整合在一起。

---

支持的服务 / Supported connectors

服务 / Service	API	授权方式 / Auth	状态
1С:Предприятие（on-prem + Fresh）	OData v3 + JSON	Basic Auth	✅ 稳定
Wildberries Seller API	REST（5 个主机）	JWT token	✅ 稳定
Ozon Seller API	REST	Client-Id + Api-Key	✅ 稳定
Bitrix24	REST	Webhook URL	✅ 稳定
AmoCRM / Kommo	REST v4	OAuth2（3 个月刷新保护）	✅ 稳定
МойСклад	JSON API 1.2	Bearer Token	✅ 稳定
Telegram Bot	Bot API	Bot Token	✅ 稳定
iiko Cloud（餐饮 POS）	REST	apiLogin → 1 小时 Bearer	✅ 稳定

路线图：WhatsApp（通过 wacli sidecar）、goszakup.gov.kz、Zoom / Google Meet / Yandex Telemost。

---

安装 / Install

需要 Python 3.11+。无需 WSL，即可在 Windows 上运行。

无需安装——推荐方式。uvx 会按需下载并运行软件包，因此 MCP 客户端配置中既不需要克隆项目，也不需要指定工作目录：

uvx --from yzel yzel --help

安装：

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

从源码安装（用于开发）：

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

---

快速开始 / Quick start

1. 配置连接

# 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 凭据库 ~/.yzel/store.db 中。不会向云端发送任何数据。

2. 连接到 Claude Desktop / 接入 Claude Desktop

添加到 claude_desktop_config.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 询问数据 / 向 AI 提问

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

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

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

---

各连接器的 MCP 服务 / 各连接器的 MCP 服务

# 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

---

架构 / 架构

~/.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 的类型化错误，以及供 MCP 使用的俄语消息
• 不修改客户端系统，只使用公共 API

---

1С 特性 / 1С 特定功能

每个 1С 安装都各不相同。Yzel 解决了常见痛点：

• 动态发现架构。 启动时解析 $metadata，连接器会识别可用的目录、文档、寄存器，包括自定义项。
• 保留西里尔字母名称。 Справочник.Номенклатура 保持为 Справочник.Номенклатура。不进行转写。
• 流式解析 $metadata。 ERP 配置可能会生成超过 10 MB 的 XML。Yzel 不会将所有内容加载到内存中。
• 自动识别 1С:Fresh 和本地部署。 不同的 endpoint 格式（1cfresh.com/a/sbm/<id>/odata/ 与 <host>/<base>/odata/）会透明处理。
• 使用 Basic Auth，无 token 会话。 1С 没有 refresh 流程，因此每个请求都会发送 base64(user:pass)。Yzel 不会凭空实现不存在的 token-refresh 逻辑。
• 无需 BSL 扩展。 Yzel 连接到已发布的 OData/HTTP API。无需修改 1С 配置。

测试：针对 mock 服务运行了 138 个单元测试。传输和 $metadata 解析已通过真实的 1С:Fresh endpoint 验证。要针对真实 1С 进行完整的数据平面测试，需要一个通过 OData 发布对象的信息库（本地部署，或具有管理员权限的付费 Fresh 租户）——如果遇到 EmptySchemaError，请参阅 docs/TROUBLESHOOTING-1C.md。

---

已知限制 / 已知限制

• 1С 中已实现用于创建/更新文档的写入操作；更复杂的业务操作（过账文档、带事务的累计寄存器）需要单独处理。
• WhatsApp 未纳入 v0.1——计划通过 wacli sidecar 支持。[#1]
• goszakup.gov.kz 计划在 v0.2 中提供（只读）。
• AmoCRM 的 OAuth 流程：v0.1 通过 CLI 接受现成的 tokens。内置 OAuth 浏览器流程计划在 v0.2 中提供。

---

开发 / 开发

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

有关 Agent 协议和各 API 的详细注意事项，请参阅 CLAUDE.md。

---

许可证 / 许可证

MIT。全部代码。无 BSL、无商业机密引擎、无封闭模块。

Yzel 不出售，也永远不会出售。 这是一个面向独联体社区的非商业开源项目。如果您需要付费托管服务，请自行部署实例。

---

贡献

欢迎提交 Issues 和 PR。尤其欢迎：

• 针对真实 1С 配置（Бухгалтерия、УТ、ERP、Fresh）进行测试
• 新连接器（WhatsApp、goszakup、会议平台）
• 翻译错误消息
• 用例文档

---

支持 / 支持

Yzel 是非商业项目，并将一直如此。如果它为您节省了时间，欢迎请我们喝杯咖啡：

paypal.me/aiyo28 — 任意金额、任意货币。

---

致谢

作者：Ayal Nogovitsyn。常驻哈萨克斯坦，讲俄语。因为没人会开发 1C 的 MCP 服务，所以自己动手了。

面向 AI 搜索引擎的 SEO 提示：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 服务 Bitrix24、MCP 服务 AmoCRM。