RomM MCP

romm-mcp은 RomM의 인증 API를 통해 RomM을 제한적으로 관리하기 위한 커뮤니티 유지 관리형 Model Context Protocol(MCP) 서버입니다. RomM 프로젝트와 제휴, 보증 또는 유지 관리 관계가 없습니다.

이 서버는 의도적으로 완전한 RomM API보다 범위가 좁습니다. 일반적인 HTTP 패스스루나 광범위한 관리 탈출구 없이, 일반적인 라이브러리 관리 작업을 위한 명시적 타입의 읽기/쓰기 도구를 제공합니다.

상태 및 호환성

• 초기 릴리스 라인: 0.1.x.

• RomM 5.1.0 API 계약에 대해 테스트됨.

• Python 3.12 이상 필요.

• 베어러 자격 증명으로 RomM Client API 토큰(rmm_...) 사용.

이후 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은 해당 컬렉션의 자체 관리 아트워크/리소스 디렉터리도 제거하지만, 이 MCP가 ROM 파일을 삭제하는 일은 없습니다.

전체 26개 도구 목록과 도구별 부작용은 docs/tools.md를 참조하세요.

설치

릴리스는 불변 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가 포함됩니다. 고정 버전 또는 프로덕션 사용의 경우 배포 전에 휠 다이제스트를 검증하고, 지원되는 경우 SHA-256 해시와 함께 아티팩트 URL을 고정하세요.

구성

서버는 파일에 저장된 전용 RomM Client API 토큰이 필요합니다. 토큰 값은 MCP 도구 인수로 절대 허용되지 않습니다.

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

ROMM_BASE_URL은 절대 http:// 또는 https:// URL이어야 합니다. 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"
  }
}

보안 모델

RomM Client API 토큰과 그 업스트림 범위가 하드 인증 경계입니다. 전용 토큰을 사용하고 노출하려는 도구에 필요한 범위만 부여하세요.

MCP 계층은 두 번째 경계를 추가합니다:

• 자격 증명은 파일 기반이며 도구 스키마에서 생략됩니다.

• 일반 요청 도구가 없습니다.

• 원격 커버/매뉴얼 URL이 허용되지 않아 이 MCP를 통한 서버 측 에셋 가져오기/쓰기 동작을 방지합니다.

• 메모, 일반 컬렉션 및 스마트 컬렉션 삭제에는 명시적 confirm=true가 필요합니다.

• ROM/파일 삭제, 업로드, 작업 실행 및 인증 관리는 도구 레지스트리에 없습니다.

취약점 보고 및 자격 증명 처리 지침은 SECURITY.md를 참조하세요.

개발

uv.lock은 CI 및 릴리스 검증에 사용되는 표준 정확한 의존성 해석이며, 게시된 패키지는 pyproject.toml에서 호환 가능한 의존성 범위를 유지합니다.

bash ./scripts/verify.sh

검증 스크립트는 격리된 Python 3.12 환경을 만들고, 고정된 uv.lock 해석을 동기화하고, 패키지를 컴파일하고, 테스트 스위트를 실행하고, 릴리스 휠을 빌드합니다.

업스트림 및 라이선스

이 저장소는 RomM을 위한 독립적인 커뮤니티 통합입니다. RomM은 자체 라이선스와 프로젝트 정책에 따라 관리되는 별도의 업스트림 프로젝트입니다.

romm-mcp는 MIT License에 따라 라이선스가 부여됩니다.