# maketka-mcp — помощник наставника «Макетки»

Подключает вашу ИИ-программу к «Макетке» (`cad.cmit.ru`): она видит работы ваших групп,
собирает черновики разборов, придумывает задания и строит 3D-модели прямо в открытой
мастерской. Имён и текстов детей она не видит — только фигуры и числа.

*This is the MCP server for Maketka (`cad.cmit.ru`), a Russian-language browser 3D
modelling service for school clubs. It lets a teacher's MCP-capable AI client read
anonymized student work, draft lesson reviews and build 3D models in the editor.
Documentation and the service itself are in Russian: <https://cad.cmit.ru/docs>.*

## Быстрый старт

Понадобится: программа, которая умеет подключать MCP-серверы (список ниже),
[Node.js](https://nodejs.org) версии 18 или новее, [Git](https://git-scm.com) — помощник
ставится прямо из этого репозитория — и код доступа.

1. **Код доступа.** В кабинете наставника: **«ИИ-помощник» → «Выдать код доступа»**.
   Код показывается один раз, начинается с `mk_`. Скопируйте его сразу.
2. **Настройки.** Найдите ниже блок под свою программу, вставьте его в её файл настроек
   и замените `mk_ВАШ_КОД` на свой код. Перезапустите программу.
3. **Проверка.** Напишите в чат: **«проверь подключение к Макетке»**. В ответе должны быть
   ваша роль и список групп. После этого спрашивайте про работы: «покажи работы группы…».

Если групп в ответе нет — помощник не включён ни у одной вашей группы; это включает
администратор. Остальные заминки — в разделе [«Если не работает»](#если-не-работает).

## Настройка по программам

Во всех блоках одно и то же: команда `npx`, адрес репозитория с закреплённой меткой
версии и ваш код доступа в переменной `MAKETKA_TOKEN`. Готовые файлы — в каталоге
[`examples/`](examples/README.md).

**Версия закреплена намеренно.** На вашем компьютере лежит код доступа, поэтому тянуть
из сети свежий код при каждом запуске мы не предлагаем. Когда выйдет новая версия,
помощник скажет об этом одной фразой в ответе на проверку подключения — тогда поменяйте
метку после `#`.

**Первый запуск дольше остальных:** `npx` забирает репозиторий и ставит зависимости.
Дальше он берёт своё из кэша.

### Настольное приложение помощника (Claude Desktop)

Файл `claude_desktop_config.json`: Windows — `%APPDATA%\Claude\`,
macOS — `~/Library/Application Support/Claude/`.

```json
{
  "mcpServers": {
    "maketka": {
      "command": "npx",
      "args": ["-y", "github:cmit-ru/maketka-mcp#v0.3.0"],
      "env": { "MAKETKA_TOKEN": "mk_ВАШ_КОД" }
    }
  }
}
```

### Cursor

Файл `~/.cursor/mcp.json` (или `.cursor/mcp.json` рядом с проектом) — блок тот же,
что выше.

### VS Code с ИИ-режимом

Файл `.vscode/mcp.json` в папке проекта. Здесь раздел называется `servers`, и нужен
`type`:

```json
{
  "servers": {
    "maketka": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "github:cmit-ru/maketka-mcp#v0.3.0"],
      "env": { "MAKETKA_TOKEN": "mk_ВАШ_КОД" }
    }
  }
}
```

### JetBrains AI Assistant

Настройки → Tools → AI Assistant → Model Context Protocol → Add → **As JSON** — и тот же
блок с `mcpServers`.

### Claude Code

Одной командой, файл править не нужно:

```bash
claude mcp add maketka --env MAKETKA_TOKEN=mk_ВАШ_КОД -- npx -y github:cmit-ru/maketka-mcp#v0.3.0
```

### Gemini CLI

Файл `~/.gemini/settings.json` — блок с `mcpServers`, как в первом примере.

### Что проверено руками

| Программа | Как подключается | Проверено |
|---|---|---|
| Настольное приложение помощника | файл настроек | — |
| VS Code с ИИ-режимом | файл настроек | — |
| Cursor | файл настроек | — |
| JetBrains AI Assistant | настройки, JSON | — |
| Claude Code | команда | — |
| Gemini CLI | файл настроек | — |

Блоки собраны по документации самих программ; дата ручной проверки появится в этой
таблице по мере проверок. Программа, которой в списке нет, но которая умеет MCP по stdio,
скорее всего подойдёт — блок для неё тот же.

**Про программы без установки.** Сейчас помощник запускается только теми программами,
которые умеют запустить его у вас на компьютере. Веб-чаты и облачные студии так не умеют:
им нужен удалённый адрес, и это отдельная работа. Отдельно стоит знать, что у веб-чатов
подключение своих источников доступно не на всех тарифах, и оплачивает его тот, кто
подключает.

## Что помощник умеет

| Инструмент | Что делает |
|---|---|
| `check` | проверка подключения: чей код, какие группы видны, включён ли в них помощник, версии и предел частоты |
| `groups` | группы наставника: название, сколько учеников, включён ли помощник |
| `works` | работы группы: номер ученика, карточка урока, объём, время сохранения |
| `work` | одна работа: обезличенная структура фигур, объём, габариты, шаги карточки и превью картинкой |
| `scene` | то же без картинки — дешёвый вызов перед правкой модели и после неё |
| `review_batch` | пакет проверки: уроки, ждущие разбора, со снимками всех работ |
| `report_save` | сохранить черновик разбора в кабинет строками «ученик — вердикт — комментарий» |
| `card_create` | придумать задание: карточка урока с шагами и проверками, всегда выключенная до вашей проверки |
| `project_create` | создать свою работу — например, образец к уроку |
| `handout` | раздать свой образец группе: каждому ученику своя копия |
| `ops_build` | построить или доработать модель в работе — на глазах у того, кто открыл её в браузере |
| `ops_status` | как идёт построение и что получилось: число тел, габариты, объём |
| `snapshot` | свежий кадр сцены, при желании с нужного ракурса или с пронумерованными рёбрами |
| `circuit_ops` | собрать или поправить схему: детали, провода, настройки детали, программа |
| `circuit_check` | проверить схему, ничего не меняя: что не так со сборкой и с электрикой |

Разбор, который вы видите в чате, — **черновик**. Ученику попадает только то, что вы
подтвердили в кабинете.

## Чего помощник не умеет

- **Не видит имён.** Ни имени, ни личного кода, ни адреса почты, ни названия, которое
  ребёнок придумал сам. В данных стоит «ученик №5»; имена подставляет только кабинет.
- **Не меняет и не удаляет работы учеников** — ни по просьбе, ни по ошибке. Строить в
  детской работе можно только после того, как наставник нажал «Править».
- **Не ставит оценок** и ничего не отправляет детям.
- **Не работает с группами, где его не включили.** Флаг у группы проверяется на каждом
  вызове.
- **Не работает у ученика.** Код доступа выдаётся только взрослой учётной записи; у
  ребёнка кода доступа не бывает.
- **Не строит в закрытом браузере.** Построение модели и свежий снимок доигрывает вкладка
  с открытой работой; если её нет, пакет ждёт своей очереди. Схему помощник собирает и без
  открытой вкладки, но картинка схемы в кабинете обновится только после того, как работу
  откроют в браузере.
- **Не собирает программу в прошивку** и не запускает схему: он видит, что в ней собрано и
  что написано, но не проверяет её в работе.

## О чём его спрашивать

- «Проверь подключение к Макетке.»
- «Покажи мои группы.»
- «Что сохранили во вторничной группе на этой неделе?»
- «Разбери занятие: у кого получилось, у кого застряло. Сохрани черновик разбора.»
- «Открой работу 128 и скажи, соответствует ли она шагам карточки.»
- «Придумай задание на 45 минут: брелок с отверстием. Шаги — словами для ребёнка.»
- «Создай образец „подставка под телефон“, построй его и раздай группе 3.»
- «Построй в работе 86 пружину и покажи, как это выглядит сверху.»
- «Покажи схемы вторничной группы и скажи, у кого светодиод стоит без резистора.»
- «Собери в моей схеме 91 мигающий светодиод на 13-м выводе и напиши программу.»

Фразы можно говорить своими словами: помощник выбирает инструмент сам.

## Если не работает

| Что видите | Что проверить |
|---|---|
| «не нашёл сервер», «не удалось запустить» | стоит ли Node.js версии 18+ и Git (`git --version` в командной строке); на Windows — замену `npx` на `cmd /c npx` (см. [`examples/`](examples/README.md)) |
| «код доступа не подошёл» | код скопирован целиком, вместе с `mk_`; не выдавали ли новый код после настройки |
| «код доступа отозван» | выдайте новый в кабинете и поправьте настройки |
| групп нет, список пустой | включён ли помощник у вашей группы (это делает администратор) |
| «для этой группы помощник не включён» | то же самое: флаг у группы |
| «такой работы нет» | работа не из ваших групп или удалена |
| «слишком много запросов» | подождите минуту: помощник спросил слишком часто |
| «эта работа сейчас никем не открыта» | откройте работу в браузере — построение доигрывает вкладка |
| «нужно обновить помощника» | поставьте новую версию: в настройках поменяйте метку после `#` |

Не нашли свой случай — напишите на `cad@cmit.ru`, приложите то, что ответила программа.
**Код доступа в письмо не вставляйте.**

## Безопасность

- **Что уходит вашей ИИ-программе:** номера учеников, типы фигур и числа (размеры, объём,
  габариты), названия групп и карточек — наш текст, а не детский, — и превью-картинки
  работ. Имена, личные коды, адреса почты и строки, которые набирал ребёнок, не уходят
  никогда: их отсекает сам сервис, до отправки. Попросить помощника «всё-таки показать
  имена» невозможно — по ту сторону их нет.
- **Права разбираются на нашей стороне.** Код доступа даёт ровно ваши группы. Чужая работа
  по номеру отвечает «такой работы нет». Правку своего клиента это не обходит.
- **Код доступа — как пароль.** Он лежит открытым текстом в файле настроек вашей
  программы: держите файл в своём профиле, не выкладывайте его и не показывайте на
  проекторе. Новый код заменяет старый и ломает настройки на других компьютерах.
- **Утёк — отзовите.** Кабинет, «ИИ-помощник» → «Выдать новый». Старый перестаёт
  работать сразу.
- **Предел частоты примерный.** Он считается на нашей стороне (порядка сотни вызовов в
  минуту) и может обнулиться при обновлении сервиса. Это защита сервиса от лавины
  запросов, а не тариф.
- Про дыры в безопасности — [SECURITY.md](SECURITY.md).

Как сервис вообще обращается с данными детей — в политике: <https://cad.cmit.ru/privacy>.

## Замечания и правки

Замечания и вопросы принимаем: `cad@cmit.ru` или обсуждение в репозитории. Ответим в
разумный срок, срок не обещаем.

**Чужие правки кодом не принимаем.** Это клиент к закрытому сервису: проверить правку
у себя мы не можем, а сломанный клиент у наставника выглядит как сломанный сервис.
Нашли ошибку — напишите, поправим сами.

## Лицензия

MIT — файл [LICENSE](LICENSE). Берите, ставьте, правьте под свою программу.

## Ссылки

- Помощник в документации сервиса: <https://cad.cmit.ru/docs#razbor>
- «Макетка»: <https://cad.cmit.ru>
- Политика: <https://cad.cmit.ru/privacy>