docs(build-system/docs-template): add MCP and CLI consumer guides

build-system/docs-template/common-template/docs/cli.md

@@ -0,0 +1,118 @@
+---
+id: cli
+title: Использование DS Builder CLI
+sidebar_position: 2
+---
+
+## Зачем
+
+`dsbuilder` — CLI design-system-builder для локальной работы с проектом дизайн-системы. Он хранит `project-id` и `design-system-id` в локальном `.sdds/config.json` — не нужно передавать их в каждом вызове, в том числе при запуске MCP-сервера.
+
+Эта страница описывает только consumer-сценарий: установку, привязку локального проекта, проверку доступа и загрузку актуальных темы и конфигурации компонентов. Команды, которые публикуют изменения обратно в дизайн-систему (`components push`, `docs publish`), сюда не входят — это отдельный сценарий для мейнтейнеров дизайн-системы.
+
+## Установка
+
+CLI распространяется как release-архив на GitHub Releases `design-system-builder` (на данный момент — только macOS).
+
+```bash
+unzip dsbuilder-cli-macos-arm64.zip
+cd dsbuilder-cli-macos-arm64
+./install.sh
+```
+
+По умолчанию скрипт устанавливает бинарник в `~/.dsbuilder/cli/macos/dsbuilder` и создаёт symlink `~/.local/bin/dsbuilder`. Если `~/.local/bin` не входит в `PATH`, добавьте его:
+
+```bash
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+Проверка установки:
+
+```bash
+dsbuilder --version
+```
+
+## Инициализация проекта
+
+Команда `init` создаёт локальный конфиг `.sdds/config.json` в текущей директории. Запускайте её из корня проекта, в котором будет использоваться дизайн-система, указав платформу — тогда её не нужно будет передавать при каждом вызове:
+
+```bash
+dsbuilder init --project-id <project-id> --design-system-id <design-system-id> --platform compose
+```
+
+Для проектов на View-компонентах используйте `android-view`:
+
+```bash
+dsbuilder init --project-id <project-id> --design-system-id <design-system-id> --platform android-view
+```
+
+`<project-id>` и `<design-system-id>` — идентификаторы вашего проекта в DS Builder.
+
+## Авторизация
+
+По умолчанию CLI ожидает API key в переменной окружения `DSBUILDER_API_KEY`:
+
+```bash
+export DSBUILDER_API_KEY="dev-token"
+```
+
+Имя переменной можно сохранить в конфиге проекта через `--api-key-env` при `init`:
+
+```bash
+dsbuilder init \
+  --project-id <project-id> \
+  --design-system-id <design-system-id> \
+  --api-key-env DSB_DEV_API_KEY
+```
+
+Если project API key недоступен, можно использовать пользовательскую сессию:
+
+```bash
+dsbuilder auth login --username <username>
+```
+
+## Проверка доступа
+
+```bash
+dsbuilder status
+```
+
+Команда проверяет доступ к настроенному проекту и дизайн-системе с текущими учётными данными.
+
+## Загрузка темы
+
+Команда `theme fetch` загружает актуальную тему из DS Builder API и записывает её в локальные `.sdds`-файлы согласно конфигу проекта:
+
+```bash
+dsbuilder theme fetch
+```
+
+## Загрузка конфигов компонентов
+
+Команда `components fetch` выгружает конфигурацию компонентов дизайн-системы в локальную директорию `.sdds/components`:
+
+```bash
+dsbuilder components fetch
+```
+
+## Генерация кода
+
+Команды `theme generate` и `components generate` превращают загруженные `theme fetch`/`components fetch` данные в код темы и компонентов — CLI делегирует эту работу платформенному инструменту (для Android — тому же Gradle-плагину, что уже используется в этом репозитории):
+
+```bash
+dsbuilder theme generate
+dsbuilder components generate
+```
+
+Платформа берётся из `.sdds/config.json` (см. `dsbuilder init`); если она не объявлена или проект ведёт несколько платформ, укажите её явно:
+
+```bash
+dsbuilder theme generate --platform compose
+```
+
+## MCP-сервер
+
+CLI умеет поднимать MCP-сервер с постоянным локальным контекстом проекта — не нужно передавать `project-id`/`design-system-id` в каждом запросе. Команду `dsbuilder mcp serve` обычно не запускают вручную — её вызывает сам MCP-клиент по своей конфигурации.
+
+За конфигурацией MCP-клиента и списком доступных инструментов — см. [MCP](mcp.md).

build-system/docs-template/common-template/docs/mcp.md

@@ -0,0 +1,44 @@
+---
+id: mcp
+title: Агентская разработка с DS Builder MCP
+sidebar_position: 3
+---
+
+## Зачем
+
+MCP (Model Context Protocol) даёт вашему AI-агенту в IDE (Cursor, Claude Code, Windsurf и другим MCP-совместимым клиентам) прямой доступ к дизайн-системе: агент может искать документацию, читать токены и конфигурации компонентов, не полагаясь на то, что вы вручную скопируете нужный фрагмент в чат.
+
+Инструменты доступны только для чтения — агент не может опубликовать или изменить что-либо в дизайн-системе через MCP.
+
+## Быстрый старт
+
+1. Установите и настройте CLI `dsbuilder` — установка, `dsbuilder init` и авторизация описаны на странице [CLI](cli.md).
+
+2. Добавьте сервер в конфигурацию вашего MCP-клиента. Например, для Claude Code (`.mcp.json`) или Cursor (`mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "dsbuilder": {
+      "command": "dsbuilder",
+      "args": ["mcp", "serve"]
+    }
+  }
+}
+```
+
+Клиент сам запускает `dsbuilder mcp serve` по этой конфигурации — запускать его отдельно не нужно. CLI уже знает `project-id` и `design-system-id` из локального `.sdds/config.json`, поэтому в запросе к агенту их указывать не нужно.
+
+После перезапуска клиента агент увидит инструменты дизайн-системы в списке доступных MCP tools.
+
+## Доступные инструменты
+
+Первая версия MCP-сервера предоставляет только read-only инструменты:
+
+- **Контекст**: `design_system_get_context`, `project_get_status`
+- **Документация**: `documentation_search`, `documentation_fetch`, `documentation_get_navigation`, `documentation_get_page`
+- **Ссылки на код**: `code_binding_search`, `code_binding_get`
+- **Токены**: `tokens_list`, `token_get`, `token_values_get`
+- **Компоненты**: `components_list`, `component_get`, `component_config_get`, `component_styles_get`, `component_variations_get`
+
+Ни один из этих инструментов не публикует и не изменяет дизайн-систему.

build-system/docs-template/common-template/sidebars.ts

@@ -15,6 +15,8 @@ import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
 const sidebars: SidebarsConfig = {
   tutorialSidebar: [
       'quick_start',
+      'cli',
+      'mcp',
       {
         type: 'category',
         label: 'Тема',

build-system/docs-template/compose-template/docs/quick_start.md

@@ -116,6 +116,14 @@ fun YourAppTheme(
 
 Для обычного использования готовых компонентов Motion API знать не обязательно, но он важен для разработки новых компонентов и сложной кастомизации.
 
+### 7. CLI
+
+Если нужен постоянный локальный контекст проекта или загрузка темы и конфигурации компонентов из терминала, прочитайте [CLI](cli.md) — инструкцию по установке и использованию `dsbuilder`.
+
+### 8. MCP
+
+Если хотите подключить к дизайн-системе AI-агента в IDE (Cursor, Claude Code и другие MCP-клиенты), прочитайте [MCP](mcp.md). Агент получит доступ к документации, токенам и компонентам через CLI `dsbuilder`.
+
 ### Минимальный маршрут
 
 Если времени мало, прочитайте:

build-system/docs-template/compose-template/sidebars.ts

@@ -15,6 +15,8 @@ import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
 const sidebars: SidebarsConfig = {
   tutorialSidebar: [
       'quick_start',
+      'cli',
+      'mcp',
       {
         type: 'category',
         label: 'Тема',

build-system/docs-template/xml-template/docs/quick_start.md

@@ -18,4 +18,14 @@ implementation("io.github.salute-developers:sdds-icons:{{ docs-iconsVersion }}")
 ```xml
  <style name="YourAppTheme" parent="{{ docs-theme-codeReference }}"> ... </style>
 ```
-3. Готово
+3. Готово
+
+## Что прочитать дальше
+
+### CLI
+
+Если нужен постоянный локальный контекст проекта или загрузка темы и конфигурации компонентов из терминала, прочитайте [CLI](cli.md) — инструкцию по установке и использованию `dsbuilder`.
+
+### MCP
+
+Если хотите подключить к дизайн-системе AI-агента в IDE (Cursor, Claude Code и другие MCP-клиенты), прочитайте [MCP](mcp.md). Агент получит доступ к документации, токенам и компонентам через CLI `dsbuilder`.

build-system/docs-template/xml-template/sidebars.ts

@@ -15,6 +15,8 @@ import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
 const sidebars: SidebarsConfig = {
   tutorialSidebar: [
       'quick_start',
+      'cli',
+      'mcp',
       {
         type: 'category',
         label: 'Тема',

openspec/changes/archive/2026-09-23-add-mcp-cli-docs-template/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-22