ROM Manager

CLI or API | MCP | Agent

Version: 2.0.1

Documentation — Installation, deployment, and usage across the API, CLI, and MCP interfaces, plus the integrated A2A agent server, are maintained in the official documentation.

⚠️ Back up your 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
• Agent
• Environment Variables
• Security & Governance
• External Binary Dependencies
• Installation
• Deployment (agent_server.py)
• Documentation
• Contributing
• License

Overview

ROM Manager is a production-grade ROM converter/organizer with an integrated Model Context Protocol (MCP) server and Agent-to-Agent (A2A) agent. It extracts 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:ROM-003) — 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:ROM-003): 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.
• Integrated Graph Agent: built-in Pydantic-AI agent (AG-UI / ACP).
• Native Telemetry & Tracing: OpenTelemetry exports out of the box.
• 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 (CLI, MCP server, A2A agent). The orchestrator (RomManager) composes focused responsibility layers and shells out to external conversion binaries:

flowchart LR
    subgraph Entry["Entry Surfaces"]
        CLI["CLI<br/>rom-manager"]
        MCP["MCP Server<br/>rom-manager-mcp<br/>(CONCEPT:ROM-001/002)"]
        AGENT["A2A Agent<br/>rom-manager-agent"]
    end

    CLI --> RM
    MCP --> API["api_client.Api<br/>(facade)"]
    AGENT --> MCP
    API --> RM

    subgraph Pipeline["RomManager orchestrator"]
        RM["RomManager"] --> ARCH["archives.py<br/>extract + cue"]
        RM --> NAME["naming.py<br/>game-code rename"]
        RM --> CONV["conversion.py<br/>command + runner seam"]
    end

    ARCH --> P7Z["7z / patool"]
    CONV --> CHDMAN["chdman (CHD)"]
    CONV --> DOLPHIN["dolphin-tool (RVZ)"]
    NAME --> CODES["game_codes.py<br/>(PSX registry, DATA)"]

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:ROM-003)

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 utilizes 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 slim [mcp] extra. The examples below install rom-manager[mcp] — the MCP-server extra that pulls only the FastMCP / FastAPI tooling (agent-utilities[mcp]). It deliberately excludes the heavy agent runtime (the epistemic-graph engine, pydantic-ai, dspy, llama-index, tree-sitter), so uvx/container installs are dramatically smaller and faster. Use the full [agent] extra only when you need the integrated Pydantic AI agent (see Installation).

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 knucklessg1/rom-manager:mcp

The :mcp tag is the slim MCP-server image (built from docker/Dockerfile --target mcp, installing rom-manager[mcp]). The default :latest tag is the full agent image (--target agent, rom-manager[agent]) which also bundles the Pydantic AI agent and the epistemic-graph engine — use it when you run rom-manager-agent (the agent), not just the MCP server. See Container images.

Additional Deployment Options

rom-manager can also run as a local container (Docker / Podman / uv) or be consumed from a remote deployment. The Deployment guide has full, copy-paste mcp_config.json for all four transports — stdio, streamable-http, local container / uv, and remote URL:

• Local container / uv — launch the server from mcp_config.json via uvx, docker run, or podman run, or point at a local streamable-http container by url.
• Remote URL — connect to a server deployed behind Caddy at http://rom-manager-mcp.arpa/mcp using the "url" key.

Agent

ROM Manager ships a Pydantic-AI agent (rom-manager-agent) that calls the MCP tool surface and exposes an AG-UI web interface. Its identity lives in rom_manager/agent_data/IDENTITY.md.

rom-manager-agent --web

Environment Variables

Package environment variables

Inherited agent-utilities variables (apply to every connector)

31 package + 14 inherited variable(s). Auto-generated from .env.example + the shared agent-utilities 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:ROM-003)

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

MCP / Framework Variables (agent-utilities)

Terminal Variables

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

Security & Governance

• No credentials: ROM Manager is a local tool with no service URL/token.
• Eunomia policies & OpenTelemetry: inherited from the agent-utilities 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 you want to run:

pip install rom-manager            # core CLI + Api
pip install "rom-manager[mcp]"     # + slim MCP server
pip install "rom-manager[agent]"   # + A2A agent (Pydantic AI + epistemic-graph engine)
pip install "rom-manager[native]"  # + patool (archive extraction)
pip install "rom-manager[all]"     # everything

Container images (:mcp vs :agent)

One multi-stage docker/Dockerfile builds two right-sized images, selected by --target:

docker build --target mcp   -t knucklessg1/rom-manager:mcp    docker/   # slim MCP server
docker build --target agent -t knucklessg1/rom-manager:latest docker/   # full agent

docker/mcp.compose.yml runs the slim :mcp server; docker/agent.compose.yml runs the agent (:latest) with a co-located :mcp sidecar.

Knowledge-graph database (epistemic-graph)

The full agent ([agent] / :latest) embeds the epistemic-graph engine (pulled in transitively via agent-utilities[agent]). For production — or to share one knowledge graph across multiple agents — run epistemic-graph as its own database container and point the agent at it instead of embedding it. Deployment recipes (single-node + Raft HA), connection config, and the full database architecture (with diagrams) are documented in the epistemic-graph deployment guide. The slim [mcp] server and the core CLI do not require the database.

Deployment (agent_server.py)

rom-manager-agent (entry point rom_manager.agent_server:agent_server) starts a Pydantic-AI A2A agent that auto-discovers the MCP tool surface from mcp_config.json and can expose an AG-UI web interface.

# Local: web UI on the default host/port, OTEL enabled
rom-manager-agent --web --otel \
  --provider openai --model-id gpt-4o-mini \
  --host 0.0.0.0 --port 8080

Container deployment (compose):

# docker/agent.compose.yml (excerpt)
services:
  rom-manager-agent:
    image: knucklessg1/rom-manager:latest
    command: ["rom-manager-agent", "--web"]
    environment:
      ROM_DIRECTORY: /games
      TRANSPORT: streamable-http
      HOST: 0.0.0.0
      PORT: 8080
      ENABLE_OTEL: "True"
      AUTH_TYPE: none
    volumes:
      - /srv/roms:/games
    ports:
      - "8080:8080"

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-os-genesis

This package can be provisioned for you — skill-guided — by the agent-os-genesis universal skill (its single-package deploy mode): it picks your install method, seeds secrets to OpenBao/Vault (or .env), trusts your enterprise CA, registers the MCP server, and verifies it — the same machinery that stands up the whole Agent OS, narrowed to just this package. Ask your agent to "deploy rom-manager with agent-os-genesis".

Secrets are read-existing + seeded via vault_sync — you are only prompted for what's missing.