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
@@ -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.