romm_library_items

Browse and filter ROMs in your library by platform, search terms, or favorites, with pagination and sorting options.

Instructions

Browse ROMs — filter by platform, search term, or favorites. Paginated.

platform_id: Filter to a single platform (use romm_platforms to find IDs). 0 = all. search: Text search in ROM names. favorite: Show only favorites (default: false). limit: Items per page (default 25, max 100). offset: Skip this many items (default 0). order_by: Sort field — "name", "fs_size_bytes", "updated_at" (default: name). order_dir: "asc" or "desc" (default: asc).

Input Schema

TableJSON Schema

Name	Required	Default
`platform_id`	No
`search`	No
`favorite`	No
`limit`	No
`offset`	No
`order_by`	No	name
`order_dir`	No	asc

Implementation Reference

server.py:391-442 (handler)

The handler function for romm_library_items which fetches ROMs from the Romm API, processes the output, and formats it for the user.

async def romm_library_items(
    platform_id: int = 0,
    search: str = "",
    favorite: bool = False,
    limit: int = 25,
    offset: int = 0,
    order_by: str = "name",
    order_dir: str = "asc",
) -> str:
    """Browse ROMs — filter by platform, search term, or favorites. Paginated.

    platform_id: Filter to a single platform (use romm_platforms to find IDs). 0 = all.
    search: Text search in ROM names.
    favorite: Show only favorites (default: false).
    limit: Items per page (default 25, max 100).
    offset: Skip this many items (default 0).
    order_by: Sort field — "name", "fs_size_bytes", "updated_at" (default: name).
    order_dir: "asc" or "desc" (default: asc).
    """
    limit = min(max(limit, 1), 100)
    params: dict = {
        "limit": limit,
        "offset": offset,
        "order_by": order_by,
        "order_dir": order_dir,
    }
    if platform_id:
        params["platform_ids"] = platform_id
    if search:
        params["search_term"] = search
    if favorite:
        params["favorite"] = True

    data = await _get("roms", params=params, long_timeout=True)

    items = []
    if isinstance(data, dict):
        items = data.get("items", [])
    elif isinstance(data, list):
        items = data

    if not items:
        qualifier = f" matching \"{search}\"" if search else ""
        qualifier += f" on platform {platform_id}" if platform_id else ""
        return f"No ROMs found{qualifier}."

    total = len(items)
    lines = [f"ROMs (offset {offset}, showing {total}):\n"]
    for i, rom in enumerate(items, 1):
        lines.extend(_fmt_rom_line(rom, index=i + offset))

    return "\n".join(lines)

mcp-romm