ArcadeJanitor

ArcadeJanitor is a focused Rust CLI and MCP server for managing MAME ROM folders using only mame.xml and catver.ini metadata.

Why ArcadeJanitor?

ArcadeJanitor began with a straightforward need: clean up a main MAME ROM directory. Existing tools offered powerful capabilities, but their complexity was more than was needed for that task. ArcadeJanitor is designed to be simple and fast for focused ROM folder cleanup, whether used directly from the command line or through an AI agent.

Workspace

• src/arcadejanitor-core - shared models, parsers, operations, and utilities
• src/arcadejanitor-cli - command-line interface
• src/arcadejanitor-mcp - Axum HTTP/WebSocket MCP server

v1 scope

ArcadeJanitor v1 supports MAME ROM folders, mame.xml, catver.ini, catalog queries, collection filtering and auditing, statistics, moving, deleting, and metadata cache management. It intentionally excludes CHDs, BIOS dependency resolution, scraping, GUI, dashboards, cloud sync, plugins, and non-MAME systems.

--catver is optional. When it is omitted, ArcadeJanitor downloads catver.ini from the maintained upstream repository on first use and caches it in the current user's OS cache directory. Supplying --catver <path> always uses that file instead.

When --mame-executable <path> is supplied without --mame-xml, ArcadeJanitor runs mame.exe -listxml and caches the result in the current user's OS cache directory. The cached XML is reused when no XML path or executable is provided.

Installation

Download the package for your operating system from the latest GitHub release. Each package contains the arcadejanitor CLI and arcadejanitor-mcp server.

On Linux or macOS, extract the downloaded archive:

# Use "macos" instead of "linux" when extracting the macOS package.
tar -xzf arcadejanitor-<version>-linux.tar.gz
chmod +x arcadejanitor arcadejanitor-mcp
./arcadejanitor --help

On Windows, extract the downloaded archive with PowerShell:

Expand-Archive .\arcadejanitor-<version>-windows.zip -DestinationPath .\arcadejanitor
Set-Location .\arcadejanitor
.\arcadejanitor.exe --help

Move the extracted binaries to a directory on PATH to run them from any location, or use the relative paths shown in the examples below.

CLI

ArcadeJanitor uses a resource-first command structure:

arcadejanitor
├── rom        list, show, move, delete, stats, audit
├── catalog    list, show
├── category   list, show
├── source     list, refresh, clear
├── mcp        start, install
└── completions

Use arcadejanitor <resource> --help and arcadejanitor <resource> <command> --help to discover commands and options.

Examples

./arcadejanitor rom list ./roms --genre maze --mame-xml ./mame.xml --catver ./catver.ini
./arcadejanitor rom show ./roms --name pacman --mame-xml ./mame.xml --catver ./catver.ini
./arcadejanitor catalog show --name pacman --mame-xml ./mame.xml --catver ./catver.ini --output json
./arcadejanitor catalog list --manufacturer Namco --year 1980..1985 --mame-xml ./mame.xml
./arcadejanitor category show --category Shooter --subcategory vertical --mame-xml ./mame.xml
./arcadejanitor rom move ./roms --destination ./filtered --genre maze --mame-xml ./mame.xml
./arcadejanitor rom move ./roms --destination ./filtered --genre maze --execute --mame-xml ./mame.xml
./arcadejanitor rom delete ./roms --name "prototype*" --execute --mame-xml ./mame.xml
./arcadejanitor rom stats ./roms --output json --mame-xml ./mame.xml
./arcadejanitor rom stats ./roms --category Shooter --subcategory "Flying Vertical" --show-missing --output json --mame-xml ./mame.xml
./arcadejanitor rom stats ./roms --show-missing --show-unmatched --output json --mame-xml ./mame.xml
./arcadejanitor rom audit ./roms --mame-xml ./mame.xml
./arcadejanitor source list --output table
./arcadejanitor mcp start ./roms --mame-xml ./mame.xml --catver ./catver.ini
./arcadejanitor mcp install --system vscode ./roms --mame-xml ./mame.xml --catver ./catver.ini
./arcadejanitor completions --shell powershell

rom move, rom delete, and source clear only preview their operations unless --execute is present. ROM mutations also require at least one selector or explicit --all.

All list-like commands support table, JSON, and TSV output with --output. Use --no-header for headerless table or TSV output. Result data is written to stdout; progress and diagnostics are written to stderr.

rom stats always includes aggregate missing and unmatched counts. Add --show-missing or --show-unmatched to include the corresponding ROM names.

The source options --mame-xml, --mame-executable, and --catver are global and can appear before or after a subcommand. Their environment variable equivalents are ARCADEJANITOR_MAME_XML, ARCADEJANITOR_MAME_EXECUTABLE, and ARCADEJANITOR_CATVER.

MCP Server

The MCP server manages exactly one ROM collection. It requires --rom-folder <path> or ARCADEJANITOR_MAME_ROM_FOLDER; MCP tools never accept a ROM folder, MAME XML source, MAME executable, or catver path. This prevents an agent from operating on an unintended folder or metadata source.

The server accepts the same metadata source options as the CLI: --mame-xml, --mame-executable, and --catver, with ARCADEJANITOR_MAME_XML, ARCADEJANITOR_MAME_EXECUTABLE, and ARCADEJANITOR_CATVER as their respective environment variables. It uses the same automatic MAME XML extraction, catver download, and per-user OS cache as the CLI.

Start the HTTP server with explicit configuration:

./arcadejanitor-mcp --rom-folder ./roms --mame-xml ./mame.xml --catver ./catver.ini

The CLI can start the packaged MCP server with the same metadata source options:

./arcadejanitor mcp start ./roms --mame-xml ./mame.xml --catver ./catver.ini

Install in an agentic development system

Use arcadejanitor mcp install --system <system> [rom-folder] to install the packaged MCP server as a user-scoped stdio or HTTP server. The supported systems are vscode, vscode-insiders, copilot-cli, and claude-code. Installation replaces the existing arcadejanitor server entry for that system without changing other configured servers.

./arcadejanitor mcp install --system vscode ./roms --mame-xml ./mame.xml --catver ./catver.ini
./arcadejanitor mcp install --system copilot-cli ./roms --mame-executable /path/to/mame
./arcadejanitor mcp install --system claude-code ./roms

Install an HTTP server, including one hosted on another machine, with --transport http --url http://host:3000/mcp. HTTP installs require the server to be started manually; add --start-now and a local ROM folder to start it automatically after installation.

The command uses each system's native user-scope registration interface: VS Code's active user profile, GitHub Copilot CLI's ~/.copilot/mcp-config.json, and Claude Code's user-scoped configuration. The target client command (code, copilot, or claude) must be available on PATH.

The server listens on http://127.0.0.1:3000 by default. Keep it running in a separate terminal while using an MCP client. Set ARCADEJANITOR_MCP_ADDR to change the listen address. Set ARCADEJANITOR_MCP_TOKEN to enable the destructive tools (move_roms and delete_roms). These tools preview changes by default. Set dry_run to false to apply them.

VS Code configuration

Use stdio to let VS Code start a configured server directly. Create .vscode/mcp.json in your workspace (or use MCP: Open User Configuration from the Command Palette):

{
  "servers": {
    "arcadejanitor": {
      "type": "stdio",
      "command": "/absolute/path/to/arcadejanitor-mcp",
      "args": [
        "--transport", "stdio",
        "--rom-folder", "/absolute/path/to/roms",
        "--mame-xml", "/absolute/path/to/mame.xml",
        "--catver", "/absolute/path/to/catver.ini"
      ],
      "env": {
        "ARCADEJANITOR_MCP_TOKEN": "replace-with-a-secret-token"
      }
    }
  }
}

Replace the command-line settings with the corresponding environment variables in this env object if preferred.

GitHub Copilot CLI configuration

Register a configured stdio server:

copilot mcp add --transport stdio arcadejanitor -- \
  /absolute/path/to/arcadejanitor-mcp --transport stdio \
  --rom-folder /absolute/path/to/roms --mame-xml /absolute/path/to/mame.xml \
  --catver /absolute/path/to/catver.ini

The configuration is saved to ~/.copilot/mcp-config.json. To use a manually started HTTP server instead, register its endpoint with the token header when destructive tools are enabled:

copilot mcp add --transport http \
  --header "Authorization: Bearer YOUR_TOKEN" \
  arcadejanitor http://127.0.0.1:3000/mcp

Use /mcp in an interactive Copilot CLI session to verify that arcadejanitor is connected and to view its available tools.

Endpoints:

• GET /health
• POST /mcp (MCP JSON-RPC)
• GET /ws

Set ARCADEJANITOR_MCP_TOKEN to enable destructive MCP tools. HTTP clients must authenticate using the standard HTTP authorization header. WebSocket connections from non-local browser origins are rejected.

Development

Integration tests

The integration suite keeps a deterministic, cut-down metadata dataset in tests/fixtures/: 100 MAME XML machines and 100 catver entries. Each CLI and MCP integration test creates its ROM folder under a tempfile directory and writes only small fake ROM files, so tests never use or modify the developer's ArcadeJanitor cache or ROM collection.

Run the end-to-end suites with:

cargo test -p arcadejanitor-cli --test cli
cargo test -p arcadejanitor-mcp --test http_integration

The CLI test launches the compiled binary and verifies JSON output. The MCP test launches the server on an ephemeral localhost port and calls the scan_roms tool through POST /mcp, which is the recommended boundary for testing an HTTP MCP server. Lower-level handler tests remain useful for fast protocol edge cases; use both layers rather than mocking the server transport.

Windows prerequisites

The Windows Rust toolchain in this project targets MSVC. Install the Desktop development with C++ workload from the Visual Studio Installer, including the Windows SDK, then run Cargo from a Developer PowerShell for Visual Studio terminal. This puts Microsoft's linker and its required libraries on PATH.

If the linker error reports Usage: link FILE1 FILE2, a different executable named link.exe is being found first. Check the selected executable with:

Get-Command link.exe -All

Run Cargo from the Visual Studio Developer PowerShell, or remove/reorder the conflicting link.exe directory in your user/system PATH. For example, if C:\Program Files\coreutils\bin\link.exe is returned, remove that directory from PATH for the current Visual Studio Developer PowerShell session:

$env:Path = ($env:Path -split ';' | Where-Object { $_ -ne 'C:\Program Files\coreutils\bin' }) -join ';'

The selected linker should be Visual Studio's link.exe, typically under Microsoft Visual Studio\...\VC\Tools\MSVC\...\bin\Hostx64\x64.

Alternatively, use the repository's Dev Container, which provides a Linux Rust toolchain and avoids host linker configuration.

Dev Container

Open this repository in VS Code and run Dev Containers: Reopen in Container to use the checked-in Rust development environment. It installs the stable Rust toolchain with rustfmt, clippy, and rust-src, GitHub CLI, and the workspace's recommended extensions. The MCP API is forwarded on port 3000.

cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

License

ArcadeJanitor is licensed under the MIT License.