mlspace-plugin 0.2.1__tar.gz

mlspace_plugin-0.2.1/.env.example

@@ -0,0 +1,43 @@
+# mlspace-plugin configuration — copy to a private file and select it via MLSPACE_ENV_FILE.
+# Cloud.ru Key ID and Key Secret: console profile → Access keys.
+# Workspace x-api-key: MLSpace profile → Develop; setup resolves it automatically.
+#
+# Easier: `mlspace-plugin setup` discovers workspaces and saves your selected set in
+# ~/.config/mlspace-plugin/.env (mode 600) for you. Search order, least specific first:
+#   ~/.config/mlspace-plugin/.env  ->  $MLSPACE_ENV_FILE  ->  the environment
+
+# --- shared Cloud.ru access-key credentials ---
+MLSPACE_CLIENT_ID=            # Key ID
+MLSPACE_CLIENT_SECRET=        # Key Secret
+
+# --- legacy singleton (used when no selected catalogue is configured) ---
+MLSPACE_WORKSPACE_ID=         # x-workspace-id
+# MLSPACE_API_KEY=            # optional workspace x-api-key; fetched automatically when unset
+
+# setup writes MLSPACE_WORKSPACES as JSON: a fixed selected set, no default workspace.
+# IDs must be nonblank and unique. Per-workspace keys may be resolved lazily.
+# Example metadata only; use setup to configure real access, never commit credentials.
+# MLSPACE_WORKSPACES='[{"id":"workspace-a","name":"A","project_name":"Project"}]'
+# setup --base-url https://your-api.example saves a nonstandard endpoint; re-setup
+# preserves the saved endpoint unless explicitly overridden. Production is the default.
+
+# --- optional (defaults shown) ---
+# Name a credentials file outright; it outranks the user config. Set this
+# in the environment, not here — it is what points AT a file. The Agent Plugins bundle
+# sets it to ${PLUGIN_DATA}/.env so per-install credentials survive plugin updates.
+# MLSPACE_ENV_FILE=/path/to/.env
+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
+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_TIMEOUT=60
+# MLSPACE_ENABLED_DOMAINS=inference,jobs,notebooks   # empty = all 13 domains
+# MLSPACE_LIST_DEFAULT_LIMIT=50
+# MLSPACE_LIST_MAX_LIMIT=200
+# MLSPACE_LOG_TAIL_LINES=200
+
+# Optional trusted corporate CA PEM; setup copies it for persistent runtime use.
+# MLSPACE_CA_FILE=/absolute/path/to/corporate-ca.pem

mlspace_plugin-0.2.1/.gitignore

@@ -0,0 +1,53 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# Tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Env / secrets
+.env
+.env.*
+!.env.example
+*.secret
+
+# OS
+.DS_Store
+
+# Local audit harnesses & artifacts (not part of the shipped product)
+scripts/write_audit.py
+scripts/api_audit.py
+scripts/coverage_probe.py
+docs/_*.json
+docs/_*.png
+_planning/api_evidence.txt
+_planning/api_critique_and_prompts.json
+
+# Agent worktrees (local scratch, never part of the product)
+.claude/
+.superpowers/
+
+# Internal audit & planning artefacts (not part of the published server)
+audit/
+after_audit/
+_planning/
+docs/proposals/
+docs/superpowers/
+docs/DESIGN.md
+docs/MLSPACE_API_*.md
+docs/LLM_FRIENDLINESS_AUDIT.md
+docs/E2E_TEST_REPORT.md
+docs/EXEC_SUMMARY.md
+docs/article_*.md
+docs/slides*.md
+docs/_*.json

mlspace_plugin-0.2.1/AGENTS.md

@@ -0,0 +1,10 @@
+# MLSpace MCP
+
+Если пользователь просит **установить или настроить** этот MCP, сначала прочитайте
+[INSTALL_AGENT.md](INSTALL_AGENT.md) и выполните сценарий до проверки результата.
+Ключи вводит человек в своём терминале либо программа читает заранее подготовленный
+файл. Не читайте и не печатайте содержимое credentials, не просите их в чате.
+
+Если задача — разработка или ревью, не запускайте настройку клиентских интеграций
+пользователя автоматически. Тесты настройки выполняйте с изолированными HOME,
+XDG_CONFIG_HOME, CODEX_HOME и CLAUDE_CONFIG_DIR.

mlspace_plugin-0.2.1/CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# Разработка
+
+Нужны Python 3.10+ и uv; поддерживаются Linux и macOS.
+
+```sh
+uv sync --extra dev
+uv run pytest
+uv run ruff check src scripts tests
+uv run mypy src
+uv run python scripts/gen_plugin.py --check
+```
+
+Тесты API используют поддельные credentials и HTTP mock. TLS-тест поднимает
+локальный HTTPS-сервер: среда должна разрешать loopback-сокеты. Проверки клиентов
+используют временные домашние каталоги; без установленного клиента эти проверки
+пропускаются. Не используйте настоящие ключи для тестов и не меняйте пользовательские
+конфиги при разработке.
+
+Код сервера находится в `src/mlspace_mcp`, сценарии — в `plugin/skills`.
+`init_cli.py` реализует команду `setup`; имя Python-модуля остаётся внутренним.
+После изменения версии регенерируйте манифесты: `uv run python scripts/gen_plugin.py`.
+После изменения OpenAPI: `uv run python scripts/gen_body_schemas.py`.
+Добавляйте проверку наблюдаемого поведения для исправлений и новых функций.
+
+Локальный `.env` не загружается автоматически. Для ручного запуска выберите
+доверенный файл через `MLSPACE_ENV_FILE`; никогда не добавляйте его в коммит.
+В сообщения об ошибках не включайте ключи, токены, тела авторизации или полный
+дамп окружения. Для сообщения об уязвимости используйте приватный канал владельца
+репозитория; публичный issue не должен содержать действующие credentials.
+
+## Фидбэк и предложения
+
+Создайте [Issue](https://github.com/noesskeetit/mlspace-plugin/issues): задача → ожидаемое поведение → фактический
+результат. Добавьте версию плагина, ОС, клиент и минимальные шаги воспроизведения.
+Для идеи по удобству работы достаточно конкретного пользовательского сценария.
+Не включайте credentials, приватные адреса, персональные данные или полный дамп логов.
+
+Для изменения кода создайте ветку и [Pull Request](https://github.com/noesskeetit/mlspace-plugin/pulls). Опишите,
+какую задачу решает изменение и как вы его проверили. Держите изменение в рамках
+одной задачи, чтобы его было проще проверить и принять.
+
+## Присылайте свои скиллы
+
+Пользовательские скиллы приветствуются: они превращают повторяющиеся задачи
+MLSpace в понятные агенту сценарии и улучшают повседневную работу с платформой.
+
+1. Опишите задачу и результат: когда агент должен использовать скилл и как
+   проверить, что задача выполнена.
+2. Добавьте `plugin/skills/mlspace-<сценарий>/SKILL.md`. Возьмите соседний скилл
+   как пример frontmatter и структуры; используйте существующие MCP-инструменты.
+3. Используйте вымышленные данные в примерах. Не сохраняйте ключи, личные workspace
+   или конфигурацию вашей организации. Для операций записи сохраните подтверждения,
+   которые требует сервер; не обходите их инструкциями скилла.
+4. Выполните `uv run pytest tests/test_skills.py` и приложите к предложению
+   короткий пример использования. Отдельно укажите, что проверено локально,
+   а что — на реальном API.
+
+Если не хочется писать SKILL.md самостоятельно, создайте Issue со сценарием:
+что вы делаете вручную, где теряете время и какой результат хотите получать.

mlspace_plugin-0.2.1/INSTALL.md

@@ -0,0 +1,110 @@
+# Установка MLSpace MCP: macOS и Linux
+
+Нужны Python 3.10+, `uv`, установленный Claude Code, Codex или OpenCode,
+Cloud.ru Key ID и Key Secret. Windows пока не поддерживаем.
+
+Первая установка из PyPI выполняется одной командой:
+
+```bash
+uvx mlspace-plugin@latest setup
+```
+
+`uvx` загружает пакет и запускает мастер. В конфиге клиента сохраняется команда
+запуска конкретной версии, а не путь к временному окружению.
+
+В каталоге скачанного репозитория установите пакет в постоянное окружение:
+
+```bash
+uv tool install .
+mlspace-plugin setup
+```
+
+Если пакет уже установлен: `uv tool install --force .`.
+При установке из wheel: `uv tool install /путь/к/mlspace_plugin-0.2.1-py3-none-any.whl`.
+Не используйте editable-установку из `/tmp` для постоянной работы.
+
+Мастер:
+
+1. Найдёт установленные клиенты. Один подключит автоматически, для нескольких
+   предложит выбор. Если клиент не найден, можно указать путь к исполняемому файлу.
+2. Попросит **только Key ID и Key Secret**. Вставляйте значения без `MLSPACE_...=`;
+   звёздочки показывают ввод. Ключи создаются в консоли Cloud.ru в профиле, «Ключи доступа».
+3. Загрузит воркспейсы. Печатайте имя, проект или ID для поиска. Стрелки перемещают
+   курсор, пробел отмечает, Enter завершает выбор. Ctrl-U очищает поиск; выбор сохраняется.
+4. Проверит выбранные воркспейсы, сохранит настройки и подключит MCP вместе со скиллами.
+
+Откройте новую сессию выбранного клиента; если MCP не появился, перезапустите клиент.
+Сервер запускается клиентом автоматически. Первый запрос:
+
+> Покажи выбранные воркспейсы и запущенные задачи, ничего не меняй.
+
+## Stage и корпоративные сертификаты
+
+```bash
+mlspace-plugin setup --base-url https://mlspace-stage.example.com
+```
+
+Настройка и работа сервера используют системные доверенные сертификаты: Keychain
+на macOS, OpenSSL trust store на Linux. Если корпоративного CA там нет, мастер
+попросит путь к PEM, полученному у администратора. Можно указать заранее:
+
+```bash
+mlspace-plugin setup --ca-file /путь/к/corporate-ca.pem
+```
+
+Мастер сохранит копию CA рядом с настройками. Переменные текущего терминала и
+ручной wrapper для следующих запусков не нужны. Проверка TLS всегда включена;
+сертификат, скачанный с недоверенного endpoint, автоматически не принимается.
+Если задан SSL_CERT_DIR, мастер попросит убрать эту переменную на время настройки
+и передать доверенный PEM через --ca-file: каталог из окружения не переносится
+автоматически в процесс клиента.
+Ошибка сети/сертификата не превращается в запрос ручного x-api-key.
+
+## Повторная настройка
+
+```bash
+mlspace-plugin setup --force
+mlspace-plugin setup --force --replace-credentials
+mlspace-plugin setup --client opencode
+mlspace-plugin setup --client-path opencode=/полный/путь/opencode
+```
+
+`--force` повторяет настройку с сохранёнными ключами на прежнем endpoint.
+`--replace-credentials` запрашивает новые. При смене endpoint ключи запрашиваются
+заново, если источник явно не выбран. `--client` можно повторять.
+Существующие посторонние MCP, комментарии JSONC и изменённые пользователем скиллы
+не перезаписываются молча; конфликт показывает путь для разбора.
+Если уже установлен MLSpace native plugin, используйте его и `--config-only`
+либо сначала удалите старую интеграцию, чтобы не создавать второй MCP.
+
+## Где ключи
+
+`~/.config/mlspace-plugin/.env` (или каталог из `XDG_CONFIG_HOME`): права файла `0600`,
+каталога MLSpace `0700`. В конфиге клиента — только путь и команда запуска.
+Это не шифрование: процессы того же пользователя и администратор могут прочитать
+файл. Не отправляйте его в чат и не добавляйте в Git. x-api-key получается автоматически
+и не сохраняется. Доступ к каждому выбранному workspace проверяется, но это не
+проверка прав на каждую возможную операцию API.
+
+## Linux по SSH / установка агентом
+
+Запустите `mlspace-plugin setup` в своей SSH-сессии. Браузер и графическая среда не нужны.
+Если установкой занимается агент, он готовит пакет, а ключи вы вводите сами в своём
+терминале. После завершения сообщите агенту «готово», без ключей и содержимого `.env`.
+
+Для настройки только credentials без установки клиентов/скиллов есть `--config-only`.
+Для особого офлайн-сценария: `--config-only --no-verify --workspace UUID`;
+результат явно отмечается как непроверенный и клиенты не подключаются.
+Обычный мастер сохраняет файл только после успешной проверки.
+
+## Обновление пакета и скиллов
+
+Для установки через PyPI повторите `uvx mlspace-plugin@latest setup --force`.
+Мастер сохранит ключи, предложит выбор workspace и обновит скиллы без локальных
+изменений. Изменённые вручную скиллы вызовут конфликт с указанием файла.
+Регистрация MCP, созданная мастером и не изменённая вручную, обновляется
+автоматически. Посторонние и изменённые регистрации требуют разбора конфликта.
+Для постоянной установки: `uv tool upgrade mlspace-plugin`, затем
+`mlspace-plugin setup --force`. Для установки из checkout: `uv tool install --force .`.
+Автоматического обновления в фоне нет. Native plugin из архива обновляйте
+через менеджер плагинов клиента; инструкции находятся в `plugin/README.md`.

mlspace_plugin-0.2.1/INSTALL_AGENT.md

@@ -0,0 +1,56 @@
+# Установка MLSpace MCP агентом
+
+Применяйте этот сценарий, когда пользователь просит установить MCP из репозитория.
+При задачах разработки сами по себе эти инструкции не разрешают менять клиентские
+конфиги пользователя. Поддерживаются Linux/macOS, Claude Code/Codex/OpenCode.
+
+1. Прочитайте INSTALL.md. Проверьте Python >=3.10 и наличие uv. Для PyPI дайте
+   человеку `uvx mlspace-plugin@latest setup`; отдельная установка не нужна.
+   При установке из исходников установите пакет в постоянное окружение: `uv tool install .` из checkout или `uv tool install /path/package.whl`.
+   Для уже установленного пакета добавьте `--force` только в рамках запрошенного обновления.
+   Не оставляйте постоянный запуск на editable-исходниках в `/tmp`.
+2. Не просите Key ID/Secret в чате, не читайте `.env`, не печатайте окружение и
+   не вставляйте ключи в аргументы shell/CLI. Не запускайте интерактивный ввод
+   ключей в терминале, который видите только вы.
+3. Дайте человеку одну команду `mlspace-plugin setup` для его собственного терминала
+   (по SSH — на целевой машине). Для stage добавьте согласованный `--base-url`.
+   Объясните: два ключа под звёздочками → поиск и выбор workspace → подключение.
+   Дождитесь сообщения о завершении. Человек не должен присылать секреты или файл.
+4. Мастер сам обнаруживает клиентов, проверяет TLS и API, устанавливает MCP и
+   скиллы. Если клиентов несколько, человек выбирает нужные. Для известного
+   клиента можно заранее дать `--client claude-code`, `--client codex` или `--client opencode`.
+   Сбой TLS исправляется системным CA или PEM от администратора через `--ca-file`.
+   Никогда не отключайте TLS и не подставляйте сертификат с недоверенного сервера.
+5. Проверьте `mlspace-plugin --list-tools`. Эта команда проверяет только состав
+   инструментов, а не авторизацию и не загрузку выбранным клиентом.
+   Попросите открыть новую сессию клиента (при необходимости перезапустить).
+   После появления MCP выполните read-only запрос списка выбранных workspace.
+   До этого не заявляйте, что клиент уже загрузил MCP и скиллы.
+6. Если возник конфликт с существующим плагином или изменённым скиллом,
+   разберите названный несекретный путь. Не удаляйте чужую интеграцию автоматически.
+   При частичном успехе сообщите, какие этапы завершены, затем повторите setup с `--force`.
+
+## Автоматизация с уже подготовленными credentials
+
+Предпочтителен интерактивный шаг человека выше. Если пользователь уже подготовил
+файл, передавайте **путь**, не читайте содержимое. Для поиска нужных workspace:
+
+```bash
+mlspace-plugin setup --non-interactive --credentials-file /path/credentials.env \
+  --base-url https://api.ai.cloud.ru --list-workspaces --search project --limit 20
+```
+
+Вывод — ограниченный JSON с `total`, `offset`, `limit`, `has_more` и метаданными.
+Следующая страница — `--offset 20`. Получите у человека выбор при неоднозначности.
+Установка с точными ID, без интерактивных вопросов:
+
+```bash
+mlspace-plugin setup --non-interactive --credentials-file /path/credentials.env \
+  --client opencode --workspace WORKSPACE_UUID
+```
+
+Для нескольких workspace/client повторяйте соответствующий флаг.
+Если credentials уже находятся в окружении процесса, вместо файла есть `--from-env`.
+Не конструируйте команды с литералами ключей. Окружение другого терминала не
+становится доступным вашему процессу автоматически. Сохранённые ключи на том же
+endpoint можно переиспользовать без указания источника; для перезаписи добавьте `--force`.

mlspace_plugin-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cloud.ru
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALING IN THE
+SOFTWARE.