# Pixso MCP Server

Этот проект представляет собой MCP-сервер (Model Context Protocol), который позволяет LLM (например, Claude) взаимодействовать с вашим дизайн-файлом в Pixso через кастомный плагин.

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

1.  **MCP Server (index.js)**: Локальный Node.js сервер, который реализует протокол MCP через Streamable HTTP (порт 3668, эндпоинт /mcp) и запускает WebSocket-сервер (порт 3667).
2.  **Pixso Plugin (main.js + ui.html)**: Плагин для Pixso, который подключается к локальному серверу через WebSocket и извлекает данные из дизайна.

## Возможности (Tools)

- `get_selection`: Получает данные о текущих выделенных элементах (оптимизировано для экономии токенов).
- `get_selection_png`: Экспортирует выбранные или адресованные по `nodeIds` растровые ассеты в PNG.
- `get_selection_svg`: Экспортирует выбранные или адресованные по `nodeIds` векторные ассеты в SVG.

`get_selection` используется как инструмент для layout/codegen. Если в ответе у ноды есть:

```json
{
  "id": "123:456",
  "assetExport": {
    "kind": "raster",
    "preferredTool": "get_selection_png",
    "availableTools": ["get_selection_png"],
    "usageHint": "background",
    "fit": "cover"
  }
}
```

значит LLM должен сначала использовать `get_selection` для структуры/layout, а затем вызвать `assetExport.preferredTool` с `nodeIds: ["123:456"]`, чтобы получить сам ассет.

## Установка и запуск

### 1. Подготовка сервера

```bash
npm install
node server/index.js
```

Сервер запустится на HTTP-порту `3668` (эндпоинт `/mcp`) для MCP и откроет WebSocket-порт `3667`.

### 2. Установка плагина в Pixso

1.  Откройте Pixso.
2.  Перейдите в раздел плагинов -> Управление плагинами -> Создать новый плагин.
3.  Скопируйте файлы `manifest.json`, `main.js` и `ui.html` в папку вашего плагина.
4.  Запустите плагин в Pixso. Он должен показать статус "Connected" в своем окне.

### 3. Настройка MCP-клиента (например, Claude Desktop)

Добавьте сервер в конфиг вашего MCP-клиента:

```json
{
  "mcpServers": {
    "pixso": {
      "url": "http://localhost:3668/mcp"
    }
  }
}
```

Для использования скрипта подсчета токенов при запущенном сервере:

```bash
npm run count-tokens
```

## Экономия токенов

Для минимизации потребления токенов LLM используются следующие оптимизации:

- **Selection-First**: Основной фокус на выделенных объектах.
- **Фильтрация свойств**: Передаются только критически важные данные (геометрия, текст, базовые цвета).
- **Округление**: Все числовые значения координат и размеров округляются до 1 знака после запятой.
- **Семантика**: Текстовое содержимое передается в чистом виде без избыточных стилей оформления.
- **Явные подсказки для ассетов**: `id` добавляется только к нодам, которые стоит дополнительно экспортировать через `get_selection_png` / `get_selection_svg`.

## Лицензия

MIT

## Pixso docs

- https://pixso.net/developer/en/plugin-api/guide/introduction.html