RomM MCP

romm-mcp — это поддерживаемый сообществом сервер Model Context Protocol (MCP) для ограниченного управления RomM через аутентифицированный API RomM. Он не связан с проектом RomM, не одобрен им и не поддерживается им.

Сервер намеренно уже, чем полный API RomM: он предоставляет явные типизированные инструменты чтения/записи для типовых задач управления библиотекой, без универсального HTTP-проксирования или широкой административной лазейки.

Статус и совместимость

• Начальная линия выпуска: 0.1.x.

• Проверено на контрактах API RomM 5.1.0.

• Требуется Python 3.12 или новее.

• Использует клиентские API-токены RomM (rmm_...) в качестве bearer-учётных данных.

Более поздние версии RomM могут оставаться совместимыми, но они не заявляются как протестированные, пока это не подтверждено.

Граница возможностей

Включено в v0.1:

• Обнаружение платформ и ROM.

• Ограниченные обновления текстовых метаданных ROM (name, name_sort_key, summary).

• Личные свойства ROM: статус, оценка, завершённость.

• Заметки ROM.

• Обычные коллекции и членство в коллекциях.

• Умные коллекции с явной схемой фильтров RomM 5.1.

• Чтение видимости пользователей и игровых сессий.

Намеренно исключено из v0.1:

• Универсальное API/HTTP-проксирование.

• Удаление ROM или ROM-файлов.

• Загрузка или замена ROM/файлов.

• Удалённое получение обложек/руководств и изменение ресурсов.

• Сканирование библиотеки, фоновые задачи и массовое обновление метаданных.

• Изменение конфигурации платформ/системы.

• Администрирование клиентских токенов.

• Изменение пользователей, групп разрешений или авторизации.

• Изменение устройств/синхронизации.

Удаление ROM из коллекции изменяет только членство в коллекции. Для удаления обычной коллекции требуется confirm=true; RomM также удаляет собственную управляемую директорию ресурсов/изображений этой коллекции, но ROM-файлы этим MCP никогда не удаляются.

Полный набор из 26 инструментов и побочные эффекты каждого инструмента см. в docs/tools.md.

Установка

Релизы распространяются в виде неизменяемых wheel-файлов GitHub Release. romm-mcp в настоящее время не опубликован на PyPI.

Для v0.1.0:

uvx --python 3.12 \
  --from https://github.com/X1pheR/romm-mcp/releases/download/v0.1.0/romm_mcp-0.1.0-py3-none-any.whl \
  romm-mcp

Каждый релиз включает SHA256SUMS. Для закреплённых или производственных версий проверяйте контрольную сумму wheel перед развёртыванием и, где поддерживается, закрепляйте URL артефакта с его SHA-256 хешем.

Конфигурация

Сервер требует выделенный клиентский API-токен RomM, хранящийся в файле. Значения токенов никогда не принимаются в качестве аргументов инструментов MCP.

ROMM_BASE_URL=https://romm.example.com
ROMM_API_TOKEN_FILE=/path/to/romm-api-token
ROMM_TIMEOUT_SECONDS=15

ROMM_BASE_URL должен быть абсолютным URL http:// или https://. ROMM_TIMEOUT_SECONDS должен быть больше 0 и не более 300 секунд.

Для полного набора инструментов v0.1 целевой набор областей RomM следующий:

me.read
platforms.read
roms.read
roms.write
roms.user.read
roms.user.write
collections.read
collections.write
users.read

Области users.write, выполнение задач, запись платформ, запись устройств и запись ресурсов не требуются для v0.1.

Пример MCP-клиента

{
  "command": "uvx",
  "args": [
    "--python",
    "3.12",
    "--from",
    "https://github.com/X1pheR/romm-mcp/releases/download/v0.1.0/romm_mcp-0.1.0-py3-none-any.whl",
    "romm-mcp"
  ],
  "env": {
    "ROMM_BASE_URL": "https://romm.example.com",
    "ROMM_API_TOKEN_FILE": "/path/to/romm-api-token",
    "ROMM_TIMEOUT_SECONDS": "15"
  }
}

Модель безопасности

Клиентский API-токен RomM и его исходные области являются жёсткой границей авторизации. Используйте выделенный токен и предоставляйте только те области, которые требуются инструментам, которые вы собираетесь открыть.

Слой MCP добавляет вторую границу:

• Учётные данные хранятся в файлах и исключены из схем инструментов.

• Нет универсального инструмента запросов.

• Удалённые URL обложек/руководств не принимаются, что исключает поведение получения/записи ресурсов на стороне сервера через этот MCP.

• Заметки, а также удаление обычных и умных коллекций требуют явного confirm=true.

• Удаление ROM/файлов, загрузка, выполнение задач и администрирование авторизации отсутствуют в реестре инструментов.

Рекомендации по сообщению об уязвимостях и обращению с учётными данными см. в SECURITY.md.

Разработка

uv.lock — это каноническое точное разрешение зависимостей, используемое CI и проверкой релизов, тогда как опубликованный пакет сохраняет совместимые диапазоны зависимостей в pyproject.toml.

bash ./scripts/verify.sh

Скрипт проверки создаёт изолированное окружение Python 3.12, синхронизирует зафиксированное разрешение uv.lock, компилирует пакет, запускает набор тестов и собирает релизный wheel.

Вышестоящий проект и лицензия

Этот репозиторий — независимая интеграция сообщества для RomM. RomM — отдельный вышестоящий проект, регулируемый собственной лицензией и политиками проекта.

romm-mcp распространяется под лицензией MIT.