﻿---
description: MCP-сервер VKUI — подключение AI-ассистентов к документации компонентов, хуков, примеров кода и миграций.
---

# MCP-сервер

MCP-сервер VKUI даёт AI-ассистентам (Cursor, Claude Desktop и другим клиентам с поддержкой [Model Context Protocol](https://modelcontextprotocol.io/)) доступ к актуальной документации: списку компонентов и хуков, их свойствам, примерам и рекомендациям по миграции на новые мажорные версии.

## Зачем нужен \[#why]

* **Подсказки по API** — свойства компонента, примеры использования и ссылка на документацию.
* **Миграция на новые мажорные версии** — рекомендации по обновлению кода по имени компонента или хука.
* **Примеры использования** — текстовые примеры по имени или slug компонента/хука.

Данные подгружаются из CDN MCP-данных VKUI, поэтому контент соответствует опубликованной документации выбранной версии.

## Что такое MCP \[#what-is-mcp]

[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) — открытый протокол для подключения AI-приложений к внешним данным и инструментам. Сервер предоставляет **инструменты (tools)** — функции, которые клиент может вызывать, и **ресурсы (resources)** — URI, по которым можно читать контент без вызова инструментов. VKUI MCP реализует и то, и другое.

## Подключение \[#setup]

### Подключение к MCP-клиенту \[#setup-client]

Для запуска MCP-сервера нужен установленный `Node.js`.

Добавьте сервер в `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "vkui": {
      "command": "npx",
      "args": ["-y", "@vkontakte/vkui-mcp"]
    }
  }
}
```

Подробности: [документация Cursor по MCP](https://cursor.com/docs/context/mcp#installing-mcp-servers).

Добавьте сервер через CLI VS Code:

```bash
code --add-mcp '{"name":"vkui","command":"npx","args":["-y","@vkontakte/vkui-mcp"]}'
```

Или используйте конфиг:

```json
{
  "mcpServers": {
    "vkui": {
      "command": "npx",
      "args": ["-y", "@vkontakte/vkui-mcp"]
    }
  }
}
```

Подробности: [документация VS Code по MCP](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server).

Добавьте сервер через CLI:

```bash
claude mcp add vkui npx -y @vkontakte/vkui-mcp
```

Подробности: [документация Claude Code по MCP](https://docs.claude.com/en/docs/claude-code/mcp).

Добавьте сервер в `~/.codex/config.toml`:

```toml
[mcp_servers.vkui]
command = "npx"
args = ["-y", "@vkontakte/vkui-mcp"]
```

Подробности: [документация Codex по MCP](https://github.com/openai/codex/blob/main/docs/config.md#mcp_servers).

Добавьте сервер через CLI:

```bash
gemini mcp add vkui npx -y @vkontakte/vkui-mcp
```

Подробности: [документация Gemini CLI по MCP](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md#how-to-set-up-your-mcp-server).

Добавьте сервер в конфиг вашего MCP-клиента (файл и схема зависят от клиента):

```json
{
  "mcpServers": {
    "vkui": {
      "command": "npx",
      "args": ["-y", "@vkontakte/vkui-mcp"]
    }
  }
}
```

Опция `-y` у `npx` разрешает автоматическую установку пакета при первом запуске.

### Установка в проект \[#setup-install]

Если нужно зафиксировать версию в проекте:

```bash
npm install -D @vkontakte/vkui-mcp
# или
yarn add -D @vkontakte/vkui-mcp
```

После этого в конфиге MCP укажите локальный бинарник:

```json
{
  "mcpServers": {
    "vkui": {
      "command": "node",
      "args": ["node_modules/@vkontakte/vkui-mcp/dist/cli.js"]
    }
  }
}
```

## Переменные окружения \[#env]

| Переменная     | Описание                                                                                                                      |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `DATA_URL`     | Базовый URL MCP-данных. По умолчанию используется `https://vkui-mcp.cdn-vk.ru`.                                               |
| `VKUI_VERSION` | Версия библиотеки в MCP-данных. По умолчанию `latest`. Данные всегда запрашиваются по адресу `{DATA_URL}/{VKUI_VERSION}/...`. |

Поддержка `VKUI_VERSION`:

* Для v7 доступны: `7.5.4`, `7.6.4`, `7.7.2`, `7.8.2`, `7.9.2`, `7.10.2`, `7.11.7`.
* Для v8 доступны: все версии начиная с `8.0.1`.

В Cursor и других клиентах переменные окружения для MCP-сервера задаются в конфиге. Пример с версией vkui:

```json
{
  "mcpServers": {
    "vkui": {
      "command": "npx",
      "args": ["-y", "@vkontakte/vkui-mcp"],
      "env": {
        "VKUI_VERSION": "8.1.0"
      }
    }
  }
}
```

## Инструменты (Tools) \[#tools]

Инструменты вызываются клиентом по запросу пользователя или модели.

### Компоненты

| Инструмент               | Описание                                                                                                      |
| ------------------------ | ------------------------------------------------------------------------------------------------------------- |
| `list_components`        | Список всех компонентов (имя, slug, описание, количество примеров, теги).                                     |
| `get_component_metadata` | Карточка компонента: описание и пропсы. Параметры: `name` (например `Button`) или `slug` (например `button`). |

### Теги \[#tags]

Теги — прикладная категоризация компонентов с точки зрения задач разработки (например, `form`, `modal`, `navigation`). Позволяют быстро найти подходящий компонент по типу задачи.

> Доступно начиная с VKUI **8.2.0**. На более ранних версиях запросы к этим инструментам и поле `tags` в `list_components` отсутствуют. Задайте `VKUI_VERSION` равной `8.2.0` или новее (либо оставьте значение `latest` по умолчанию).

| Инструмент               | Описание                                                                                       |
| ------------------------ | ---------------------------------------------------------------------------------------------- |
| `list_tags`              | Список всех доступных тегов.                                                                   |
| `list_components_by_tag` | Список компонентов с указанным тегом. Параметр `tag` — например `form`, `modal`, `navigation`. |

### Хуки

| Инструмент          | Описание                                                                |
| ------------------- | ----------------------------------------------------------------------- |
| `list_hooks`        | Список всех хуков (имя, slug, описание, количество примеров).           |
| `get_hook_metadata` | Карточка хука: описание, пропсы, примеры. Параметры: `name` или `slug`. |

### Примеры кода

| Инструмент     | Описание                                                                                                             |
| -------------- | -------------------------------------------------------------------------------------------------------------------- |
| `get_examples` | Текст с примерами использования компонента/хука. Параметры: `name` (например `Alert`) или `slug` (например `alert`). |

### Документация

> Доступно начиная с VKUI **8.3.0**. На более ранних версиях запросы к этим инструментам отсутствуют. Задайте `VKUI_VERSION` равной `8.3.0` или новее (либо оставьте значение `latest` по умолчанию).

| Инструмент | Описание                                                                                                                          |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `get_docs` | Полная документация компонента или хука в формате Markdown. Параметры: `name` (например `Button`) или `slug` (например `button`). |

### Миграция на новые мажорные версии

| Инструмент               | Описание                                                                                                                                       |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_migration_targets` | Список имён компонентов и хуков, для которых есть рекомендации по миграции на следующую мажорную версию (сейчас — v8).                         |
| `get_migration_target`   | Рекомендации по миграции для одного компонента/хука. Параметр `name` — имя из списка целей миграции. Возвращает фрагменты кода «до» и «после». |

Пример миграции на конкретную версию и готовые промпты см. в документации: [Миграция с v7 на v8](/migrations/migration-v8).

## Ресурсы (Resources) \[#resources]

Ресурсы подключают данные по URI без вызова инструментов — удобно подставлять контекст «как файл».

| URI                       | Описание                                                                                                                                                      |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `vkui://migration/v8`     | Статический ресурс: обзор миграции на v8 и список всех целей миграции (JSON).                                                                                 |
| `vkui://component/{slug}` | Карточка компонента по slug (например `vkui://component/button`). В списке ресурсов отображаются все компоненты; автодополнение по slug.                      |
| `vkui://migration/{name}` | Рекомендации по миграции для одного компонента или хука по имени (например `vkui://migration/Button`). В списке — все цели миграции; автодополнение по имени. |

Использование ресурсов зависит от клиента: в Cursor их можно добавлять в контекст через список ресурсов или по URI.

## Итог \[#summary]

* В Cursor и других MCP-клиентах укажите команду запуска в конфиге MCP.
* Инструменты — для списков, метаданных, примеров и миграции; ресурсы — для чтения контекста по URI.
* При необходимости задайте `DATA_URL` и/или `VKUI_VERSION` в `env` MCP-конфига.
