Metadata-Version: 2.5
Name: kompas3d-bridge-mcp
Version: 0.0.1
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

Отдельный stdio MCP над живой сессией КОМПАС. Первый срез публикует ровно один
tool — `run_python` — с тем же статическим гейтом и обязательным checkpoint, что
domain-операция в `kompas-kernel`.

Поверхность инструментов (имя, описание, schemas, annotations) — в generated
[`TOOLS.md`](TOOLS.md). Не дублируйте её вручную.

## Установка

Нужны локальные wheel `kompas-kernel` и `kompas3d-bridge-mcp` (registry за kernel
не ходим):

```bash
uv build --wheel packages/kompas-kernel -o wheelhouse
uv build --wheel packages/kompas3d-bridge-mcp -o wheelhouse
python -m venv .venv-bridge
.venv-bridge/Scripts/python -m pip install wheelhouse/kompas_kernel-*.whl wheelhouse/kompas3d_bridge_mcp-*.whl
```

## Запуск

Backend **не** стартует КОМПАС: нужен один уже открытый visible `KOMPAS.exe`.
Все параметры обязательны и явны.

```bash
kompas3d-bridge-mcp \
  --kompas-bin-dir <Bin(x64)> \
  --session-dir <dir> \
  --log-file <path> \
  --log-level INFO \
  --transport stdio
```

| Параметр | Назначение |
|---|---|
| `--kompas-bin-dir` | каталог с `ksapi.py` / `constants*.py` / `ksAPICLink` |
| `--session-dir` | корень checkpoint registry этого процесса |
| `--log-file` | ротационный JSON-лог |
| `--log-level` | уровень structlog/logging |
| `--transport` | только `stdio` |

stdout принадлежит MCP-протоколу; логи — stderr и `--log-file`.

## MCP client (пример)

```json
{
  "mcpServers": {
    "kompas3d-bridge": {
      "command": "kompas3d-bridge-mcp",
      "args": [
        "--kompas-bin-dir", "C:/path/to/Bin(x64)",
        "--session-dir", "C:/path/to/bridge-session",
        "--log-file", "C:/path/to/bridge.log",
        "--log-level", "INFO",
        "--transport", "stdio"
      ]
    }
  }
}
```

## Владение процессом

- Один процесс bridge владеет одной `KompasSession`.
- Не запускайте одновременно с KOMPAS Copilot против того же `KOMPAS.exe`.
- Завершение клиента закрывает worker; `KOMPAS.exe` не останавливается.

## Безопасность

- Код проходит статический gate до исполнения.
- Обязательный свежий checkpoint; без снимка код не запускается.
- Ошибка после начала исполнения откатывает документ.
- Собственного approval-протокола нет: клиент видит MCP annotations
  (`destructiveHint=true`, …) — см. `TOOLS.md`.

## Сверка документации tools

```bash
python -m kompas3d_bridge_mcp.tool_docs --write
python -m kompas3d_bridge_mcp.tool_docs --check
```
