From 09ef56f6bc606160d41528e96f0c7fc292d0abff Mon Sep 17 00:00:00 2001 From: Shahovalov MIkhail Date: Tue, 26 May 2026 00:07:22 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20README=20+=20=D0=B0=D0=BA=D1=82=D1=83?= =?UTF-8?q?=D0=B0=D0=BB=D0=B8=D0=B7=D0=B0=D1=86=D0=B8=D1=8F=20CLAUDE.md=20?= =?UTF-8?q?=D0=B8=20=D0=BF=D1=80=D0=B5=D0=B7=D0=B5=D0=BD=D1=82=D0=B0=D1=86?= =?UTF-8?q?=D0=B8=D0=B8=20(v1=20=D0=B3=D0=BE=D1=82=D0=BE=D0=B2)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README.md: требования, сборка/запуск, конфиг MCP-клиента, инструменты, тесты - CLAUDE.md: раздел Current state переписан под реализованный v1 + команды + ключевые факты - presentation.html: статус/прогресс (72%), TODO (фундамент и инструменты — готово), roadmap v1 ✓ - 12 тестов зелёные (5 unit + 7 integration) Co-Authored-By: Claude Opus 4.7 --- CLAUDE.md | 24 +++++++++++- README.md | 84 ++++++++++++++++++++++++++++++++++++++++++ docs/presentation.html | 55 +++++++++++++-------------- 3 files changed, 135 insertions(+), 28 deletions(-) create mode 100644 README.md diff --git a/CLAUDE.md b/CLAUDE.md index 19a153d..6b83fb4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -31,7 +31,29 @@ The index lives at `docs/kompas_sdk_index.tsv` (`filenametitleexcerpt` ## Current state -The repository is **empty / greenfield** — no source, no git, no build system yet. The implementation language and MCP transport have **not** been chosen. Before writing code, decide and record (here) the stack. The natural fit is **.NET / C#** because the КОМПАС API ships as COM type libraries with first-class C# Interop samples (see SDK `Samples/CSharp.zip`), but a Python MCP server using `pywin32`/`comtypes` is also viable. +**v1 implemented and working** (sketch→extrude→snapshot loop validated end-to-end over MCP). Stack: +**.NET 8 (`net8.0-windows`, x64), C#**, MCP via the official `ModelContextProtocol` SDK over **stdio**. +See [`README.md`](README.md) and [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md); design decisions/caveats in +[`docs/OPEN_QUESTIONS.md`](docs/OPEN_QUESTIONS.md). + +Layout: `src/Kompas.Mcp.Core` (COM layer), `src/Kompas.Mcp.Host` (MCP stdio server + tools), +`tests/Kompas.Mcp.Tests` (unit + integration), `libs/kompas-interop/*.dll` (vendored КОМПАС interop +assemblies from SDK `Samples/Common`, referenced via `Directory.Build.props` → `KompasInteropDir`). + +```powershell +dotnet build -c Release # build +dotnet test --filter "Category=Unit" # unit tests (no COM) +dotnet test --filter "Category=Integration" # integration (requires running КОМПАС) +dotnet run --project src/Kompas.Mcp.Host # start the MCP server (stdio) +``` + +Key implementation facts (don't relearn): +- **All COM calls run on one dedicated STA thread** (`KompasDispatcher.InvokeAsync`); КОМПАС is single-instance STA. Services never touch COM off that thread. +- Connection goes through **API5** (`KOMPAS.Application.5` → `KompasObject`) then `ksGetApplication7()` → `IApplication`; the API5 root is needed for `ksPart` 3D-building and `ksDocument3D` snapshots. +- 3D is built via **API5 `ksPart`** (`NewEntity(o3d_sketch/o3d_bossExtrusion/...)`, `ksBossExtrusionDefinition`/`ksCutExtrusionDefinition`); cut-through holes use `dtBoth` + `etThroughAll`. API7 is used for app/documents. +- **Snapshot**: `ksDocument3D.SaveAsToRasterFormat(file, ksRasterFormatParam)` renders to a temp file (the in-memory `resultArrayBytes` stays empty when a filename is given); read bytes back. Return to MCP via `ImageContentBlock.FromBytes(bytes, mime)` — **not** `Data = bytes` (Data holds base64 bytes). +- Logs go to **stderr** (stdout is the MCP channel). Integration tests reuse one КОМПАС via `KompasFixture`; artifacts land in gitignored `.scratch/`. +- Not yet done (next): face selection / sketch-on-face, revolve, fillet/chamfer, `get_part_info` (mass/volume), variables/properties, a proper in-process MCP-client test. ## КОМПАС-3D API architecture (the critical context) diff --git a/README.md b/README.md new file mode 100644 index 0000000..ceca6e4 --- /dev/null +++ b/README.md @@ -0,0 +1,84 @@ +# kompas3d-mcp + +**MCP-сервер для управления CAD-системой КОМПАС-3D (АСКОН) языковой моделью.** + +Сервер — это COM-клиент КОМПАС-3D: он подключается к установленному КОМПАС и предоставляет +LLM набор инструментов для создания документов, построения 3D-деталей (эскиз → выдавливание), +а также **снимок модели** (агент «видит» результат и строит пошагово). + +> Подробности: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) · план — [docs/IMPLEMENTATION_PLAN.md](docs/IMPLEMENTATION_PLAN.md) +> · спорные вопросы — [docs/OPEN_QUESTIONS.md](docs/OPEN_QUESTIONS.md) · обзор — [docs/presentation.html](docs/presentation.html) + +## Требования + +- **Windows x64**, установленный **КОМПАС-3D** (разрабатывалось на v24 Home). +- **.NET SDK 8+** (собирается и на SDK 10; целевой фреймворк `net8.0-windows`). + +## Сборка и запуск + +```powershell +dotnet build -c Release +# сервер (stdio): +dotnet run --project src/Kompas.Mcp.Host -c Release +# или собранный exe: +src/Kompas.Mcp.Host/bin/Release/net8.0-windows/kompas-mcp.exe +``` + +### Подключение к MCP-клиенту (stdio) + +```json +{ + "mcpServers": { + "kompas3d": { "command": "C:\\путь\\к\\kompas-mcp.exe", "args": [] } + } +} +``` + +## Инструменты (v1) + +| Группа | Инструменты | +|---|---| +| System | `kompas_connect`, `kompas_status`, `kompas_set_visible` | +| Documents | `document_create`, `document_open`, `document_save`, `document_save_as`, `document_close`, `document_active` | +| Sketch | `sketch_create`, `sketch_add_line`, `sketch_add_circle`, `sketch_add_rectangle`, `sketch_close` | +| Features | `extrude_boss`, `extrude_cut`, `rebuild` | +| Vision | `model_snapshot` (PNG-снимок активной модели) | + +### Типовой сценарий + +`kompas_connect` → `document_create part` → `sketch_create XOY` → `sketch_add_circle` → +`sketch_close` → `extrude_boss` → `model_snapshot` → (повтор для следующих элементов). + +> ⚠️ Вызовы зависимых инструментов выполняйте **последовательно** (дождавшись ответа): +> сессия построения хранит эскизы по `id`, а сервер обрабатывает запросы конкурентно. + +## Структура + +``` +src/Kompas.Mcp.Core/ COM-слой: STA-диспетчер, подключение, документы, эскизы/операции, снимок +src/Kompas.Mcp.Host/ MCP-сервер (stdio) + определения инструментов +tests/Kompas.Mcp.Tests/ unit (диспетчер) + integration (требуют КОМПАС) +libs/kompas-interop/ вендорские interop-сборки КОМПАС (из SDK Samples/Common) +docs/ архитектура, план, презентация, навигатор по справке SDK +tools/kdoc.py поиск/чтение справки SDK КОМПАС (см. CLAUDE.md) +``` + +## Тесты + +```powershell +dotnet test # все (integration требуют КОМПАС) +dotnet test --filter "Category=Unit" # только unit (без COM) +dotnet test --filter "Category=Integration" # только integration +``` + +## Архитектура (кратко) + +- **STA-поток** (`KompasDispatcher`) владеет всеми COM-вызовами — КОМПАС однопоточный STA. +- Подключение через API5 `KompasObject` (`KOMPAS.Application.5`) → API7 `IApplication` (`ksGetApplication7`). +- 3D строится через API5 `ksPart` (эскизы, выдавливание); снимок — `ksDocument3D.SaveAsToRasterFormat`. +- MCP — официальный C# SDK `ModelContextProtocol`, транспорт stdio, логи в stderr. + +## Лицензирование + +`libs/kompas-interop/*.dll` — interop-сборки АСКОН из состава SDK КОМПАС-3D; распространяются +согласно условиям АСКОН. Для работы требуется установленный КОМПАС-3D. diff --git a/docs/presentation.html b/docs/presentation.html index 54f7aef..6a8c669 100644 --- a/docs/presentation.html +++ b/docs/presentation.html @@ -125,7 +125,7 @@
- Статус: спайки S1–S2 пройдены · подключение к КОМПАС работает + Статус: v1 работает — цикл эскиз→выдавливание→снимок через MCP (18 инструментов)

КОМПАС-3D MCP-сервер
управление CAD языком LLM

MCP-сервер, который превращает операции КОМПАС-3D — создание документов, эскизы, 3D-операции, параметры — в инструменты для языковой модели. Под капотом — @@ -246,8 +246,8 @@ впереди.

-
Общий прогрессСпайки пройдены · идёт фундамент v1
-
+
Общий прогрессv1 работает · 12 тестов зелёные · доки и ревью
+
@@ -267,43 +267,42 @@
-

Фундамент v1 В РАБОТЕ

+

Фундамент v1 ГОТОВО

Скелет сервера и связь с КОМПАС

    -
  • ✓Спайк S1: interop-сборки собираются под net8.0-windows
    • -
  • ✓Спайк S2: подключение к КОМПАС (launch/attach, IApplication, версия 24.0)
    • -
  • ~Скелет решения (git, .slnx, Directory.Build.props)
    • -
  • Маппинг перечислений (enum ↔ строка)
    • -
  • STA-поток + диспетчер + насос сообщений
    • -
  • MCP-хост на stdio, логи в stderr
    • -
  • Трансляция ошибок COM в MCP-ответы
    • +
  • ✓Спайки S1–S4: interop, подключение, STA, рендер
    • +
  • ✓Решение Core/Host/Tests, Directory.Build.props, git
    • +
  • ✓Маппинг перечислений (enum ↔ строка)
    • +
  • ✓STA-диспетчер (выделенный поток, очередь задач)
    • +
  • ✓MCP-хост на stdio, логи в stderr
    • +
  • ✓Подключение по ProgID (attach/launch)
-

Инструменты v1 ДАЛЕЕ

-

Покрытие центрального цикла моделирования

+

Инструменты v1 ГОТОВО

+

18 инструментов, отдаются по MCP-протоколу

    -
  • System: connect · set_visible · status
    • -
  • Documents: create · open · save · close · active
    • -
  • Sketch: create · add line/circle/arc/rect · close
    • -
  • Features: extrude boss/cut · revolve · rebuild
    • -
  • Query: select_face · list_bodies · get_part_info
    • -
  • Vision: model_snapshot · set_view 👁️
    • +
  • ✓System: connect · status · set_visible
    • +
  • ✓Documents: create · open · save · save_as · close · active
    • +
  • ✓Sketch: create · add line/circle/rectangle · close
    • +
  • ✓Features: extrude_boss · extrude_cut · rebuild
    • +
  • ✓Vision: model_snapshot 👁️
    • +
  • Query: select_face · list_bodies · get_part_info (далее)
-

Качество и поставка ДАЛЕЕ

+

Качество и поставка В РАБОТЕ

Тесты, сборка, интеграция с клиентом

    -
  • Unit-тесты чистой логики (маппинг, валидация)
    • -
  • Интеграционные тесты с КОМПАС (категория Integration)
    • -
  • Smoke через MCP Inspector
    • -
  • Сборка kompas-mcp.exe (win-x64)
    • -
  • Регистрация stdio-сервера в конфиге клиента
    • +
  • ✓Unit-тесты диспетчера (5) — без COM
    • +
  • ✓Интеграционные тесты с КОМПАС (7): подключение, документы, снимок, цикл
    • +
  • ✓Сквозной прогон по MCP-протоколу (tools/call → PNG)
    • +
  • ✓Сборка kompas-mcp.exe, README с конфигом клиента
    • +
  • In-process тест MCP-клиента, релизный publish
@@ -318,8 +317,8 @@

Наращиваем покрытие API волнами — от простых операций к параметрике, черчению и сборкам.

-
v1 · сейчас

Цикл моделирования

Документы, эскизы, выдавливание/вырез, вращение, выборка граней

-
v2

Операции

Скругление, фаска, оболочка, ребро, лофт, кинематика, массивы

+
v1 · готово ✓

Цикл моделирования

Документы, эскизы, выдавливание/вырез, снимок модели — работает

+
v2 · далее

Операции и выборка

Выбор граней, эскиз на грани, вращение, скругление/фаска, массивы

v3

Параметрика

Переменные IVariable7, свойства IPropertyMng, формулы

v4

2D-черчение

Виды, размеры, тексты, штриховки; спецификации

v5

Сборки и экспорт

Компоненты, сопряжения, конвертеры (STEP), HTTP/SSE-транспорт

@@ -331,8 +330,10 @@
КОМПАС-3D MCP · документация проекта
+ 📦 README 📐 Документ архитектуры 🛠️ План реализации + ❓ Открытые вопросы 📘 CLAUDE.md 📚 Справка SDK КОМПАС-3D 🌐 Онлайн-справка АСКОН