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 версии 18 или новее, Git — помощник ставится прямо из этого репозитория — и код доступа.

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

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

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

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

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

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

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

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

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

Cursor

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

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

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

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

JetBrains AI Assistant

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

Claude Code

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

claude mcp add maketka --env MAKETKA_TOKEN=mk_ВАШ_КОД -- npx -y github:cmit-ru/maketka-mcp#v0.2.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/`)
«код доступа не подошёл»	код скопирован целиком, вместе с `mk_`; не выдавали ли новый код после настройки
«код доступа отозван»	выдайте новый в кабинете и поправьте настройки
групп нет, список пустой	включён ли помощник у вашей группы (это делает администратор)
«для этой группы помощник не включён»	то же самое: флаг у группы
«такой работы нет»	работа не из ваших групп или удалена
«слишком много запросов»	подождите минуту: помощник спросил слишком часто
«эта работа сейчас никем не открыта»	откройте работу в браузере — построение доигрывает вкладка
«нужно обновить помощника»	поставьте новую версию: в настройках поменяйте метку после `#`

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

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

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

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

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

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

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

Лицензия

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

Ссылки

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

maketka-mcp