RomM MCP

romm-mcp は、RomM の認証付き API を通じて RomM を制限付きで管理するための、コミュニティ保守の Model Context Protocol (MCP) サーバーです。これは RomM プロジェクトとは提携しておらず、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 ツールの API サーフェスとツールごとの副作用については、docs/tools.md を参照してください。

インストール

リリースは不変の GitHub Release wheel として配布されます。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 ハッシュ付きで固定してください。

設定

サーバーは、ファイルに保存された専用の 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、タスク実行、platform-write、device-write、asset-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 レイヤーは 2 つ目の境界を追加します:

• 資格情報はファイルに格納され、ツールスキーマから除外されます。

• 汎用リクエストツールはありません。

• リモートのカバー/マニュアル 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 License の下でライセンスされています。