Skip to main content
Glama
kompas-mcp

kompas-mcp

by biryak
README.md
# kompas-mcp

Локальный MCP-сервер для КОМПАС-3D v25 (COM API7). План: [docs/plan/PLAN.md](docs/plan/PLAN.md) · фаза 0: [docs/phase0/REPORT.md](docs/phase0/REPORT.md).

Работает с уже запущенным КОМПАС-3D того же пользователя: читает модели, строит и правит детали, заполняет основную надпись, выгружает STEP/IGES/STL/PDF/DXF/SVG. Каждое изменение проверяется (объём, ошибки дерева), делается бэкап, отменяется одним Ctrl+Z. Сетевых вызовов и телеметрии нет.

Последний выпуск — 0.6.0; описание ниже — по ветке `main`, история выпусков — в [docs/release-notes.md](docs/release-notes.md). Руководство пользователя: [docs/user/README.md](docs/user/README.md). Отчёты по фазам: [2](docs/phase2/REPORT.md), [3](docs/phase3/REPORT.md), [4](docs/phase4/REPORT.md), [5](docs/phase5/REPORT.md), [6](docs/phase6/REPORT.md).

## Требования
- Windows 10/11 x64, КОМПАС-3D v25 с легальной лицензией. Сервер **не запускает** КОМПАС сам: откройте его до начала работы.
- Любой MCP-клиент: Claude Desktop/Code, VS Code с Copilot, Cursor, Windsurf, Gemini CLI, Codex CLI, LM Studio и
  др. (см. «Подключение к ИИ-клиенту»); клиент и КОМПАС запускаются без «от имени администратора».

## Установка (для пользователей)

**Вариант 1 — одной командой** (PowerShell, без прав администратора):
```powershell
powershell -ExecutionPolicy Bypass -c "irm https://github.com/biryak/fresh-kompas-mcp/releases/latest/download/install.ps1 | iex"
```
Скрипт:
1. Ставит [uv](https://docs.astral.sh/uv/), если его нет.
2. Скачивает пакет последнего релиза и **проверяет SHA256** по `SHA256SUMS.txt` релиза: пакет не подписан сертификатом, это его замена.
3. Ставит пакет в отдельное окружение (`uv tool install`).
4. Запускает самопроверку `doctor`.
5. Спрашивает папки, с которыми серверу можно работать, и для каждого найденного ИИ-клиента — подключить ли его
   (Claude Desktop/Code, VS Code с Copilot, Cursor, Windsurf, Gemini CLI, Codex CLI, LM Studio). Конфиг Claude
   Desktop ищется там, где он есть: `%APPDATA%\Claude` у обычной установки или `%LOCALAPPDATA%\Claude-Data\…`
   у установки из пакета Windows; перед правкой любого конфига делается копия `.bak-kompas-mcp`.
6. Добавляет папку программ uv в PATH (`uv tool update-shell`), если её там нет: команда `kompas-mcp` работает в
   новом окне терминала.

После установки перезапустите ИИ-клиент.

Параметры (`-Version v0.6.0`, `-Roots "D:\CAD;E:\Projects"`, `-Clients "cursor,vscode"` — только эти клиенты без вопросов, `-Wheel <файл .whl>` — без скачивания, `-Yes`) и удаление передаются так:
```powershell
& ([scriptblock]::Create((irm https://github.com/biryak/fresh-kompas-mcp/releases/latest/download/install.ps1))) -Uninstall
```

**Вариант 2 — Claude Desktop, расширение.** Скачайте `kompas-mcp-<версия>.mcpb` со страницы [Releases](https://github.com/biryak/fresh-kompas-mcp/releases) и откройте его двойным щелчком. В настройках расширения укажите «Папки проектов». Нужен установленный uv. Claude Desktop покажет, что расширение не подписано: так и есть.

**Вариант 3 — вручную** (uv уже установлен). Ссылку на `kompas_mcp-<версия>-py3-none-any.whl` возьмите со
страницы [Releases](https://github.com/biryak/fresh-kompas-mcp/releases) и сверьте SHA256 с `SHA256SUMS.txt`:
```bash
uv tool install --python 3.13 <ссылка на .whl>
```
```bash
uv tool update-shell
```
Затем в новом окне терминала подключите клиент (см. ниже):
```bash
kompas-mcp connect --all --roots "D:\CAD"
```

Проверка (КОМПАС запущен):
```bash
kompas-mcp doctor --live
```

## Подключение к ИИ-клиенту (Claude, ChatGPT/Codex, Gemini, Copilot, локальные модели)

kompas-mcp — обычный MCP-сервер (stdio), поэтому с ним работает любой клиент с поддержкой MCP и любая модель,
которую этот клиент умеет вызывать. Установщик сам находит клиенты на компьютере и для каждого спрашивает,
подключить ли сервер. Позже то же делает команда `kompas-mcp connect`:

```bash
kompas-mcp connect
```
покажет найденные клиенты и где сервер уже подключён;
```bash
kompas-mcp connect cursor --roots "D:\CAD;E:\Projects"
```
подключит один клиент (`--all` — все найденные; `--profile read-only` — только чтение). Отключить:
`kompas-mcp disconnect cursor` (или `--all`). Перед первой правкой конфига клиента рядом сохраняется копия
`<файл>.bak-kompas-mcp`; чужие записи и настройки не меняются. После подключения перезапустите клиент.

| Клиент | `id` | Модели | Куда пишется |
|---|---|---|---|
| Claude Desktop | `claude-desktop` | Claude | `claude_desktop_config.json` (обычная установка или пакет Windows) |
| Claude Code | `claude-code` | Claude | `claude mcp add -s user` |
| VS Code + GitHub Copilot (режим агента) | `vscode` | GPT, Claude, Gemini — что доступно в Copilot | `%APPDATA%\Code\User\mcp.json` |
| Cursor | `cursor` | на выбор в Cursor | `~\.cursor\mcp.json` |
| Windsurf | `windsurf` | на выбор в Windsurf | `~\.codeium\windsurf\mcp_config.json` |
| Gemini CLI | `gemini` | Gemini | `~\.gemini\settings.json` |
| Codex CLI (OpenAI) | `codex` | GPT | `~\.codex\config.toml` (таймаут запуска 60 с, вызова 300 с) |
| LM Studio | `lmstudio` | локальные модели на вашем компьютере | `~\.lmstudio\mcp.json` |
| Любой другой MCP-клиент | — | — | блок для его настроек: `kompas-mcp connect --print` |

Что учесть с другими моделями:
- Модель должна уметь вызывать инструменты (tool calling). Из локальных подходят, например, Qwen3 и gpt-oss
  в LM Studio; маленьким моделям 45 инструментов даются плохо — начните с `--profile read-only` (8 инструментов:
  статус, документы, отчёт по модели, выбор граней, снимок).
- Правила безопасности (перезапись файлов, закрытие документов, папки, PDM) проверяет сам сервер, а не модель:
  они действуют с любым клиентом. Подсказки сервера (`instructions`) и prompts часть клиентов не показывает —
  тогда попросите модель сначала вызвать `kompas_status`.
- Снимки (`view_capture`) клиент без поддержки картинок получает только как размер изображения.
- Данные уходят тому, кто обслуживает выбранную модель. С локальной моделью в LM Studio они остаются на
  компьютере; ограничения из [руководства](docs/user/README.md) (ДСП/КТ/ГОЗ) решает служба ИБ.

## Для разработчика
```bash
uv sync
```
```bash
uv run pytest
```
Живые тесты на КОМПАС: `KOMPAS_INTEGRATION=1 uv run pytest tests/integration` (открывают только новые документы). Релиз: тег `vX.Y.Z` → GitHub Actions собирает wheel, sdist, `.mcpb`, `SHA256SUMS.txt` и публикует Release.

`KOMPAS_MCP_ROOTS` задаёт папки, с которыми серверу разрешено работать; несколько папок разделяются `;`. Машинная политика в `HKLM\Software\Policies\kompas-mcp` или `%ProgramData%\kompas-mcp\policy.json` (только admin) имеет приоритет; см. PLAN §9.

## Инструменты
| Инструмент | Что делает |
|---|---|
| `kompas_status` | Версия КОМПАС, лицензия, модальные окна, состояние воркера, политика |
| `doc_list` / `doc_open` | Список открытых документов и их handles; открытие файла (по умолчанию только для чтения). STEP/IGES импортируются в новую модель из временной копии (исходник не меняется); в ответе единицы файла (мм, дюймы…), габарит в мм и тела |
| `inspect_model` | Дерево построения, переменные, МЦХ (мм/кг, всегда свежие), габарит, свойства, исполнение, ошибки, имена по умолчанию; на спецификации — строки и свободные строки с id; на чертеже — листы, виды (масштаб, положение, модель), их размеры и технические требования |
| `select` | Грани и рёбра по геометрии (`surface_type`, `radius_mm`, `normal`, `extreme`, `created_by`, `expect_count`) или уже выбранные из справочника КОМПАС материалы; справочные данные с источником — резьба (`kind="thread"`) и предельные отклонения (`kind="fit"`) из таблиц КОМПАС |
| `material_pick` | Выбор материала в штатном окне КОМПАС и назначение детали; повторное назначение запомненного — `part_set_properties(material_id=…)` |
| `selection_get` | Что сейчас выделил пользователь |
| `view_capture` | PNG документа; `view` — спереди/сверху/изометрия и др., `fit` — показать всё; вид пользователя восстанавливается сразу после снимка |
| `variables_set` (чтение — `inspect_model`, `obj=` для переменных операции) | Переменные детали и операций; привязка параметров операций к переменным (`expr`); допуски (`H7`, `h6`… из базы допусков КОМПАС) |
| `sketch_create` | Эскиз целиком за один вызов (линии, прямоугольники, окружности, дуги, полилинии); по желанию параметрический: ограничения (горизонтальность, совпадение точек, касание, концентричность и др.) и управляющие размеры с переменными. `into` — дополнить готовый эскиз. Состав эскиза и его размеры — `inspect_model(obj=…)`, новое значение размера — `feature_edit(params={"W": 120})` |
| `aux_plane` | Вспомогательная геометрия: плоскость со смещением, под углом через ось или ребро, через три точки; ось по двум точкам, ребру, двум плоскостям, оси цилиндра или конуса; точка по координатам |
| `part_extrude` / `part_revolve` | Бобышка/вырез выдавливанием или вращением; вырез «не в ту сторону» отклоняется |
| `part_sweep_loft` | Кинематическая операция (профиль по траектории: трубы, гнутые стержни) и операция по сечениям (переходы); бобышка или вырез |
| `part_body` | Многотельные детали: тело отдельным телом (`new_body` в выдавливании и вращении), объединение, вычитание, пересечение тел, отсечение плоскостью (остаётся сторона с указанной точкой), перенос и копия тела; список тел — `inspect_model(sections=["bodies"])` |
| `part_thread_rib_draft` | Условное изображение резьбы на валу или в отверстии (обозначение из таблицы резьб КОМПАС), ребро жёсткости, уклон граней |
| `part_fillet_chamfer` / `part_shell` / `part_pattern` | Скругление/фаска по рёбрам из селектора; оболочка; круговой/линейный/зеркальный массив |
| `part_hole` | Отверстие на плоской грани в точке `at=[x, y]` или по расстояниям от двух граней/рёбер; резьба (M8, M20×1,5 и др.) из базы резьб КОМПАС `thread.db`; конец 118° или плоский |
| `feature_edit` (в т.ч. `delete`) / `part_set_properties` | Параметры готовой операции (`params`: глубина, направление, «через всё», эскиз, угол и ось, радиус, катет, толщина, диаметр, число и шаг копий, смещение) — одним Ctrl+Z, с откатом, если ломается дерево; определение операции — `inspect_model(obj=…)`; переименование, исключение, удаление операций; обозначение и наименование детали |
| `batch` | Несколько операций одним шагом Ctrl+Z, есть `dry_run`; вырез внутри — `operation: "cut"` |
| `doc_create` / `doc_save` / `doc_close` | Новый документ; сохранение с проверкой записи (замена чужого файла — только с согласия); закрытие без потери несохранённого |
| `inspect_check` | Проверка геометрии; `measure=[a, b]` — расстояние (мин./макс./по нормали), ближайшие точки, угол и взаимное положение граней, рёбер, осей, плоскостей, компонентов: толщина стенки, зазор, соосность |
| `drw_set_stamp` | Основная надпись: графы без источника в модели (фамилии, даты, организация); ассоциативные графы — из модели |
| `export` / `job_status` | Выгрузка заданием: STEP AP214/AP242, IGES, STL, PNG для моделей; PDF, DXF (мм), DWG (AutoCAD 2018, мм 1:1), SVG, PNG для чертежей. Исходники не меняются, в заголовках нет путей и имени пользователя |

Prompts: `review_model`, `create_part_from_spec`, `modify_parameter`, `fill_title_block`, `batch_export`, `make_drawing`, `assembly_bom`, `review_documents` (сверка модели, чертежа, спецификации и ТЗ — роль въедливого корректора). Ревизия — `inspect_model(sections=["review"])`: на модели — чек-лист, на чертеже и спецификации — сверка с моделью и сборкой.

### v1 ([отчёт фазы 5](docs/phase5/REPORT.md))
| Инструмент | Что делает |
|---|---|
| `asm_add_component` / `asm_mate` | Компоненты сборки из файлов и их сопряжения, в том числе симметрия (`kind="symmetric"`, `plane`) — центрирование по замыслу |
| `asm_edit` | Перенести компонент числами (начало и оси; сопряжения держат то, что ограничивают), заменить файл компонента, удалить компонент или сопряжение — каждое одним Ctrl+Z. Положение компонентов и сопряжения — `inspect_model(sections=["components"])` |
| `asm_check_collisions` | Пересечения компонентов (пары и объём) |
| `asm_bom` | Состав изделия по разделам ГОСТ 2.106, выгрузка в .xlsx |
| `embodiment` | Исполнения: список, создание (-01, -02…), переключение |
| `drw_create_views` / `drw_tech_requirements` | Ассоциативные виды по ЕСКД с осевыми; технические требования и неуказанная шероховатость |
| `drw_add_section` / `drw_add_dimension` | Разрезы и сечения; ассоциативные размеры: линейные, угловые, диаметр, радиус; знаки шероховатости на поверхностях |
| `drw_view_edit` | Масштаб, положение, поворот и имя вида — одним Ctrl+Z; предупреждает, если вид вышел за рамку |
| `drw_add_positions` | Позиции (линии-выноски) на сборочном чертеже |
| `drw_rebuild` | Обновить чертёж после изменения модели; называет размеры, потерявшие привязку к изменённой модели |
| `spec_create` | Спецификация `.spw` по сохранённой сборке; `export` в xlsx/ods/pdf |
| `spec_edit` | Строки спецификации, которых нет в модели: документация, прочие изделия, материалы, комплекты — добавить, изменить, удалить (в Undo КОМПАС не попадает, в ответе есть `before`) |
| `part_set_properties(spec_section=…)` | Раздел спецификации детали: готовый файл крепежа → «Стандартные изделия» |
| Стандартные изделия ПОЛИНОМ | Вставляет пользователь из каталога КОМПАС; `asm_components` помечает их `catalog="polynom"`, `asm_bom` и `spec_create` относят к «Стандартным изделиям» |

## Ресурсы

| Ресурс | Что даёт |
|---|---|
| `kompas://status`, `kompas://docs`, `kompas://materials` | То же, что `kompas_status`, `doc_list`, материалы из справочника |
| `kompas://doc/{handle}/{раздел}` | Часть отчёта по документу (как `inspect_model`): `tree`, `variables`, `mass`, `bbox`, `properties`, `errors`, `embodiment`, `naming`; `stamp` — основная надпись |
| `kompas://doc/{handle}/preview.png` | PNG документа, как `view_capture` (около 800 px); отключается вместе со снимками (`allow_screenshot`) |
| `kompas://api/{имя}`, `kompas://api/{имя}/{член}` | Справка по интерфейсу или перечислению API КОМПАС (`IPart7`, `ksObj3dTypeEnum`) из библиотек типов установленного КОМПАС: члены строкой `Имя(параметры) [get/put]`; описание члена — вторым ресурсом |

## Материалы
Единственный источник — справочник материалов КОМПАС (ПОЛИНОМ:MDM). `material_pick` открывает штатное окно выбора КОМПАС, пользователь выбирает материал, сервер назначает его детали (одна запись Undo, бэкап, проверка массы) и запоминает в `%LOCALAPPDATA%\kompas-mcp\materials_seen.json`. `part_set_properties(material_id=…)` повторно назначает запомненный материал без окна. Своего списка материалов у сервера нет; если нужного материала нет в справочнике, его заводят в справочнике КОМПАС/ПОЛИНОМ (при наличии прав).

TDQS

A3.8/5.0

Scored across 45 tools

Disambiguation4/5

Each tool targets a distinct CAD operation, and domain prefixes (part_/drw_/asm_/spec_/doc_) plus explicit descriptions separate the modeling, drawing, assembly and specification surfaces. A few near-pairs remain — select vs selection_get, inspect_model vs inspect_check, asm_bom vs spec_create, feature_edit vs variables_set — but the descriptions draw clear lines between them.

Naming Consistency3/5

There is a recognizable domain-prefix scheme (part_extrude, drw_add_dimension, asm_mate, doc_open), but verb ordering is mixed: noun_verb forms (sketch_create, variables_set, material_pick, selection_get) coexist with verb_noun forms (doc_save, doc_close, view_capture). Several tools carry no domain prefix at all (select, batch, export, embodiment, aux_plane, feature_edit), so the pattern is readable but not uniform.

Tool Count3/5

45 tools is heavy and well above the comfortable range for an agent, risking navigation and selection cost. However, the scope genuinely spans 3D modeling, assemblies, drawings, specifications, documents and export, and each tool maps to a real, non-redundant operation rather than being filler.

Completeness4/5

Coverage is unusually deep: sketching, all major solid features, patterns, booleans, mates and components, drawing views/dimensions/sections/positions/title block, specifications, save/open/close, export with job polling, and read-only inspection/verification. Minor gaps exist — no way to edit or delete an existing drawing dimension (only add), and limited drawing sheet/template management — which agents can work around.

Maintenance

ActivityNo data
ResponsivenessOutdated data