RomM MCP

romm-mcp es un servidor de Model Context Protocol (MCP) mantenido por la comunidad para la gestión acotada de RomM a través de la API autenticada de RomM. No está afiliado, respaldado ni mantenido por el proyecto RomM.

El servidor es intencionalmente más limitado que la API completa de RomM: proporciona herramientas explícitas de lectura/escritura tipadas para tareas comunes de gestión de bibliotecas sin un paso HTTP genérico ni una vía de escape administrativa amplia.

Estado y compatibilidad

• Línea de lanzamiento inicial: 0.1.x.

• Probado contra los contratos de API de RomM 5.1.0.

• Requiere Python 3.12 o superior.

• Utiliza tokens de API de cliente de RomM (rmm_...) como credenciales de portador.

Las versiones posteriores de RomM pueden seguir siendo compatibles, pero no se afirma que estén probadas hasta que se verifiquen.

Límite de capacidades

Incluido en v0.1:

• Descubrimiento de plataformas y ROM.

• Actualizaciones acotadas de metadatos de texto de ROM (name, name_sort_key, summary).

• Propiedades personales de estado/calificación/finalización de ROM.

• Notas de ROM.

• Colecciones regulares y membresía de colecciones.

• Colecciones inteligentes con un esquema de filtro explícito de RomM 5.1.

• Lecturas de visibilidad de usuario y sesiones de juego.

Excluido intencionalmente de v0.1:

• Paso HTTP/API genérico.

• Eliminación de ROM o archivos ROM.

• Cargas o reemplazo de ROM/archivos.

• Obtención remota de carátulas/manuales y mutación de activos.

• Escaneos de biblioteca, tareas en segundo plano y actualización masiva de metadatos.

• Mutación de configuración de plataforma/sistema.

• Administración de tokens de cliente.

• Mutación de usuarios, grupos de permisos o autorización.

• Mutación de dispositivos/sincronización.

Eliminar ROMs de una colección solo cambia la membresía de la colección. Eliminar una colección regular requiere confirm=true; RomM también elimina el directorio de arte/recursos gestionado por esa colección, pero este MCP nunca elimina archivos ROM.

Consulta docs/tools.md para la superficie completa de 26 herramientas y los efectos secundarios por herramienta.

Instalación

Los lanzamientos se distribuyen como ruedas inmutables de GitHub Release. romm-mcp no está publicado actualmente en PyPI.

Para 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

Cada lanzamiento incluye SHA256SUMS. Para uso fijado o de producción, verifica el digest de la rueda antes del despliegue y, donde se admita, fija la URL del artefacto con su hash SHA-256.

Configuración

El servidor requiere un token de API de cliente de RomM dedicado almacenado en un archivo. Los valores de token nunca se aceptan como argumentos de herramientas MCP.

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

ROMM_BASE_URL debe ser una URL absoluta http:// o https://. ROMM_TIMEOUT_SECONDS debe ser mayor que 0 y como máximo 300 segundos.

Para el conjunto de herramientas completo de v0.1, el conjunto de ámbitos de RomM previsto es:

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

Los ámbitos users.write, ejecución de tareas, escritura de plataforma, escritura de dispositivo y escritura de activos no son requeridos por v0.1.

Ejemplo de cliente 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"
  }
}

Modelo de seguridad

El token de API de cliente de RomM y sus ámbitos ascendentes son el límite de autorización estricto. Usa un token dedicado y otorga solo los ámbitos requeridos por las herramientas que pretendes exponer.

La capa MCP añade un segundo límite:

• Las credenciales se respaldan en archivos y se omiten de los esquemas de herramientas.

• No hay herramienta de solicitud genérica.

• No se aceptan URLs remotas de carátulas/manuales, evitando el comportamiento de obtención/escritura de activos en el servidor a través de este MCP.

• La eliminación de notas, colecciones regulares y colecciones inteligentes requiere confirm=true explícito.

• La eliminación de ROM/archivos, cargas, ejecución de tareas y administración de autorización están ausentes del registro de herramientas.

Consulta SECURITY.md para obtener orientación sobre informes de vulnerabilidades y manejo de credenciales.

Desarrollo

uv.lock es la resolución exacta canónica de dependencias utilizada por CI y la verificación de lanzamientos, mientras que el paquete publicado mantiene rangos de dependencias compatibles en pyproject.toml.

bash ./scripts/verify.sh

El script de verificación crea un entorno aislado de Python 3.12, sincroniza la resolución congelada de uv.lock, compila el paquete, ejecuta la suite de pruebas y construye la rueda de lanzamiento.

Upstream y licencia

Este repositorio es una integración comunitaria independiente para RomM. RomM es un proyecto upstream separado regido por su propia licencia y políticas de proyecto.

romm-mcp está licenciado bajo la Licencia MIT.