mlspace-plugin 0.3.2__tar.gz → 0.3.4__tar.gz

{mlspace_plugin-0.3.2 → mlspace_plugin-0.3.4}/.env.example

@@ -30,6 +30,9 @@ MLSPACE_BASE_URL=https://api.ai.cloud.ru
 MLSPACE_READONLY=false                # true hides and blocks all 58 write actions
                                       # when writes are enabled, destructive actions
                                       # additionally require confirm=true
+# Account-wide password rotation is blocked unless the operator explicitly opts in.
+# Enable only for an approved rotation, then disable and restart the MCP server.
+# MLSPACE_ALLOW_REGISTRY_PASSWORD_ROTATION=false
 MLSPACE_TRANSPORT=streamable-http     # streamable-http | stdio
 MLSPACE_HOST=127.0.0.1                # loopback only (no server-side auth in v1)
 MLSPACE_PORT=8000

{mlspace_plugin-0.3.2 → mlspace_plugin-0.3.4}/INSTALL.md

@@ -21,7 +21,7 @@ mlspace-plugin setup
 ```
 
 Если пакет уже установлен: `uv tool install --force .`.
-При установке из wheel: `uv tool install /путь/к/mlspace_plugin-0.3.2-py3-none-any.whl`.
+При установке из wheel: `uv tool install /путь/к/mlspace_plugin-0.3.4-py3-none-any.whl`.
 Не используйте editable-установку из `/tmp` для постоянной работы.
 Далее команды показаны для PyPI. После установки исходников или wheel через
 `uv tool install` заменяйте `uvx mlspace-plugin@latest` на `mlspace-plugin`,
@@ -43,7 +43,7 @@ mlspace-plugin setup
 
 Если настройка клиента не завершилась, проверенные ключи остаются сохранёнными.
 Мастер перечислит установленные клиенты; устраните причину и выполните напечатанную
-команду `Retry`. Она сохраняет выбор клиентов, включая незавершённые подключения.
+команду после «Повторите команду». Она сохраняет выбор клиентов, включая незавершённые подключения.
 
 Откройте новую сессию выбранного клиента; если MCP не появился, перезапустите клиент.
 Сервер запускается клиентом автоматически. Первый запрос:

{mlspace_plugin-0.3.2 → mlspace_plugin-0.3.4}/INSTALL_AGENT.md

@@ -41,7 +41,7 @@
    запустить ту же команду без `--non-interactive`, сохранив endpoint, путь и выбор клиентов.
    Для конфликта нативного плагина Claude/Codex разберите указанный несекретный путь;
    не удаляйте чужую интеграцию автоматически.
-   При частичном успехе сообщите, какие этапы завершены, и используйте команду `Retry`
+   При частичном успехе сообщите, какие этапы завершены, и используйте команду после «Повторите команду»
    из ошибки: она сохраняет выбор незавершённых подключений. Для автоматизации
    добавьте прежние `--non-interactive` и `--workspace`.
 

{mlspace_plugin-0.3.2 → mlspace_plugin-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mlspace-plugin
-Version: 0.3.2
+Version: 0.3.4
 Summary: Cloud.ru MLSpace plugin: MCP server, agent skills and setup
 Project-URL: Repository, https://github.com/noesskeetit/mlspace-plugin
 Project-URL: Issues, https://github.com/noesskeetit/mlspace-plugin/issues
@@ -290,15 +290,21 @@ write-запросов подаются параметром `body: dict`; об
 Для других агентов предусмотрены Agent Plugins 1.0, Agent Skills и обычное
 MCP-подключение; поддержку конкретного загрузчика нужно проверять отдельно.
 Пошаговые сценарии поставляются только скиллами плагина; сервер отдаёт общие правила
-в instructions. `tests/test_skills.py` сверяет скиллы с реальными инструментами.
+в instructions. Ключевые правила подачи ответа также включены в описания инструментов
+для клиентов, которые не передают модели instructions сервера.
+`tests/test_skills.py` сверяет скиллы с реальными инструментами.
 
 ---
 
 ## Безопасность
 
 - **Гейт подтверждения**: 16 необратимых действий (удаления, отзыв доступа,
-  отмена переноса, ротация пароля реестра) требуют `confirm=true`. Это основной
-  рубеж в конфигурации по умолчанию.
+  отмена переноса, ротация пароля реестра) требуют `confirm=true`.
+- **Смена пароля Registry выключена по умолчанию**, поскольку затрагивает личный
+  аккаунт и уже работающие подключения. После согласования ротации оператор может
+  задать `MLSPACE_ALLOW_REGISTRY_PASSWORD_ROTATION=true` в конфигурации сервера и
+  перезапустить MCP. `setup` не включает этот параметр. После операции выключите его
+  и снова перезапустите MCP. Флаг инструмента `confirm=true` не обходит этот запрет.
 - **Режим read-only** (`MLSPACE_READONLY=true`): все 58 write-действий исчезают
   из `action`-перечня — модель их не видит — и блокируются в рантайме как
   страховка. По умолчанию **выключен**: сервер задуман как рабочий инструмент, а
@@ -313,13 +319,27 @@ MCP-подключение; поддержку конкретного загру
   общего сервера. Жизненный цикл воркспейса — только через консоль.
 - **Сеть**: HTTP-транспорт отказывается слушать не-loopback адрес (в v1 нет
   серверной аутентификации).
-- **Секреты в ответах** (пароль registry, api-key воркспейса) редактируются.
+- **Секреты в ответах** (пароль Registry, API key воркспейса) по умолчанию
+  маскируются. Для задачи, которой нужно реальное значение, действия
+  `mlspace_docker_registry(action="generate_password")` и
+  `mlspace_workspaces(action="get_api_key")` принимают `reveal_secret=true`
+  вместе с `confirm=true`. Это раскрывает секрет в результате инструмента:
+  он становится доступен модели и может сохраниться в истории MCP-клиента.
+  Флаг действует только на эти операции, а не отключает маскирование глобально.
+  `generate_password` меняет пароль; агент должен получить разрешение на ротацию
+  и передать `reveal_secret=true` сразу, если новый пароль нужен для `docker login`.
+  Для входа используйте `--password-stdin`; не помещайте пароль в обычный ответ,
+  документацию или репозиторий. Обычным MCP-запросам ручное получение ключа не нужно.
 
 > Важно про `confirm`: этот флаг ставит **сам агент** в том же вызове. Это защита от
 > случайного действия, а **не** human-in-the-loop. Подтверждение человеком обеспечивает
-> окно вашего MCP-клиента, которому мы помогаем аннотацией `destructiveHint`.
-> Единственный рубеж, который агент обойти не может, — `MLSPACE_READONLY=true`;
-> в конфигурации по умолчанию его нет, и решение остаётся за клиентом.
+> клиент, если в нём настроено согласование операций; `destructiveHint` — лишь подсказка.
+> `reveal_secret` также является явным запросом агента, а не отдельным окном согласия.
+> `MLSPACE_READONLY=true` блокирует изменения, включая ротацию пароля, но не чтение
+> workspace API key с явным раскрытием. Это не режим запрета экспорта секретов.
+> Агент с доступом к изменению конфигурации сервера способен изменить и его ограничения;
+> настройки MCP не заменяют права доступа в API и клиенте. После явного раскрытия секрета
+> сервер не может гарантировать, что модель не повторит его в своём ответе.
 
 ---
 

{mlspace_plugin-0.3.2 → mlspace_plugin-0.3.4}/README.md

@@ -239,15 +239,21 @@ write-запросов подаются параметром `body: dict`; об
 Для других агентов предусмотрены Agent Plugins 1.0, Agent Skills и обычное
 MCP-подключение; поддержку конкретного загрузчика нужно проверять отдельно.
 Пошаговые сценарии поставляются только скиллами плагина; сервер отдаёт общие правила
-в instructions. `tests/test_skills.py` сверяет скиллы с реальными инструментами.
+в instructions. Ключевые правила подачи ответа также включены в описания инструментов
+для клиентов, которые не передают модели instructions сервера.
+`tests/test_skills.py` сверяет скиллы с реальными инструментами.
 
 ---
 
 ## Безопасность
 
 - **Гейт подтверждения**: 16 необратимых действий (удаления, отзыв доступа,
-  отмена переноса, ротация пароля реестра) требуют `confirm=true`. Это основной
-  рубеж в конфигурации по умолчанию.
+  отмена переноса, ротация пароля реестра) требуют `confirm=true`.
+- **Смена пароля Registry выключена по умолчанию**, поскольку затрагивает личный
+  аккаунт и уже работающие подключения. После согласования ротации оператор может
+  задать `MLSPACE_ALLOW_REGISTRY_PASSWORD_ROTATION=true` в конфигурации сервера и
+  перезапустить MCP. `setup` не включает этот параметр. После операции выключите его
+  и снова перезапустите MCP. Флаг инструмента `confirm=true` не обходит этот запрет.
 - **Режим read-only** (`MLSPACE_READONLY=true`): все 58 write-действий исчезают
   из `action`-перечня — модель их не видит — и блокируются в рантайме как
   страховка. По умолчанию **выключен**: сервер задуман как рабочий инструмент, а
@@ -262,13 +268,27 @@ MCP-подключение; поддержку конкретного загру
   общего сервера. Жизненный цикл воркспейса — только через консоль.
 - **Сеть**: HTTP-транспорт отказывается слушать не-loopback адрес (в v1 нет
   серверной аутентификации).
-- **Секреты в ответах** (пароль registry, api-key воркспейса) редактируются.
+- **Секреты в ответах** (пароль Registry, API key воркспейса) по умолчанию
+  маскируются. Для задачи, которой нужно реальное значение, действия
+  `mlspace_docker_registry(action="generate_password")` и
+  `mlspace_workspaces(action="get_api_key")` принимают `reveal_secret=true`
+  вместе с `confirm=true`. Это раскрывает секрет в результате инструмента:
+  он становится доступен модели и может сохраниться в истории MCP-клиента.
+  Флаг действует только на эти операции, а не отключает маскирование глобально.
+  `generate_password` меняет пароль; агент должен получить разрешение на ротацию
+  и передать `reveal_secret=true` сразу, если новый пароль нужен для `docker login`.
+  Для входа используйте `--password-stdin`; не помещайте пароль в обычный ответ,
+  документацию или репозиторий. Обычным MCP-запросам ручное получение ключа не нужно.
 
 > Важно про `confirm`: этот флаг ставит **сам агент** в том же вызове. Это защита от
 > случайного действия, а **не** human-in-the-loop. Подтверждение человеком обеспечивает
-> окно вашего MCP-клиента, которому мы помогаем аннотацией `destructiveHint`.
-> Единственный рубеж, который агент обойти не может, — `MLSPACE_READONLY=true`;
-> в конфигурации по умолчанию его нет, и решение остаётся за клиентом.
+> клиент, если в нём настроено согласование операций; `destructiveHint` — лишь подсказка.
+> `reveal_secret` также является явным запросом агента, а не отдельным окном согласия.
+> `MLSPACE_READONLY=true` блокирует изменения, включая ротацию пароля, но не чтение
+> workspace API key с явным раскрытием. Это не режим запрета экспорта секретов.
+> Агент с доступом к изменению конфигурации сервера способен изменить и его ограничения;
+> настройки MCP не заменяют права доступа в API и клиенте. После явного раскрытия секрета
+> сервер не может гарантировать, что модель не повторит его в своём ответе.
 
 ---
 

{mlspace_plugin-0.3.2 → mlspace_plugin-0.3.4}/RELEASE.md

@@ -7,11 +7,11 @@
    `uv lock` и `uv run python scripts/gen_plugin.py`. Обновите примеры имён wheel/ZIP
    в инструкциях, если версия присутствует в имени файла.
 2. Выполните проверки из `CONTRIBUTING.md` на Linux и macOS.
-3. Соберите пакет (в командах ниже замените 0.3.2 на выпускаемую версию):
+3. Соберите пакет (в командах ниже замените 0.3.4 на выпускаемую версию):
 
 ```sh
-uv build --out-dir dist/release-0.3.2
-uv run python scripts/build_plugin.py --output dist/plugin-release-0.3.2
+uv build --out-dir dist/release-0.3.4
+uv run python scripts/build_plugin.py --output dist/plugin-release-0.3.4
 ```
 
 4. Просмотрите содержимое wheel, sdist и ZIP. В них не должно быть credentials,
@@ -23,11 +23,11 @@ uv run python scripts/build_plugin.py --output dist/plugin-release-0.3.2
    `UV_PUBLISH_TOKEN` средствами вашего хранилища секретов, не аргументом команды:
 
 ```sh
-uv publish --trusted-publishing never dist/release-0.3.2/mlspace_plugin-0.3.2-py3-none-any.whl dist/release-0.3.2/mlspace_plugin-0.3.2.tar.gz
+uv publish --trusted-publishing never dist/release-0.3.4/mlspace_plugin-0.3.4-py3-none-any.whl dist/release-0.3.4/mlspace_plugin-0.3.4.tar.gz
 ```
 
 6. Проверьте версию и SHA256 обоих файлов через PyPI JSON API; проверьте установку
-   `uvx --from mlspace-plugin==0.3.2 mlspace-plugin --version` из нового кеша.
+   `uvx --from mlspace-plugin==0.3.4 mlspace-plugin --version` из нового кеша.
 7. Только после проверки точной версии в PyPI обновите рабочую ветку GitHub
    marketplace и создайте тег релиза. До этого проверяйте изменения на отдельной
    release-ветке или локальном Git marketplace: main не должен ссылаться на

{mlspace_plugin-0.3.2 → mlspace_plugin-0.3.4}/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mlspace",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Cloud.ru MLSpace: training jobs, inference, notebooks, data transfer, registry and compute catalog — an MCP server plus skills.",
   "author": {
     "name": "Cloud.ru"

{mlspace_plugin-0.3.2 → mlspace_plugin-0.3.4}/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mlspace",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Cloud.ru MLSpace: training jobs, inference, notebooks, data transfer, registry and compute catalog — an MCP server plus skills.",
   "author": {
     "name": "Cloud.ru"

{mlspace_plugin-0.3.2 → mlspace_plugin-0.3.4}/plugin/.mcp.json

@@ -5,7 +5,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "mlspace-plugin==0.3.2",
+        "mlspace-plugin==0.3.4",
         "mlspace-plugin",
         "--transport",
         "stdio"

{mlspace_plugin-0.3.2 → mlspace_plugin-0.3.4}/plugin/mcp.json

@@ -6,7 +6,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "mlspace-plugin==0.3.2",
+        "mlspace-plugin==0.3.4",
         "mlspace-plugin",
         "--transport",
         "stdio"

{mlspace_plugin-0.3.2 → mlspace_plugin-0.3.4}/plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "mlspace",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Cloud.ru MLSpace: training jobs, inference, notebooks, data transfer, registry and compute catalog — an MCP server plus skills.",
   "author": {
     "name": "Cloud.ru"

mlspace_plugin-0.3.4/plugin/skills/mlspace-diagnose-data-transfer/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: mlspace-diagnose-data-transfer
+description: "Diagnose a failed / partial data transfer on Cloud.ru MLSpace. Did my data transfer actually fail / land incompletely, and why. Uses the mlspace_data_transfer tools."
+license: MIT
+compatibility: Requires the `mlspace` MCP server from this plugin (Cloud.ru MLSpace credentials needed).
+---
+
+# Diagnose a failed / partial data transfer
+
+Did my data transfer actually fail / land incompletely, and why.
+
+This skill drives the `mlspace` MCP server shipped in the same plugin. If its
+tools are not connected, say so instead of guessing — none of these steps can be
+carried out any other way.
+
+## Arguments
+
+- `transfer_id` — Transfer id (or give a name).
+- `transfer_name` — Transfer name to look up.
+- `expected_rows` — Rows you expected, to judge completeness.
+- `act` — If true, may rerun a failed run (after confirm).
+- `target` — Connected workspace ID or unambiguous name, if scoped.
+
+## Procedure
+
+Final-answer contract:
+- **Status and reported counters**: observations returned by the API.
+- **Failure cause and phase**: use explicit matching log evidence; otherwise unknown.
+- **Data impact**: unknown until an independent source/destination contents check
+  establishes it. Even a known cause such as AccessDenied at PutObject does not
+  establish whether other writes in the run already happened. A known cause and
+  unknown data impact can both be true. Zero counters are not that contents check.
+
+The tool's `_mcp_evidence` describes the limits of those observations, not an API
+defect or a separate user-facing warning. Never translate zero counters into
+"the run failed before transfer started" or "nothing was read/written".
+
+Goal: determine whether a data transfer truly failed / was partial, and why.
+1. Resolve the transfer: if transfer_id given use it, else data_transfer list_transfers
+   and match transfer_name.
+2. data_transfer list_history (transfer_id, page=1, page_size=20 — this endpoint uses
+   page/page_size). Take the latest run's history_id + metrics (size_bytes, rows_count,
+   progress, status).
+3. data_transfer get_history_status (ids=[history_id]) for the authoritative status
+   (in_progress|success|failed|cancelled).
+4. If failed/cancelled, data_transfer get_event_logs (history_id, offset=0, limit=50,
+   as_enum_resolved=true) for the decoded reason.
+   If events are empty, retain the failed/cancelled status and inspect the matching
+   history entry and existing connector logs. Do not call try_connector merely to
+   read logs: it can activate the connector. Treat a value such as not_found as an
+   observation, not proof of a missing SQL table; that cause needs supporting logs
+   or a separate authorized check. Never invent the reason for failure.
+5. Compare rows_count/size_bytes vs the user's expectation to judge "partial".
+   These are reported counters, not an audit of source/destination contents.
+   Even zero bytes/rows/progress does not prove the run never started, identify
+   its failure phase, or prove data was unchanged. Do not claim any of those
+   without independent evidence. Distinguish "this diagnostic made no changes"
+   from "the earlier transfer made no changes". A connector's saved success
+   status is not a fresh connection test and does not establish current health.
+Output: status + hard numbers (rows/bytes/progress) + completeness verdict + decoded
+event reasons; separate "genuinely failed" from "clean exit / fewer rows than expected".
+When failure logs are empty, conclude that the cause and data impact are unknown.
+Report the counters as observations; do not turn them into a narrative about which
+execution phase failed. Suggest the next read-only check instead of inventing a cause.
+If no evidence identifies a failure phase, do not list speculative phases as the
+diagnosis. Rerunning is a write that may change destination data: never include it
+in a list of read-only checks or propose it when the user asked for read-only diagnosis.
+Only if act=true: rerun_history (body={history_id}) for a failed run, after confirming.
+For reasoning: status is only a 4-value enum; "finished but data looks wrong" is
+inferred from the numbers, not a dedicated field. In the answer, explain only the
+evidence and remaining uncertainty relevant to this run, not a general API audit.

mlspace_plugin-0.3.4/plugin/skills/mlspace-stage-s3-to-nfs/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: mlspace-stage-s3-to-nfs
+description: "Stage S3 data to NFS (one-off or nightly) on Cloud.ru MLSpace. Copy/sync S3 -> NFS for a GPU job, optionally on a schedule. Write action. Uses the mlspace_data_transfer tools."
+license: MIT
+compatibility: Requires the `mlspace` MCP server from this plugin (Cloud.ru MLSpace credentials needed).
+---
+
+# Stage S3 data to NFS (one-off or nightly)
+
+Copy/sync S3 -> NFS for a GPU job, optionally on a schedule. Write action.
+
+This skill drives the `mlspace` MCP server shipped in the same plugin. If its
+tools are not connected, say so instead of guessing — none of these steps can be
+carried out any other way.
+
+## Arguments
+
+- `source_hint` — Which S3 connector/bucket.
+- `destination_hint` — Which NFS/cluster connector.
+- `source_path` — Path within the source.
+- `destination_path` — Path within the NFS share.
+- `schedule` — Desired recurrence, start time and timezone, or a verified CronViewModel object.
+- `transfer_name` — Name for the transfer.
+- `cluster_name` — Target cluster name (required, not auto-derivable).
+- `target` — Connected workspace ID or unambiguous name, if scoped.
+
+## Procedure
+
+Goal: copy/sync S3 -> NFS, optionally on a nightly schedule (write actions;
+refused under MLSPACE_READONLY=true).
+1. data_transfer list_connectors with page=1, page_size=20; continue as needed to
+   locate the requested connectors. SOURCE: an object-storage connector (s3amazon/
+   s3custom/s3google). DEST: an NFS/cluster connector. Capture both connector ids.
+   Reuse existing system connectors rather than attempting to create them. A system
+   NFS connector may be absent from list output. For the selected destination
+   workspace, its workspace ID can be tested as a candidate via get_connector
+   (connector_type="nfs", id_=workspace ID); use it only after verifying the returned
+   connector belongs to the intended destination. Do not probe unrelated workspaces.
+2. cluster_name is required. Use a verified value from task context or consult the
+   configured endpoint's /public/v2/openapi.json, components.schemas.TransferClusterEnum
+   and TransferMultiClusterEnum. These describe accepted names, not current reachability
+   or access rights. Do not infer API names from UI labels or construct routes by
+   concatenating cluster names. If the requested route is absent, explain that the
+   direct route is not established; do not launch a multi-hop transfer without an
+   agreed intermediate destination and confirmation of both supported legs.
+   If names or destination remain ambiguous, ask the user.
+3. (optional, S3 only) try_connector to pre-check connectivity (+ its /try/logs).
+4. Ensure source_path + destination_path are known (ask if absent). Choose the
+   strategy from the user's overwrite/append/sync intent; recurrence alone does
+   not determine it. For a schedule, confirm the time and timezone and build
+   crontab as a CronViewModel JSON object (start_at, time, weekdays, monthdays,
+   period as applicable), never a cron-expression string. Verify the service's
+   field semantics before converting the requested recurrence; the schema alone
+   does not establish period units or timezone behavior. Do not guess fractional
+   periods or silently substitute a different interval. Read back the saved
+   schedule and compare it with the requested one before claiming success.
+   For a one-off run omit crontab; creation starts the transfer immediately.
+5. list_transfers; if one matches this source->dest and the user means "edit", capture
+   its id for update instead of create.
+6. create_transfer (body=TransferInputViewModelV5: name, connector ids, paths,
+   cluster_name, strategy, optional crontab) OR update_transfer(id_, full body).
+   To just enable/disable: switch_transfer(id_, body={"active": true|false}).
+7. Verify: list_history(transfer_id) -> latest run id + status; get_history_status.
+Output: source and destination, the created/updated transfer id, schedule with
+timezone, and verified run status. A future scheduled run has not succeeded yet.
+Before writing, summarize the destination, strategy and schedule for the user;
+do not dump the request body or connector credentials. Report any unverified
+schedule or incomplete result plainly; include API details only for diagnosis.

{mlspace_plugin-0.3.2 → mlspace_plugin-0.3.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mlspace-plugin"
-version = "0.3.2"
+version = "0.3.4"
 description = "Cloud.ru MLSpace plugin: MCP server, agent skills and setup"
 keywords = ["mlspace", "mcp", "agent-skills", "cloudru"]
 classifiers = [

{mlspace_plugin-0.3.2 → mlspace_plugin-0.3.4}/src/mlspace_mcp/__init__.py

@@ -1,4 +1,4 @@
 """mlspace_mcp — MCP server for the Cloud.ru MLSpace public API v2."""
 
-__version__ = "0.3.2"
+__version__ = "0.3.4"
 USER_AGENT = f"mlspace-plugin/{__version__}"

mlspace_plugin-0.3.4/src/mlspace_mcp/__main__.py

@@ -0,0 +1,125 @@
+"""CLI entry point for mlspace-plugin."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import sys
+from pathlib import Path
+
+from . import __version__
+from .config import load_settings, user_config_file
+from .server import build_server
+
+
+def _configure_logging() -> None:
+    """Basic stderr logging so the server's logger.warning/exception emit in prod.
+    Level via MLSPACE_LOG_LEVEL (default INFO). stderr keeps stdout clean for stdio MCP.
+    """
+    level = os.environ.get("MLSPACE_LOG_LEVEL", "INFO").upper()
+    logging.basicConfig(
+        level=getattr(logging, level, logging.INFO),
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+        stream=sys.stderr,
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="mlspace-plugin",
+        description="MCP-сервер для публичного API v2 Cloud.ru MLSpace.",
+    )
+    parser.add_argument("--version", action="version", version=f"mlspace-plugin {__version__}")
+    parser.add_argument(
+        "--transport",
+        choices=["streamable-http", "stdio"],
+        help="Использовать этот транспорт вместо MLSPACE_TRANSPORT.",
+    )
+    parser.add_argument(
+        "--list-tools",
+        action="store_true",
+        help="Показать доступные инструменты и завершить работу (ключи не нужны).",
+    )
+    # Optional subcommand: with none given the CLI serves, as it always has.
+    sub = parser.add_subparsers(dest="command")
+    setup = sub.add_parser(
+        "setup",
+        help="Настроить ключи доступа, воркспейсы, MCP-клиенты и skills.",
+        description=(
+            "Введите Cloud.ru Key ID и Cloud.ru Key Secret, выберите доступные воркспейсы MLSpace. Настройки сохраняются в "
+            f"{user_config_file()} с правами 0600 (доступ только вашему пользователю). Ввод выполняется в вашем терминале: ключи "
+            "не передаются модели. Оба поля скрыты звёздочками. Затем подключаются MCP и skills выбранных клиентов."
+        ),
+    )
+    setup.add_argument("--path", type=Path, help="Сохранить ключи и воркспейсы в указанный файл вместо стандартного файла настроек.")
+    setup.add_argument("--force", action="store_true", help="Повторить настройку существующего файла с сохранёнными ключами. Конфликты пользовательских skills требуют отдельного выбора.")
+    setup.add_argument(
+        "--base-url",
+        help="Сохранить этот HTTPS-адрес API MLSpace; по умолчанию используется адрес из файла или production.",
+    )
+    setup.add_argument(
+        "--no-verify", action="store_true", help="Сохранить настройки без проверки API; нужны --config-only и --workspace. Клиенты не подключаются."
+    )
+    setup.add_argument("--client", dest="clients", action="append", choices=["claude-code", "codex", "opencode"], help="Подключить этот клиент; повторите флаг для нескольких. По умолчанию клиенты определяются автоматически.")
+    setup.add_argument("--client-path", dest="client_paths", action="append", metavar="CLIENT=PATH", help="Путь к исполняемому файлу клиента, если он отсутствует в PATH: например codex=/usr/local/bin/codex.")
+    setup.add_argument("--config-only", action="store_true", help="Сохранить только ключи и воркспейсы. Для подключения клиентов позже повторите setup --force --client CLIENT.")
+    setup.add_argument("--non-interactive", action="store_true", help="Без вопросов в терминале: укажите ID через --workspace и источник ключей либо используйте сохранённые ключи.")
+    setup.add_argument("--from-env", action="store_true", help="Прочитать ключи из переменных MLSPACE_CLIENT_ID / MLSPACE_CLIENT_SECRET.")
+    setup.add_argument("--credentials-file", type=Path, help="Прочитать ключи из существующего dotenv-файла без вывода их значений.")
+    setup.add_argument("--replace-credentials", action="store_true", help="Запросить новые ключи вместо сохранённых; для существующего файла также нужен --force.")
+    setup.add_argument("--workspace", dest="workspace_ids", action="append", help="Выбрать воркспейс по точному ID; повторите флаг для нескольких.")
+    setup.add_argument("--ca-file", type=Path, help="Файл доверенного CA в формате PEM от администратора. Копия сохраняется для следующих запусков MCP; проверка TLS включена.")
+    setup.add_argument("--list-workspaces", action="store_true", help="Вывести страницу доступных воркспейсов в JSON без сохранения и установки.")
+    setup.add_argument("--search", default="", help="Фильтровать JSON воркспейсов по названию, проекту или ID (с --list-workspaces).")
+    setup.add_argument("--offset", type=int, default=0, help="Пропустить это число результатов JSON; не меньше 0, по умолчанию 0.")
+    setup.add_argument("--limit", type=int, default=20, help="Число воркспейсов на странице JSON: 1–100, по умолчанию 20.")
+    args = parser.parse_args(argv)
+
+    if args.command == "setup":
+        from .init_cli import run_init
+
+        return run_init(
+            args.path,
+            force=args.force,
+            verify=not args.no_verify,
+            base_url=args.base_url,
+            config_only=args.config_only, non_interactive=args.non_interactive,
+            from_env=args.from_env, credentials_file=args.credentials_file,
+            workspace_ids=args.workspace_ids, clients=args.clients, client_paths=args.client_paths,
+            ca_file=args.ca_file, replace_credentials=args.replace_credentials,
+            list_workspaces=args.list_workspaces, search=args.search, offset=args.offset, limit=args.limit,
+        )
+
+    _configure_logging()
+    settings = load_settings()
+    if args.transport:
+        settings.transport = args.transport
+
+    if args.list_tools:
+        mcp = build_server(settings)
+        tools = mcp._tool_manager.list_tools()
+        mode = "read-only" if settings.readonly else "read-write"
+        print(f"mlspace-plugin {__version__} — {len(tools)} инструментов ({mode}):")
+        for tool in sorted(tools, key=lambda t: t.name):
+            print(f"  {tool.name}")
+        return 0
+
+    settings.validate_bind()
+    settings.require_credentials()
+    mcp = build_server(settings)
+
+    if settings.transport == "stdio":
+        mcp.run(transport="stdio")
+    else:
+        print(
+            f"mlspace-plugin: сервер streamable-HTTP запущен на "
+            f"http://{settings.host}:{settings.port}/mcp",
+            file=sys.stderr,
+        )
+        mcp.run(transport="streamable-http")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())