Metadata-Version: 2.5
Name: kompas3d-bridge-mcp
Version: 0.0.2
Summary: Standalone stdio MCP bridge over a live KOMPAS session (single run_python tool)
License-Expression: MIT
Requires-Python: >=3.12
Requires-Dist: fastmcp==3.2.4
Requires-Dist: kompas-kernel>=0.0.1
Requires-Dist: mcp==1.28.1
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Description-Content-Type: text/markdown

# Инструкция по запуску kompas3d-bridge-mcp

## Предварительные требования

1. **Открытый KOMPAS-3D** — должен быть запущен **ровно один** экземпляр `KOMPAS.exe` (visible, не в фоне).
2. **KOMPAS_BIN_DIR** — путь к каталогу с SDK файлами той же установки КОМПАС, что запущена.
   - Обычно: `C:\Program Files\ASCON\KOMPAS-3D vXX\Bin` или `C:\Program Files\ASCON\KOMPAS-3D vXX\Bin(x64)` (XX — версия, напр. v24, v25)
   - В этом каталоге **обязательно** должны лежать: `ksapi.py`, `constants.py`, `constants3d.py`, `ksAPICLink.dll`
   - Рядом (в родительской папке) должен быть `KOMPAS.exe`
   - **Найти свой путь:** `dir "C:\Program Files\ASCON\KOMPAS-3D*"` → проверьте `Bin` и `Bin(x64)`
3. **Python 3.12+** — пакет установится через `pip`.

---

## Установка (после публикации на PyPI)

```bash
pip install kompas3d-bridge-mcp
```

Проверка:

```bash
kompas3d-bridge-mcp --help
```

## Запуск (stdio MCP)

```bash
kompas3d-bridge-mcp \
  --kompas-bin-dir "C:\Program Files\ASCON\KOMPAS-3D v25\Bin" \
  --session-dir "C:\temp\kompas-bridge-session" \
  --log-file "C:\temp\kompas-bridge.log" \
  --log-level INFO \
  --transport stdio
```

> **Важно:** путь может быть `Bin` или `Bin(x64)` — проверьте, где лежат `ksapi.py`, `constants.py`, `constants3d.py`, `ksAPICLink.dll`.

### Параметры

| Параметр           | Описание                                                                                            | Пример                                          |
| ------------------ | --------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| `--kompas-bin-dir` | **Обязательно.** Путь к каталогу с SDK файлами **запущенного** KOMPAS (`Bin` или `Bin(x64)`).     | `C:\Program Files\ASCON\KOMPAS-3D v25\Bin`      |
| `--session-dir`    | **Обязательно.** Каталог для чекпоинтов (rollback при ошибке). Создаётся автоматически.             | `C:\temp\kompas-bridge-session`                 |
| `--log-file`       | **Обязательно.** Путь к ротационному JSON-логу (stderr также логирует).                             | `C:\temp\kompas-bridge.log`                     |
| `--log-level`      | Уровень логирования.                                                                                | `INFO`, `DEBUG`, `WARNING`                      |
| `--transport`      | Только `stdio` (MCP-протокол через stdin/stdout).                                                   | `stdio`                                         |

---

## Подключение к AI-агентам (MCP-клиентам)

После установки (`pip install kompas3d-bridge-mcp`) и проверки `kompas3d-bridge-mcp --help`, добавьте сервер в конфиг вашего агента.

### opencode (`~/.config/opencode/opencode.json` или `~/.opencode.json`)

```json
{
  "mcp": {
    "servers": {
      "kompas3d-bridge": {
        "command": "kompas3d-bridge-mcp",
        "args": [
          "--kompas-bin-dir",
          "C:/Program Files/ASCON/KOMPAS-3D v25/Bin",
          "--session-dir",
          "C:/temp/kompas-bridge-session",
          "--log-file",
          "C:/temp/kompas-bridge.log",
          "--log-level",
          "INFO",
          "--transport",
          "stdio"
        ]
      }
    }
  }
}
```

> **Важно:** путь может быть `Bin` или `Bin(x64)` — проверьте, где лежат `ksapi.py`, `constants.py`, `constants3d.py`, `ksAPICLink.dll`.
> **Перезапустите opencode** после изменения конфига.

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

1. Откройте **KOMPAS-3D** (ровно один экземпляр).
2. Перезапустите агент / клиент.
3. В чате агента должно появиться уведомление: _«MCP server "kompas3d-bridge" connected»_ или значок 🔧 / 🔌.
4. Спросите: **«Какие инструменты доступны у kompas3d-bridge?»** — агент должен перечислить 11 tools.
5. Тест: **«Покажи открытые документы в KOMPAS»** → вызов `document.list`.

---

### Важные нюансы

| Нюанс                         | Детали                                                                         |
| ----------------------------- | ------------------------------------------------------------------------------ |
| **Пути в JSON**               | Используйте прямые слэши `/` или двойные обратные `\\\\`                       |
| **Команда**                   | После `pip install` — просто `kompas3d-bridge-mcp` (в PATH)                    |
| **KOMPAS должен быть открыт** | Перед запуском агента откройте KOMPAS-3D. Bridge не запускает его сам.         |
| **Один экземпляр**            | Не запускайте bridge одновременно с KOMPAS Copilot против того же `KOMPAS.exe` |
| **Логи**                      | Если инструменты не появляются — проверьте `--log-file` и stderr               |

---

### Пример после успешного подключения

В чате агента:

```
User: Какие документы открыты в KOMPAS?
Assistant: [вызывает document.list]
→ Возвращает список: "Сборка1.m3d", "Деталь1.m3d"

User: Сделай скриншот активного вида
Assistant: [вызывает view.screenshot]
→ Возвращает base64 PNG

User: Найди в SDK как создать выдавливание
Assistant: [вызывает api.search с query="extrusion"]
→ Возвращает интерфейсы IExtrusion, методы SetSideParameters и т.д.

User: Выполни код: создай эскиз на XOY прямоугольник 50x30 и выдавли на 10мм
Assistant: [вызывает code.execute с Python-кодом]
→ Создаёт геометрию в KOMPAS
```

---

## Доступные инструменты (MCP tools)

После подключения клиент увидит:

| Инструмент           | Категория | Статус   | Описание                                                                                                                      |
| -------------------- | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `document.list`      | read      | ✅ Реальный | Список открытых документов                                                                                                    |
| `document.get`       | read      | ✅ Реальный | Детали документа по ID                                                                                                        |
| `document.create`    | update    | ✅ Реальный | Создать новый документ                                                                                                        |
| `document.open`      | update    | ✅ Реальный | Открыть существующий файл                                                                                                     |
| `document.save`      | update    | ✅ Реальный | Сохранить документ                                                                                                            |
| `document.close`     | update    | ✅ Реальный | Закрыть документ                                                                                                              |
| `operation.list`     | read      | ✅ Реальный | Дерево операций (фич) документа                                                                                               |
| `operation.get`      | read      | ✅ Реальный | Детали операции + интерфейсы SDK                                                                                              |
| `view.screenshot`    | read      | ✅ Реальный | Скриншот вида (проекция)                                                                                                      |
| `api.search`         | read      | ⚠️ Заглушка | Поиск по SDK (интерфейсы, методы, константы) — **фиксированный список 5 записей**                                           |
| `code.execute`       | execute   | ✅ Реальный | **Единственный исполняющий инструмент** — запускает Python-код в сессии КОМПАС через статический гейт + обязательный чекпоинт |
| `ui.back`            | update    | ⚠️ Заглушка | Шаг назад в истории — **пустой HistoryStep**                                                                                  |
| `ui.forward`         | update    | ⚠️ Заглушка | Шаг вперёд в истории — **пустой HistoryStep**                                                                                 |

> **⚠️ Важно:** `api.search`, `ui.back`, `ui.forward` — заглушки. Они работают, но возвращают фиктивные/пустые данные. Реальная реализация требует доступа к справке SDK и Undo/Redo API.

---

## Заглушки (stubs) в текущем срезе

| Инструмент | Что возвращает | Что нужно для реальной реализации |
|------------|----------------|-----------------------------------|
| `api.search` | Хардкодный список из 5 записей (GetDocuments, Add, Open, Save, Close) | Парсинг справки SDK / RAG-индекс |
| `ui.back` / `ui.forward` | Пустой `HistoryStep` (direction + пустой `change`) | COM API истории: `IView.GetHistory`, `Undo`/`Redo` |

> Планируется: `api.search` — через RAG-слой; `ui.*` — через COM API истории (отдельный feature).

---

## Что НЕ реализовано (текущий срез)

| Область | Что отсутствует | Планируется / примечание |
|---------|-----------------|--------------------------|
| **Транспорт** | Только `stdio`. Нет HTTP/SSE/WebSocket | Для встраивания в веб-UI нужен отдельный транспорт |
| **Только чтение** | Нет tools для: создание эскизов, операции 3D (выдавливание, рез, массив), работа со сборками (вставка компонентов, сборные единицы), черчение 2D | Планируется через `code.execute` + рецепты |
| **Выбор/селекция** | Нет `selection.get` / `selection.set` — получить/задать выделенные объекты в UI | Нужен доступ к `IView.GetSelectedObjects` |
| **Свойства объектов** | Нет `property.get` / `property.set` — чтение/запись атрибутов (материал, цвет, наименование) | Через `code.execute` доступно |
| **Параметризация** | Нет `parameter.list` / `parameter.set` — переменные модели, таблицы параметров | Через `code.execute` доступно |
| **Спецификации/Вedomости** | Нет работы с БД спецификаций, ведомостей деталей | Планируется отдельным feature-слоем |
| **PDM/КОМПАС-Сервер** | Нет интеграции с КОМПАС-Сервер / PDM | Требует отдельного API |
| **Events/подписки** | Нет MCP notifications на изменения в документе | `KompasSession` не экспонирует события наружу |
| **Несколько документов** | Один bridge = одна сессия = работа с открытыми документами. Нет tool для переключения контекста между документами | `document.list` + `document.get` покрывают базу |
| **Approval protocol** | Нет встроенного approval workflow. Клиент видит только MCP annotations (`destructiveHint`) | Ожидается на стороне клиента |
| **Resources/Prompts** | MCP Resources и Prompts не экспонируются | Только Tools |
| **Мультиплексирование** | Нельзя подключить несколько клиентов к одному bridge | Один процесс = один клиент |

---

## Безопасность и ограничения

- **Один процесс bridge = одна сессия KOMPAS**. Не запускайте одновременно с KOMPAS Copilot против того же `KOMPAS.exe`.
- **Код выполняется только через `code.execute`** — он проходит статический гейт (проверка имён SDK) и требует свежий чекпоинт. Без чекпоинта код не запустится.
- При ошибке после начала исполнения — автоматический rollback к чекпоинту.
- `KOMPAS.exe` **не останавливается** при завершении bridge.
- MCP annotations: `destructiveHint=true` у `code.execute` и мутирующих document/ui инструментов.

---

## Логи и диагностика

- **stdout** — чистый MCP-протокол (JSON-RPC), не читать человеком.
- **stderr + `--log-file`** — структурированные логи (structlog, JSON).
- Уровень `DEBUG` даёт детали: вызовы SDK, чекпоинты, timing.

---

## Пример использования (через MCP-клиент)

1. Откройте KOMPAS-3D (один экземпляр).
2. Запустите MCP-клиент с конфигом выше.
3. В чате клиента: _«Покажи список открытых документов»_ → вызовется `document.list`.
4. _«Выполни код: создай эскиз на XOY и выдавли в куб 10мм»_ → вызовется `code.execute` с Python-кодом через KsAPI.

---
