Metadata-Version: 2.5
Name: kompas3d-bridge-mcp
Version: 0.0.4
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`.
2. **KOMPAS_BIN_DIR** — путь к каталогу `Bin` той же установки КОМПАС, что запущена.

   **Windows:**
   - Обычно: `C:\Program Files\ASCON\KOMPAS-3D v25\Bin`
   - В этом каталоге **обязательно** должны лежать: `ksapi.py`, `constants.py`, `constants3d.py`, `ksAPICLink.dll`
   - Рядом (в родительской папке) должен быть `KOMPAS.exe`

   **Linux:**
   - Обычно: `/opt/ascon/kompas3d-v25/Bin`
   - В этом каталоге **обязательно** должны лежать: `ksapi.py`, `constants.py`, `constants3d.py`, `libksAPICLink.so`, `kKompas`

3. **Python 3.12+** — пакет установится через `pip`.

---

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

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

Проверка:

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

---

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

**Windows:**

```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
```

**Linux:**

```bash
kompas3d-bridge-mcp \
  --kompas-bin-dir "/opt/ascon/kompas3d-v25/Bin" \
  --session-dir "/tmp/kompas-bridge-session" \
  --log-file "/tmp/kompas-bridge.log" \
  --log-level INFO \
  --transport stdio
```

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

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

---

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

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

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

**Windows:**

```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"
        ]
      }
    }
  }
}
```

**Linux:**

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "kompas3d-bridge": {
      "type": "local",
      "command": [
        "kompas3d-bridge-mcp",
        "--kompas-bin-dir",
        "/opt/ascon/kompas3d-v25/Bin",
        "--session-dir",
        "/tmp/kompas-bridge-session",
        "--log-file",
        "/tmp/kompas-bridge.log",
        "--log-level",
        "INFO",
        "--transport",
        "stdio"
      ],
      "enabled": true
    }
  }
}
```

> **Перезапустите opencode** после изменения конфига.

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

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

---

## Доступные инструменты (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`, `view.screenshot`, `ui.back`, `ui.forward` — заглушки. Они работают, но возвращают фиктивные/пустые данные. Реальная реализация требует доступа к справке SDK и Undo/Redo API.

---

## Уточнение требований к `api.search` и `view.screenshot`

В текущей поставке MCP-сервера `kompas3d-bridge-mcp` два инструмента реализованы как заглушки:

- **`api.search`** — возвращает фиксированный мок-список из 5 записей; полноценный поиск по SDK не реализован.
- **`view.screenshot`** — возвращает пустой результат; генерация скриншота не реализована.

Нам нужны **оформленные требования (ТЗ/ADR) к ВЫХОДУ (возвращаемому клиенту)** — что именно должен вернуть каждый инструмент MCP-клиенту (AI-агенту).

### `api.search` — что возвращает клиенту

Опишите **структуру одного результата поиска** (JSON-объект):

- какие поля: `name`, `type` (interface/method/constant/example), `signature`, `description`, `example_url`, `version` и т.д.
- обязательные vs опциональные поля
- формат ответа: список объектов, пагинация, скоринг/релевантность

### `view.screenshot` — что возвращает клиенту

Опишите **формат возвращаемого изображения**:

- base64 PNG/JPEG, data URL, или путь к временному файлу (MCP-протокол поддерживает resource URI)
- метаданные: проекция, разрешение, формат, timestamp
- структура ответа: один объект с `image` + `meta`, или массив для нескольких проекций
