docs: README + актуализация CLAUDE.md и презентации (v1 готов)

- 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 <noreply@anthropic.com>
2026-05-26 00:07:22 +03:00
parent 230c534403
commit 09ef56f6bc
3 changed files with 135 additions and 28 deletions
@@ -31,7 +31,29 @@ The index lives at `docs/kompas_sdk_index.tsv` (`filename<TAB>title<TAB>excerpt`

 ## 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)

@@ -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.
@@ -125,7 +125,7 @@
 <!-- HERO -->
 <header class="hero">
  <div class="wrap">
-    <span class="badge"><span class="dot" style="background:var(--green);box-shadow:0 0 10px var(--green)"></span> Статус: спайки S1–S2 пройдены · подключение к КОМПАС работает</span>
+    <span class="badge"><span class="dot" style="background:var(--green);box-shadow:0 0 10px var(--green)"></span> Статус: v1 работает — цикл эскиз→выдавливание→снимок через MCP (18 инструментов)</span>
    <h1>КОМПАС-3D <span class="g">MCP-сервер</span><br>управление CAD языком LLM</h1>
    <p class="lead">MCP-сервер, который превращает операции КОМПАС-3D — создание документов,
      эскизы, 3D-операции, параметры — в инструменты для языковой модели. Под капотом —
@@ -246,8 +246,8 @@
      впереди.</p>

    <div class="prog">
-      <div class="progrow"><span>Общий прогресс</span><span>Спайки пройдены · идёт фундамент v1</span></div>
-      <div class="bar"><i style="width:34%"></i></div>
+      <div class="progrow"><span>Общий прогресс</span><span>v1 работает · 12 тестов зелёные · доки и ревью</span></div>
+      <div class="bar"><i style="width:72%"></i></div>
    </div>

    <div class="todo-grid" style="margin-top:26px">
@@ -267,43 +267,42 @@

      <!-- NOW -->
      <div class="panel">
-        <h3>Фундамент v1 <span class="tag now">В РАБОТЕ</span></h3>
+        <h3>Фундамент v1 <span class="tag done">ГОТОВО</span></h3>
        <p class="meta">Скелет сервера и связь с КОМПАС</p>
        <ul class="list">
-          <li class="muted"><span class="mark ok">✓</span><span class="t">Спайк S1: interop-сборки собираются под <code>net8.0-windows</code></span></li>
-          <li class="muted"><span class="mark ok">✓</span><span class="t">Спайк S2: подключение к КОМПАС (launch/attach, IApplication, версия 24.0)</span></li>
-          <li><span class="mark wip">~</span><span>Скелет решения (git, <code>.slnx</code>, Directory.Build.props)</span></li>
-          <li><span class="mark todo"></span><span>Маппинг перечислений (enum ↔ строка)</span></li>
-          <li><span class="mark todo"></span><span>STA-поток + диспетчер + насос сообщений</span></li>
-          <li><span class="mark todo"></span><span>MCP-хост на stdio, логи в stderr</span></li>
-          <li><span class="mark todo"></span><span>Трансляция ошибок COM в MCP-ответы</span></li>
+          <li class="muted"><span class="mark ok">✓</span><span class="t">Спайки S1–S4: interop, подключение, STA, рендер</span></li>
+          <li class="muted"><span class="mark ok">✓</span><span class="t">Решение Core/Host/Tests, Directory.Build.props, git</span></li>
+          <li class="muted"><span class="mark ok">✓</span><span class="t">Маппинг перечислений (enum ↔ строка)</span></li>
+          <li class="muted"><span class="mark ok">✓</span><span class="t">STA-диспетчер (выделенный поток, очередь задач)</span></li>
+          <li class="muted"><span class="mark ok">✓</span><span class="t">MCP-хост на stdio, логи в stderr</span></li>
+          <li class="muted"><span class="mark ok">✓</span><span class="t">Подключение по ProgID (attach/launch)</span></li>
        </ul>
      </div>

      <!-- TOOLS -->
      <div class="panel">
-        <h3>Инструменты v1 <span class="tag next">ДАЛЕЕ</span></h3>
-        <p class="meta">Покрытие центрального цикла моделирования</p>
+        <h3>Инструменты v1 <span class="tag done">ГОТОВО</span></h3>
+        <p class="meta">18 инструментов, отдаются по MCP-протоколу</p>
        <ul class="list">
-          <li><span class="mark todo"></span><span><code>System</code>: connect · set_visible · status</span></li>
-          <li><span class="mark todo"></span><span><code>Documents</code>: create · open · save · close · active</span></li>
-          <li><span class="mark todo"></span><span><code>Sketch</code>: create · add line/circle/arc/rect · close</span></li>
-          <li><span class="mark todo"></span><span><code>Features</code>: extrude boss/cut · revolve · rebuild</span></li>
-          <li><span class="mark todo"></span><span><code>Query</code>: select_face · list_bodies · get_part_info</span></li>
-          <li><span class="mark todo"></span><span><code>Vision</code>: model_snapshot · set_view 👁️</span></li>
+          <li class="muted"><span class="mark ok">✓</span><span class="t"><code>System</code>: connect · status · set_visible</span></li>
+          <li class="muted"><span class="mark ok">✓</span><span class="t"><code>Documents</code>: create · open · save · save_as · close · active</span></li>
+          <li class="muted"><span class="mark ok">✓</span><span class="t"><code>Sketch</code>: create · add line/circle/rectangle · close</span></li>
+          <li class="muted"><span class="mark ok">✓</span><span class="t"><code>Features</code>: extrude_boss · extrude_cut · rebuild</span></li>
+          <li class="muted"><span class="mark ok">✓</span><span class="t"><code>Vision</code>: model_snapshot 👁️</span></li>
+          <li><span class="mark todo"></span><span><code>Query</code>: select_face · list_bodies · get_part_info (далее)</span></li>
        </ul>
      </div>

      <!-- QUALITY -->
      <div class="panel">
-        <h3>Качество и поставка <span class="tag next">ДАЛЕЕ</span></h3>
+        <h3>Качество и поставка <span class="tag now">В РАБОТЕ</span></h3>
        <p class="meta">Тесты, сборка, интеграция с клиентом</p>
        <ul class="list">
-          <li><span class="mark todo"></span><span>Unit-тесты чистой логики (маппинг, валидация)</span></li>
-          <li><span class="mark todo"></span><span>Интеграционные тесты с КОМПАС (категория Integration)</span></li>
-          <li><span class="mark todo"></span><span>Smoke через MCP Inspector</span></li>
-          <li><span class="mark todo"></span><span>Сборка <code>kompas-mcp.exe</code> (win-x64)</span></li>
-          <li><span class="mark todo"></span><span>Регистрация stdio-сервера в конфиге клиента</span></li>
+          <li class="muted"><span class="mark ok">✓</span><span class="t">Unit-тесты диспетчера (5) — без COM</span></li>
+          <li class="muted"><span class="mark ok">✓</span><span class="t">Интеграционные тесты с КОМПАС (7): подключение, документы, снимок, цикл</span></li>
+          <li class="muted"><span class="mark ok">✓</span><span class="t">Сквозной прогон по MCP-протоколу (tools/call → PNG)</span></li>
+          <li class="muted"><span class="mark ok">✓</span><span class="t">Сборка <code>kompas-mcp.exe</code>, README с конфигом клиента</span></li>
+          <li><span class="mark todo"></span><span>In-process тест MCP-клиента, релизный publish</span></li>
        </ul>
      </div>
    </div>
@@ -318,8 +317,8 @@
    <p class="sub">Наращиваем покрытие API волнами — от простых операций к параметрике,
      черчению и сборкам.</p>
    <div class="timeline">
-      <div class="tl cur"><div class="ph">v1 · сейчас</div><h4>Цикл моделирования</h4><p>Документы, эскизы, выдавливание/вырез, вращение, выборка граней</p></div>
-      <div class="tl"><div class="ph">v2</div><h4>Операции</h4><p>Скругление, фаска, оболочка, ребро, лофт, кинематика, массивы</p></div>
+      <div class="tl" style="border-color:var(--green)"><div class="ph" style="color:var(--green)">v1 · готово ✓</div><h4>Цикл моделирования</h4><p>Документы, эскизы, выдавливание/вырез, снимок модели — работает</p></div>
+      <div class="tl cur"><div class="ph">v2 · далее</div><h4>Операции и выборка</h4><p>Выбор граней, эскиз на грани, вращение, скругление/фаска, массивы</p></div>
      <div class="tl"><div class="ph">v3</div><h4>Параметрика</h4><p>Переменные <code>IVariable7</code>, свойства <code>IPropertyMng</code>, формулы</p></div>
      <div class="tl"><div class="ph">v4</div><h4>2D-черчение</h4><p>Виды, размеры, тексты, штриховки; спецификации</p></div>
      <div class="tl"><div class="ph">v5</div><h4>Сборки и экспорт</h4><p>Компоненты, сопряжения, конвертеры (STEP), HTTP/SSE-транспорт</p></div>
@@ -331,8 +330,10 @@
  <div class="wrap">
    <div>КОМПАС-3D MCP · документация проекта</div>
    <div class="links">
+      <a href="../README.md">📦 README</a>
      <a href="ARCHITECTURE.md">📐 Документ архитектуры</a>
      <a href="IMPLEMENTATION_PLAN.md">🛠️ План реализации</a>
+      <a href="OPEN_QUESTIONS.md">❓ Открытые вопросы</a>
      <a href="../CLAUDE.md">📘 CLAUDE.md</a>
      <a href="KOMPAS_SDK_ru-RU/index.html">📚 Справка SDK КОМПАС-3D</a>
      <a href="https://help.ascon.ru/KOMPAS_SDK/22/ru-RU/index.html">🌐 Онлайн-справка АСКОН</a>