ROM Manager

CLI or API | MCP

Version: 3.2.1

Documentation — Installation, deployment, and usage across the API, CLI, and official documentation.

⚠️ Back up the operator's ROMs before working with this tool. Conversion and the --delete / clean_origin_files options are destructive to source files.

Table of Contents

• Overview
• Key Features
• Architecture
• Usage (CLI or API)
• MCP
• Environment Variables
• Security & Governance
• External Binary Dependencies
• Installation
• Documentation
• Contributing
• License

Overview

ROM Manager is a production-grade ROM converter/organizer with an integrated archives, auto-renames ROMs via a known game-code registry, converts ISO/WBFS images to CHD (chdman) or RVZ (dolphin-tool), generates missing .cue sheets, and cleans up source files — in parallel.

It also speaks to RomM (CONCEPT:RO-OS.state.api-base-one-mixin) — a self-hosted ROM library server — through a full REST client, so one rom-manager tool manages both the files on disk (local conversion) and the web library (RomM).

The local conversion pipeline needs no service URL or credentials; the RomM client is configured via ROMM_* environment variables.

Key Features

• Real conversion pipeline: parallel extract → rename → convert (CHD/RVZ) → cleanup.
• Full RomM REST client (CONCEPT:RO-OS.state.api-base-one-mixin): complete coverage of the RomM API (roms, platforms, collections, saves, states, firmware, users, tasks, search, config, feeds, devices, …) with Basic/OAuth2 auth — one unified CLI and one action-routed MCP tool per resource group.
• Consolidated Action-Routed MCP Tools: togglable domains (conversion, game-codes, romm-*) minimize token overhead and IDE tool bloat.
• Native Telemetry & Tracing: OpenTelemetry exports by default.
• Lazy native deps: archive backends are optional extras, imported only when used.

Architecture

ROM Manager keeps a single, well-factored pipeline behind three entry surfaces responsibility layers and shells out to external conversion binaries:

Usage (CLI or API)

This package wraps a local ROM conversion pipeline (rom_manager.rom_manager.RomManager). Use it via the CLI or the rom_manager.api_client.Api facade.

rom-manager --directory "/games/PSX/" --iso chd --verbose

Detailed API usage is in docs/usage.md.

RomM web library (CONCEPT:RO-OS.state.api-base-one-mixin)

The same rom-manager command manages a running RomM server. Set ROMM_URL and credentials (ROMM_USERNAME/ROMM_PASSWORD or ROMM_TOKEN), then use rom-manager <resource> <action> [positionals] [--flag value …]:

rom-manager roms list --platform_ids 7 --limit 50   # list/search ROMs
rom-manager roms get 123                             # positional id
rom-manager platforms list
rom-manager saves add --rom_id 5 --file_path ./game.srm
rom-manager tasks run scan                           # trigger a library scan
rom-manager stats                                    # server statistics

Resources map 1:1 to RommApi methods. The on-disk converter is reachable as before (bare flags) or via the explicit rom-manager convert … alias. From Python, use rom_manager.get_romm_client() → RommApi.

MCP

This server use dynamic Action-Routed tools to optimize token overhead and maximize IDE compatibility.

Available MCP Tools

The table below is auto-generated from the MCP server — do not edit by hand.

Condensed action-routed tools (default — MCP_TOOL_MODE=condensed)

Verbose 1:1 API-mapped tools (MCP_TOOL_MODE=verbose or both)

16 action-routed tool(s) (default) · 8 verbose 1:1 tool(s). Each is enabled unless its <DOMAIN>TOOL toggle is set false; MCP_TOOL_MODE selects the surface (condensed default · verbose 1:1 · both). Auto-generated — do not edit.

Dynamic Tool Selection

Each domain is gated by an environment toggle (default True). Set a toggle to False to omit that tool from the registered surface.

Running the MCP server

# stdio (default)
rom-manager-mcp

# Streamable HTTP
rom-manager-mcp --transport streamable-http --host 0.0.0.0 --port 8000

Install the connector-focused [mcp] extra. Examples use rom-manager[mcp] to add FastMCP / FastAPI through agent-connector-sdk; the required Agent Connector SDK core enables model orchestration.

stdio client config

{
  "mcpServers": {
    "rom-manager": {
      "command": "uvx",
      "args": ["--from", "rom-manager[mcp]", "rom-manager-mcp"],
      "env": { "ROM_DIRECTORY": "/games", "CONVERSIONTOOL": "True", "GAME_CODESTOOL": "True" }
    }
  }
}

Docker

docker run --rm -it -v /games:/games -e ROM_DIRECTORY=/games \
  -p 8000:8000 -e TRANSPORT=streamable-http example/rom-manager:mcp

The :mcp tag is the MCP-serving image (built from docker/Dockerfile --target mcp, installing rom-manager[mcp]). The default when the operator run rom-manager-agent (the agent), not just the MCP server. See Container images.

Additional Deployment Options

rom-manager can run as a local stdio process or container, or behind a remote network boundary. The Deployment guide carries the detailed transport contract.

• Local container — launch a reviewed immutable image as a least-privilege stdio child with no listener or published port.
• Remote URL — connect through an operator-supplied authenticated HTTPS ingress. Keep its URL, outbound identity references, trust profile, and exact MCP_ALLOWED_HOSTS in AgentConfig.

Agent

rom_manager/agent_data/IDENTITY.md.

Environment Variables

Package environment variables

Inherited agent-connector-sdk variables (apply to every connector)

32 package + 16 inherited variable(s). Auto-generated from .env.example + the shared agent-connector-sdk set — do not edit.

All settings are optional — ROM Manager runs with sensible defaults and requires no credentials. Copy .env.example to .env to override.

Application Variables

CPU count and "delete originals" are exposed as CLI flags (--cpu-count / --delete) and MCP action params (cpu_count / clean_origin_files) rather than environment variables.

RomM Variables (CONCEPT:RO-OS.state.api-base-one-mixin)

Required only when using RomM (roms, platforms, … commands / romm_* tools).

MCP / Framework Variables (agent-connector-sdk)

Terminal Variables

These are set automatically by the server to keep stdio transport clean; the operator do not normally set them the operator.

Security & Governance

• No credentials: ROM Manager is a local tool with no service URL/token.
• Eunomia policies & OpenTelemetry: inherited from the agent-connector-sdk middleware (see .env.example).
• Destructive-op safety: the agent recommends backing up ROMs before clean_origin_files/delete operations.

External Binary Dependencies

Conversion actions shell out to native tools (the Python package installs fine without them):

• chdman (CHD) — apt install mame-tools (Ubuntu) or MAME tools on Windows.
• dolphin-tool (RVZ) — see the Dolphin emulator docs.
• 7z / archive backends (extraction) — apt install p7zip-full; pair with the rom-manager[native] extra (patool).

Installation

Pick the extra that matches what the operator want to run:

pip install rom-manager            # core CLI + Api
pip install "rom-manager[mcp]"     # + MCP server
pip install "rom-manager[native]"  # + patool (archive extraction)
pip install "rom-manager[all]"     # everything

Container images (:mcp)

One multi-stage docker/Dockerfile builds the MCP-only image (--target mcp):

docker build --target mcp   -t example/rom-manager:mcp    docker/   # connector-focused MCP server

agent (immutable agent digest) with a co-located :mcp sidecar.

Knowledge-graph database (epistemic-graph)

Agent Connector SDK core dependency (epistemic-graph[full]). The [mcp] extra keeps deployments can use the bundled engine. For production or shared state, run epistemic-graph as a dedicated database service and configure the runtime to use it. Deployment recipes (single-node + Raft HA), connection configuration, and architecture diagrams are documented in the epistemic-graph deployment guide.

Deployment (agent_server.py)

Container deployment (compose):

The MCP server (rom-manager-mcp) deploys the same way; see docs/deployment.md for the full compose/Swarm recipes.

Documentation

• Installation
• Deployment
• Usage (API / CLI / MCP)
• Overview
• Concepts (CONCEPT:ROM-*)

Contributing

Contributions are welcome. Run pre-commit run --all-files before opening a PR. Preserve the real conversion pipeline — wrap RomManager, do not break it.

License

MIT © Knuckles-Team

Deploy with agent-connector-sdk-deployment

Provision this package with the consolidated agent-connector-sdk-deployment workflow. It selects an installed-package, editable-source, or immutable-container path; records only runtime secret and TLS-profile references in AgentConfig; and runs doctor, registration, policy, observability, and rollback gates. Ask your agent to "deploy rom-manager with agent-connector-sdk-deployment".

The repository embeds no deployment profile, credential value, certificate path, or environment-specific endpoint. Supply those at runtime through AgentConfig and the configured secret provider.

Governed capability contract

This package ships a compact canonical skill surface with specialist procedures kept as referenced workflows. The current MCP tools, skill metadata, connector_manifest.yml, ontology, mappings, shapes, fixtures, migrations, tool-schema fingerprints, and certification metadata form one versioned capability contract. Validate them together; do not rely on stale tool names or historical per-task skill wrappers.

Runtime endpoints, credentials, certificate trust, tenant identity, retention, and observability policy are deployment inputs and are never packaged values. See Configuration, trust, and privacy before enabling a network transport, connector ingestion, Arbora delegation, or trace export.