# Webasyst MCP Server

> **For Claude Desktop and Cursor.** This repository is the Claude/Cursor-oriented Webasyst MCP server.
>
> **Unofficial project.** This MCP server is community-maintained and is not affiliated with, endorsed by, or sponsored by Webasyst.
>
> If you use Codex, use the Codex-first server instead: [emmy-design/webasyst-codex-mcp](https://github.com/emmy-design/webasyst-codex-mcp).

[![npm version](https://img.shields.io/npm/v/webasyst-mcp-server.svg)](https://www.npmjs.com/package/webasyst-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

MCP (Model Context Protocol) server for [Webasyst](https://github.com/webasyst) framework. Provides development tools for apps, plugins, themes and configuration via AI interface.

> 📝 **Note:** Documentation is primarily in Russian.

---

MCP (Model Context Protocol) сервер для работы с фреймворком [Webasyst](https://github.com/webasyst). Предоставляет инструменты для разработки приложений, плагинов, тем и конфигурации через AI-интерфейс.

> **Неофициальный проект.** MCP-сервер поддерживается сообществом и не является официальным продуктом Webasyst.

## Создавайте проекты Webasyst через AI

Создавайте приложения, плагины, темы дизайна и backend-интерфейсы Webasyst UI 2.0 с помощью Claude Desktop и Cursor. Этот MCP-сервер дает AI-ассистенту структурированные инструменты для изучения локальной установки Webasyst, генерации каркасов, чтения реальных UI-примеров и проверки шаблонов после правок.

Проект заточен под Webasyst-разработку: при создании backend UI он должен опираться на реальные паттерны Webasyst UI 2.0 из `wa-apps/ui/templates/actions/component/`, а не на Bootstrap, Tailwind или случайную стороннюю дизайн-систему.

## Для кого это?

- Для разработчиков, которые создают приложения, плагины, виджеты, темы и расширения Shop-Script под Webasyst.
- Для вайб-кодеров, которые хотят быстро прототипировать Webasyst-функции через AI-ассистента, но не отходить от структуры и соглашений платформы.
- Для команд, которым нужно превращать продуктовые идеи в настройки, таблицы, формы, диалоги и локализованный backend UI.
- Для интеграторов Webasyst, которым нужны повторяемые заготовки, подсказки по UI 2.0 и базовая проверка результата.

## Первый плагин за 5 минут

1. Установите MCP-сервер и подключите его к Claude Desktop или Cursor.
2. Откройте локальный проект Webasyst.
3. Попросите AI-ассистента создать плагин, страницу настроек или UI-компонент.
4. Перед UI-задачей попросите использовать контекст Webasyst UI 2.0.
5. После правок попросите проверить шаблоны на соответствие Webasyst UI 2.0.

## Примеры промптов

```
Создай плагин Shop-Script "loyalty" со страницей настроек на Webasyst UI 2.0
```

```
Перед правкой backend-страницы посмотри реальные примеры Webasyst UI для fields, table, button и dialog
```

```
Сделай форму настроек плагина через .fields, .button и стандартные паттерны Webasyst UI 2.0
```

```
Проверь этот Smarty-шаблон на совместимость с Webasyst UI 2.0 и исправь проблемы
```

```
Создай виджет для приложения Site с локализацией и frontend assets
```

```
Сгенерируй структуру приложения Webasyst для прототипа CRM
```

```
Адаптируй этот экран под реальные компоненты dropdown и dialog из wa-apps/ui
```

```
Подготовь релизный архив плагина после базовой проверки структуры и локализации
```

## Стандарты разработки

**ВАЖНО:** Перед началом работы обязательно ознакомьтесь со [СТАНДАРТАМИ РАЗРАБОТКИ](DEVELOPMENT_STANDARDS.md)
Также перед ревью используйте чек-лист: [PR_CHECKLIST.md](PR_CHECKLIST.md)

## Возможности

### Управление приложениями
- Получение списка всех приложений
- Детальная информация о приложениях
- Создание структуры новых приложений

### Работа с плагинами
- Список плагинов для каждого приложения
- Информация о конкретных плагинах
- Создание структуры новых плагинов

### Управление темами
- Список доступных тем для приложений
- Информация о темах оформления

### Конфигурация
- Системная конфигурация
- Конфигурация маршрутизации
- Настройки приложений

### CLI интерфейс
- Выполнение команд через CLI Webasyst
- Автоматизация задач разработки

## Установка

### Вариант 1: Через npm (рекомендуется)

```bash
npm install -g webasyst-mcp-server
```

### Вариант 2: Из исходников

1. Клонируйте репозиторий:
   ```bash
   git clone https://github.com/emmy-design/webasyst-mcp.git
   cd webasyst-mcp
   ```

2. Установите зависимости:
   ```bash
   npm install
   ```

3. Сделайте файл исполняемым:
   ```bash
   chmod +x webasyst-mcp.js
   ```

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

### Запуск сервера
```bash
npm start
```

### Интеграция с Claude Desktop

Добавьте следующую конфигурацию в файл `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "webasyst": {
      "command": "node",
      "args": ["/путь/к/вашему/проекту/webasyst-mcp/webasyst-mcp.js"],
      "env": {}
    }
  }
}
```

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

**Информация**
- `list_webasyst_apps` — приложения (include_system).
- `get_app_info` — детали приложения (app_id).
- `list_app_plugins`, `get_plugin_info` — плагины приложения (app_id, plugin_id).
- `list_app_themes`, `list_app_widgets` — темы/виджеты приложения (app_id).
- `get_routing_config` — маршрутизация (app_id опционально).
- `get_system_config` — системная конфигурация.
- `run_webasyst_cli` — запуск `cli.php` (command, args).

**Создание (базовое)**
- `create_app_structure`, `create_plugin_structure`.
- `create_action`, `create_model`, `create_theme`, `create_widget` (Dashboard).
- `create_generic_app` — приложение в произвольном пути.

**Site**
- `create_site_plugin`, `create_site_widget`, `create_site_block`, `create_site_theme`.

**Shop**
- `create_shop_plugin`, `create_shop_theme`, `create_shop_report`.
- `create_shipping_plugin` (wa-plugins/shipping), `create_payment_plugin` (wa-plugins/payment).

**UI**
- `enable_webasyst_ui` — подключение UI 2.0.
- `create_ui_component` — таблица/форма/модалка и др.

**SEO и аналитика**
- `setup_seo_optimization`, `analyze_project`.
- `generate_po_template`, `compile_mo`, `check_project_compliance`, `prepare_release_bundle`.

**DevOps**
- `generate_nginx_vhost`, `generate_htaccess`.

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

После интеграции с Claude Desktop вы можете использовать следующие команды:

```
Покажи мне все приложения Webasyst
```

```
Создай новое приложение с ID "myapp" и названием "Мое приложение"
```

```
Покажи информацию о приложении "shop"
```

```
Создай плагин "analytics" для приложения "shop" с названием "Аналитика продаж"
```

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

```
webasyst-mcp/
├── webasyst-mcp.js    # Основной файл MCP сервера
├── package.json       # Конфигурация npm пакета
├── README.md          # Документация
└── node_modules/      # Зависимости (после npm install)
```

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

- Node.js >= 18.0.0
- Проект Webasyst с корректной структурой директорий
- Права на чтение/запись в директории проекта

## Особенности для дизайнеров

Этот MCP сервер особенно полезен для дизайнеров и продуктовых менеджеров, работающих с Webasyst:

- **Простой интерфейс**: Все команды выполняются через естественный язык в Claude
- **Автоматизация**: Создание структуры приложений и плагинов одной командой
- **Безопасность**: Все изменения сохраняются только локально в git
- **Интуитивность**: Не требует глубоких знаний PHP - достаточно базового понимания HTML/CSS
- **UI гайдлайны**: Рекомендации по использованию Webasyst UI 2.0 (см. [UI_COMPONENTS_REFERENCE.md](UI_COMPONENTS_REFERENCE.md))
- **Локализация**: Правила и стандарты локализации Webasyst (см. [LOCALIZATION_GUIDE.md](LOCALIZATION_GUIDE.md))

## Стилизация интерфейса (UI 2.0)

### ОБЯЗАТЕЛЬНОЕ ТРЕБОВАНИЕ:
**При создании интерфейсов ВСЕГДА используйте:**
1. **Компоненты из `wa-apps/ui/`** - готовые шаблоны и примеры
2. **Классы из `wa-content/css/wa/wa-2.0.css`** - основные стили системы
3. **CSS-переменные** вместо хардкода цветов

- **Где смотреть примеры**: `wa-apps/ui/templates/actions/component/`
  > Если приложение UI не установлено, установите его через Инсталлер (`?module=store&action=product&slug=ui`)
- **Основные стили**: `wa-content/css/wa/wa-2.0.css`
- **Полный справочник компонентов**: [UI_COMPONENTS_REFERENCE.md](UI_COMPONENTS_REFERENCE.md)
- **Чек-лист PR**: [PR_CHECKLIST.md](PR_CHECKLIST.md)
- **Быстрая навигация по компонентам**:
  - **Переключатели**: `switch.html`, `toggle.html`
  - **Селекты и выпадающие списки**: `dropdown.html`, `inputs.html`
  - **Таблицы**: `table.html`, `tablebox.html`
  - **Карточки**: `card.html`
  - **Кирпичи/brick-сетка**: `bricks.html`
  - **Загрузка и прогресс**: `loading.html`, `spinner.html`, `progressbar.html`
  - **Диалоги и выдвижные панели**: `dialog.html`, `drawer.html`, `tooltip.html`

- **Подключение базовых стилей UI**:

```smarty
{include file="ui_wrapper.html"}
```

или вручную в layout:

```html
<link rel="stylesheet" href="{$wa_app_static_url}wa-ui-variables.css">
```

- **Рекомендации**:
  - Для JS старайтесь искать элементы по `id`, а не по классам
  - Минимизируйте кастомные стили; используйте CSS-переменные UI 2.0
  - Опираться на готовую разметку из файлов в `wa-apps/ui/templates/actions/component/`

Подробнее: [UI_COMPONENTS_REFERENCE.md](UI_COMPONENTS_REFERENCE.md)

## Поддержка

Если у вас возникли вопросы или проблемы:
1. Проверьте, что вы находитесь в корневой директории проекта Webasyst
2. Убедитесь, что Node.js установлен и имеет версию 18+
3. Проверьте права доступа к файлам проекта

## Авторы

- **Vlad Arkhipov** — создатель и основной разработчик

*Проект создан с использованием AI-ассистентов (Claude, Cursor).*

## Благодарности

Проект создан на основе официальных материалов [Webasyst](https://www.webasyst.ru/):

- [Документация разработчика](https://developers.webasyst.ru/docs/) — использовалась как база для стандартов и структуры генерируемого кода
- [Приложение UI](https://www.webasyst.ru/store/app/ui/) — дизайн-система Webasyst 2.0, на основе которой создан справочник компонентов

## Участие в разработке

Мы приветствуем вклад в проект! См. [CONTRIBUTING.md](CONTRIBUTING.md) для деталей.

## Лицензия

MIT License — см. файл [LICENSE](LICENSE)