ИИ-Ассистент в КонтрCAD: Инструкция по подключению (MCP)

Статьи 68 Опубликовано: 06.11.2026 Автор: Лунев Валерий

КонтрCAD начиная с версии 0.9.80 поддерживает Model Context Protocol (MCP) — открытый стандарт, который позволяет нейросетям (DeepSeek, Claude, ChatGPT, Cursor и другим) напрямую управлять вашей 3D-моделью.

Вы просто пишете в чат: «Создай корпус для Raspberry Pi 4» — и ассистент строит его через историю операций: создаёт примитивы, эскизы, выдавливания, булевы операции и фаски. Всё это остаётся обычными параметрическими операциями, которые можно отменить (Ctrl+Z) или поправить в панели истории.

 

Ниже — настройка для веб-версии и десктопного приложения, список инструментов и решение типовых проблем.

Что выбрать: веб или десктоп

Способ Веб-версия Десктопная версия
Транспорт WebMCP (встроенный в браузер) Streamable HTTP (локальный сервер)
Что нужно Chrome 126+ / Edge и расширение-клиент Установленный КонтрCAD Desktop + любой MCP-клиент
Где живут инструменты в открытой вкладке редактора в приложении, пока оно запущено
Доступно сразу 16 инструментов (ядро), остальные — по группам все 68 инструментов

Если работаете в браузере — берите первый вариант. Если нужен «полный» ассистент в Cursor/Claude Desktop/DeepSeek Harness — второй.

 

Настройка для веб-версии

Веб-версия использует WebMCP: редактор регистрирует свои инструменты в браузере, и ассистент «видит» открытую вкладку и управляет ей напрямую.

Что понадобится

  1. Браузер Google Chrome (версия 126 или новее) либо Microsoft Edge.
  2. Клиент с поддержкой WebMCP — например, официальное расширение DeepSeek Harness (подойдёт и другой WebMCP-клиент).

Пошаговая настройка

  1. Установите расширение-клиент (для DeepSeek Harness — из Chrome Web Store).
  2. Настройте клиент: в настройках расширения укажите адрес локального сервера, например http://127.0.0.1:3080, если запускаете DSH локально. Обычно Harness сам предлагает команду для терминала, которая всё настроит.
  3. Откройте редактор в браузере: kontrcad.ru/editor или dev.kontrcad.ru.
  4. Начните диалог: откройте боковую панель расширения поверх редактора. Ассистент подхватит инструменты автоматически.

Если инструменты не появились после обновления редактора — перезагрузите вкладку с ?nocache=1 (или сбросьте кэш кнопкой в редакторе): редактор кэшируется service worker'ом.

Важно: группы инструментов

В веб-версии по умолчанию активны только 13 инструментов ядра + 3 мета-инструмента (16). Остальные — в группах, чтобы не забивать контекст модели:

Группа Что внутри
core чтение сцены, примитивы, трансформации, булевы операции *(активна всегда)*
history undo/redo/jump, изменение параметров, описания операций
sketches плоскости, эскизы, текст, DOF-анализ, extrude/revolve/sweep/loft
images скриншот вьюпорта, рендер-превью, мозаика 4 видов
library встроенная библиотека моделей
files проекты в локальной БД, экспорт STL/STEP/3MF/OBJ/PLY/GLTF
advanced фаски, резьба, шестерни, массивы, группы, repair, decimate

Ассистент открывает нужную группу сам:

list_tool_groups()                                    → какие группы есть и что активно
enable_tool_group({ groups: ["sketches", "advanced"] })  → включить

enable_tool_group в десктопной версии просто отвечает «все инструменты доступны сразу» — там группы не нужны.

Промт для веб-версии

Скопируйте в чат ассистента:

Ты — инженер-ассистент в параметрическом CAD КонтрCAD (веб-версия, WebMCP).

КАНАЛ: только mcp__chrome__evaluate → window.__kc.call(name, args).
• Возвращает объект/JSON — работай с данными, не пересказывай их целиком.
• Нет __kc → перезагрузи вкладку с ?nocache=1.
• images-инструменты сами открывают вкладку, base64 в контекст НЕ приходит.

ГРУППЫ: по умолчанию активны только core (16 инструментов с мета).
• Нужного инструмента нет в списке → list_tool_groups() → enable_tool_group({groups:[...]}).
• sketches — эскизы/текст/DOF/профильные операции; advanced — фаски, резьба, массивы;
images — превью; files — проекты и экспорт; library — библиотека; history — история.
• Справка по теме: get_help({topic}) — вызывай вместо перебора инструментов.

ДИСЦИПЛИНА:
• get_scene_state — один раз в начале, дальше работай по известным UUID.
• list_objects дешевле get_scene_state; get_object — для одного объекта.
• Не перепроверяй успешные операции и не вызывай get_scene_state после каждого шага.
• Несколько последовательных шагов → batch({steps:[...], rollback:true}).
• get_multi_view — только в финале. Новая задача — новый чат.

ИСТОРИЯ:
• update_operation сливает параметры (передавай только изменения).
• undo/redo/jump_to требуют expected_current_id.

СТИЛЬ: кратко, прогресс галочками (✅ шаг N: …), финал — 3–5 предложений + превью.
Не объясняй очевидное.

Проверка

Отправьте: _«Создай куб 40×40×40, вычти цилиндр Ø24 высотой 60 и покажи результат через get_model_preview»_. Если через 10–15 секунд появилась деталь с отверстием — всё работает.

 

Настройка для десктопной версии (Electron + Streamable HTTP)

Десктопная версия не зависит от браузерных расширений и не требует Chrome. При обычном запуске КонтрCAD Desktop поднимает локальный MCP-сервер:

http://127.0.0.1:3100/mcp

Транспорт — Streamable HTTP, рекомендованный для актуальных MCP-клиентов (DeepSeek Harness, Cursor, Claude Desktop).

⚠️ Сервер доступен только пока запущено приложение «КонтрCAD». Закрыли редактор — соединение оборвалось. Сервер слушает только 127.0.0.1 и не требует авторизации, поэтому не пробрасывайте порт наружу.

Что понадобится

  1. Запущенное приложение КонтрCAD Desktop (обычный запуск, без флагов).
  2. MCP-клиент. В примерах — DeepSeek Harness.

Способ А: через интерфейс DeepSeek Harness (рекомендуется)

Плагин dsh-mcp-center добавляет в Harness отдельную страницу управления MCP-серверами. Установите его один раз:

dsh plugin --profile web add dsh-mcp-center
  1. Перезапустите dsh web и откройте Settings → MCP Center.
  2. Нажмите ＋ Add MCP server и заполните:
    • Name: kontrcad (станет префиксом инструментов: mcp__kontrcad__*)
    • Type: Streamable HTTP
    • URL: http://127.0.0.1:3100/mcp
    • Auth Mode: none (сервер локальный, токен не нужен)
  3. Нажмите Save. Рядом с сервером появится статус Connected (68 tools).

 

Способ Б: через конфигурационный файл

Добавьте в agent.cordis.yml (или cordis.patch.yml) вашего профиля:

- id: mcp-kontrcad
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: kontrcad
transport: streamable-http
url: http://127.0.0.1:3100/mcp

Перезапустите Harness: плагин подключится, вызовет tools/list и зарегистрирует все 68 инструментов.

Способ В: STDIO (Claude Desktop и подобные)

Клиенты вроде Claude Desktop умеют сами запускать сторонние программы. КонтрCAD стартует в скрытом режиме, отдаёт инструменты и завершается при отключении клиента.

{
"mcpServers": {
"kontrcad": {
  "command": "C:\\Путь\\К\\Установленному\\КонтрCAD.exe",
  "args": ["--mcp"]
}
}
}

При запуске из исходников команда — npm, аргументы — ["start", "--", "--mcp"]. После сохранения конфига перезапустите клиент.

Проверка подключения

В логах Harness (или в окне MCP Center) должно появиться:

kontrcad  Connected (68)
No auth · http://127.0.0.1:3100/mcp

Промт для ассистента (десктопная версия)

Ты — инженер-ассистент в параметрическом CAD КонтрCAD (десктопная версия).
Ты управляешь моделью через MCP-сервер kontrcad (Streamable HTTP, локальный).

ВОЗМОЖНОСТИ: доступны все 68 инструментов — чтение сцены, примитивы, эскизы и текст,
DOF-анализ, профильные операции (extrude/revolve/sweep/loft), булевы операции,
фаски, резьба, массивы, история, проекты, библиотека, изображения.

ДИСЦИПЛИНА:
• get_scene_state — один раз в начале, дальше работай по известным UUID.
• list_objects дешевле get_scene_state; get_object — для одного объекта.
• Не перепроверяй успешные операции.
• Несколько шагов подряд → batch({steps:[...], rollback:true}).
• Справка по теме: get_help({topic}) вместо перебора инструментов.
• get_multi_view / get_model_preview — для финального показа.

ИСТОРИЯ:
• update_operation сливает параметры (передавай только изменения) — так меняются размеры
без потери зависимых операций.
• undo/redo/jump_to требуют expected_current_id.

СТИЛЬ: кратко, прогресс галочками (✅ шаг N: …), финал — 3–5 предложений + превью.

 

Быстрый тест после подключения

Отправьте ассистенту:

Создай куб 40×40×40, вычти из него цилиндр Ø24 высотой 60,
и покажи результат через get_model_preview.

Если через 10–15 секунд появится изображение детали с отверстием — интеграция работает.

 

Какие инструменты доступны ИИ

ИИ работает не с пикселями, а с параметрическим ядром: он создаёт настоящие операции, которые можно отменить (Ctrl+Z) или изменить параметры. Всего — 68 инструментов (65 в группах + 3 мета-инструмента).

Ядро и чтение сцены (core, активна всегда)

  • get_scene_state(include_objects?, include_operations?) — полное состояние: объекты (UUID, имена, типы, позиции, размеры) и история операций.
  • list_objects() — краткий список объектов. Дешевле, чем get_scene_state.
  • get_object(uuid) — подробно про один объект: bbox, size, position, position_bottom (центр нижней грани).
  • body_topology(uuid, mode: "cylinders") — найденные цилиндрические поверхности тела (валы/отверстия: тип, диаметр, глубина, ось).
  • create_primitive(type, …) — 18 типов: куб, сфера, цилиндр, конус, тор, пирамида, шестигранник, труба, полусфера, звезда, сердце, клин, крыши и др.
  • move_object / rotate_object / scale_object — трансформации. move_object поддерживает position_mode: preserve | bottom | center.
  • boolean_union / boolean_subtract / boolean_intersect — булевы операции на Manifold (watertight-результат).
  • delete_objects(uuids) — удаление (каскадно для групп).
  • batch(steps, rollback: true) — несколько инструментов одним вызовом с откатом при ошибке.

История операций (history)

  • undo(expected_current_id) / redo(expected_current_id) / jump_to(target_index, expected_current_id) — навигация по истории с защитой от гонки.
  • update_operation(operation_id, new_params) — изменить параметры операции; зависимые операции перестраиваются автоматически.
  • update_object_parameter(uuid, param_name, value) — упрощённо: один параметр по UUID объекта.
  • remove_operation(operation_id) — удалить операцию (откажется, если на неё ссылаются).
  • describe_operation(operation_id | object_uuid, description) — подписать операцию для туториала/истории.

Зачем expected_current_id: пользователь может в любой момент нажать Ctrl+Z или добавить операцию руками. С проверкой ассистент получит ошибку и пересинхронизируется, без неё — сломал бы сцену. Это «оптимистичная блокировка».

Эскизы, текст и профильные операции (sketches)

  • create_workplane(face_ref | position+normal, name, plane_type) — плоскость эскиза (ассоциативно к грани или снапшотом).
  • add_sketch_entities(plane_id, entities) — линии, окружности, дуги, овалы, полилинии, сплайны, точки; у каждой сущности можно задать pinned.
  • remove_sketch_entities / update_sketch_entity — правка и удаление элементов (в т.ч. pinned).
  • add_sketch_constraint / remove_sketch_constraint — ограничения: horizontal, vertical, parallel, perpendicular, angle, equality, coincident, point_on_line, tangent, distance и др.
  • add_sketch_text(plane_id, text, position, height, font_name, anchor, direction, pinned) — текст в эскизе: глифы превращаются в замкнутые полилинии. По умолчанию текст закреплён (pinned: true), поэтому не увеличивает DOF.
  • get_sketch_state(plane_id) — элементы, регионы (готовые профили для выдавливания), ограничения.
  • get_sketch_dof(plane_id?, tolerance?, include_entities?) — анализ степеней свободы: зафиксирован ли чертёж, сколько степеней осталось, есть ли конфликт или избыточные связи, какие элементы ещё подвижны.
  • extrude — выдавливание профиля (figures или selected_regions_data) с наклоном, скруткой и масштабированием; operation_type: new | cut | join.
  • revolve — тело вращения (ось или line_axis_points).
  • sweep — профиль по траектории (path_points).
  • loft — плавное соединение 2+ сечений.

Изображения (images)

  • get_viewport_screenshot(max_size?, hide_helpers?) — «что видит пользователь».
  • get_model_preview(uuids?, view?, wireframe?, max_size?, background?) — чистый рендер объекта с ракурса.
  • get_multi_view(uuids?, views?, max_size?) — мозаика 2×2 (front/right/top/iso) одним изображением, вчетверо дешевле четырёх скриншотов.

Нужен vision в MCP-клиенте. В веб-версии изображение открывается в отдельной вкладке и не попадает в контекст как base64.

Библиотека (library)

  • list_library_items(category_id?, search?, limit?) — каталог встроенной библиотеки (без параметров — категории). Вызывайте до импорта.
  • import_library_model(item_id | name_query, position?, color?) — вставить модель из библиотеки.

Проекты и экспорт (files)

  • new_project(confirm: true) — очистить сцену и начать с нуля.
  • save_project(name, description?, existing_key?, overwrite?) — сохранить в локальную БД.
  • list_saved_projects(search?, limit?) / open_saved_project(key, confirm: true) / delete_saved_project(key, confirm: true).
  • export_project_file(compact?) — скачать .kbcad для бэкапа или переноса.
  • export_model(format: stl | stl-ascii | obj | ply | gltf | 3mf | step, file_name?, selected_only?).

Импорт проекта из файла остаётся за пользователем — ассистент не может открыть диалог выбора файла.

Продвинутое (advanced)

  • fillet_chamfer(target_uuid, edges, distance1, distance2?, segments?) — фаска/скругление по рёбрам. Перед вызовом получите рёбра: get_object_edges.
  • get_object_edges(uuid, axis?, min_length?, min_crease_angle?, near_point?, radius?, limit?) — рёбра в мировых координатах.
  • get_object_faces(uuid, axis?, min_area?, near_point?, radius?, limit?, include_face_ref?) — грани (в т.ч. face_ref для создания плоскости по грани).
  • thickness(uuid, thickness, mode?, segments?, inset?) — оболочка заданной толщины.
  • create_thread(type, standard?, diameter, pitch, length, threadType, …) — отдельное тело резьбы.
  • thread_cut(target_uuid, diameter, pitch, length, position, …) — нарезать резьбу на существующем теле (внутреннюю/наружную).
  • create_gear(teeth, module, faceWidth, …) — эвольвентная шестерня.
  • split_by_plane(uuid, plane_id) — разрезать плоскостью.
  • repair_geometry(uuids, …) — починить «грязный» STL (manifold).
  • decimate_mesh(uuids, reduction_factor?, …) — уменьшить число полигонов.
  • create_text3d(text, font_size?, depth?, …) — объёмный текст.
  • array_linear / array_circular — массивы.
  • mirror_object, duplicate_object, group_objects, ungroup_objects.
  • change_color, change_name, change_visibility.

Мета-инструменты (доступны всегда)

  • list_tool_groups(include_tools?) — какие группы есть, что активно, сколько инструментов.
  • enable_tool_group(groups) — включить группы (в вебе; в десктопе всё уже доступно).
  • get_help(topic) — подробная справка по теме вместо длинных описаний в схеме: general, sketch, extrude, move_object, boolean_operations, fillet_chamfer, get_object_edges, repair_geometry, create_primitive.

Как экономить контекст

  • get_help(topic) — длинные инструкции не висят в схеме инструментов, их запрашивают по необходимости.
  • batch — несколько последовательных шагов одним вызовом (с rollback: true при ошибке сцена откатится).
  • expect — во многих инструментах (create_primitive, move_object, булевы, extrude, fillet_chamfer) можно передать ожидаемые bbox/volume: ассистент сразу узнает, что размер не сошёлся, без отдельной проверки.
  • list_objects вместо get_scene_state, get_object для одного объекта, изображения — только для финального показа.

 

Примеры промптов

Простой:

Создай куб 50×50×50 мм, затем цилиндр радиусом 10 мм и высотой 60 мм. Вычти цилиндр из куба — получится сквозное отверстие.

Корпус:

Создай корпус: куб 100×80×50 мм. Сделай оболочку (thickness) с толщиной стенок 2 мм. Затем 4 цилиндра радиусом 3 мм на расстоянии 10 мм от углов и вычти их из корпуса. В конце — фаска 1 мм на верхних рёбрах.

Эскиз с текстом и проверкой DOF:

На верхней грани корпуса создай плоскость эскиза. Нарисуй прямоугольник 40×15 и добавь текст «КонтрCAD» высотой 6 мм по центру. Проверь get_sketch_dof — текст должен быть закреплён. Выдави прямоугольник на 2 мм и вырежи текст на 0.5 мм.

Резьба:

На валу Ø20 нарежь внешнюю резьбу M20×2.5 длиной 15 мм. position подбери так, чтобы витки начинались в 3 мм от основания вала. Покажи результат через get_multi_view.

 

Ограничения и безопасность

  • Локальность. Десктопный сервер слушает только 127.0.0.1:3100, авторизации нет — не публикуйте порт в сеть.
  • Жизненный цикл. HTTP-сервер живёт, пока запущен КонтрCAD; STDIO-режим завершается вместе с клиентом.
  • Необратимое — только вручную. Сжатие/очистка истории, импорт файла проекта и выбор файлов остаются за пользователем.
  • История защищена. undo/redo/jump_to требуют expected_current_id — ассистент не «перескочит» через ваши правки.
  • Группы. В веб-версии набор инструментов ограничен активными группами — это не баг, а экономия контекста.

Решение проблем

Симптом Что делать
Ассистент пишет «инструмент не найден» В вебе включите группу: list_tool_groups() → enable_tool_group({groups:[...]})
Ошибки с UUID «объект не найден» Попросите get_scene_state или list_objects — ассистент увидит актуальные UUID
Нет window.__kc в веб-версии Перезагрузите вкладку с ?nocache=1 (или сбросьте кэш в редакторе)
Ассистент ищет КОМПАС-3D или другие программы Уточните: «Ты работаешь внутри редактора КонтрCAD. Используй только свои MCP-инструменты»
В десктопе не подключается http://127.0.0.1:3100/mcp Проверьте, что КонтрCAD запущен; не занят ли порт 3100 другой программой; в консоли приложения должно быть [MCP] Streamable HTTP server: http://localhost:3100/mcp
В MCP Center статус не Connected Проверьте тип транспорта (Streamable HTTP, не SSE) и URL с /mcp на конце
Инструменты есть, но модель «не видит» изображения Включите группу images и убедитесь, что у клиента есть vision