mtgc — Personal Magic: The Gathering Library Catalog

A desktop and Android app (Tauri v2 + React) for cataloging your MTG collection: rapid fuzzy card entry, rich criteria search (colors, commander color-identity compatibility, mana value, type/subtype/keyword, price, format legality), and deck organization with per-card deck membership. All logic lives in a platform-agnostic Rust core, so both platforms share it.

Architecture

src/                 React + TypeScript UI (swappable presentation)
src-tauri/           Tauri v2 shell — exposes the core as typed commands
crates/mtgc-core/    Pure Rust: db, fuzzy search, filters, decks, ingester, sync
crates/mtgc-server/  Optional sync server: each user's libraries, OIDC and/or passwords

Two kinds of data, both in the OS app-data dir (e.g. ~/.local/share/com.garrettmills.mtgc/):

• your libraries — owned cards, decks, deck contents. Each lives on the device and works fully offline; sign in to a sync server to share them between devices (see Sync). You can keep several and switch between them (see Libraries). Export library… in the Info tab saves the open one as a JSON backup.
• reference.db — read-only card data built from Scryfall bulk. Bulky and re-downloaded per device, so it's never synced.

First-time setup

./scripts/devel-setup.sh     # Tauri system libs (webkit2gtk/gtk3) + Tauri CLI
npm install                  # frontend deps

Why GTK3, not GTK4? Tauri v2's Linux backend (wry/tao) hard-depends on GTK3 + webkit2gtk-4.1; there's no GTK4/webkitgtk-6.0 option yet. GTK4 support is tracked upstream but unmerged with no ETA: tauri#7335, tao#1104, wry#1228. Revisit once Tauri ships GTK4 support (likely Tauri v3).

Run

cargo tauri dev              # launches the desktop app (dev mode)

On first launch, click Download card data — it fetches the Scryfall Oracle Cards + Default Cards bulk (~a few hundred MB) and builds reference.db. After that the app is fully offline.

You can also build the card database from the command line:

cargo run -p mtgc-core --bin mtgc-ingest -- /path/to/reference.db

Production build

Build an optimized app with the frontend embedded into the executable:

./scripts/devel-setup.sh   # once, if not already done
cargo tauri build

Outputs (under the workspace target/release/):

• target/release/mtgc — the standalone executable. The web UI and all app logic are baked into this one file. It dynamically links the system WebKit/GTK libraries (webkit2gtk4.1, gtk3), so those must be present on the machine that runs it — they are on any modern desktop Linux and are installed by devel-setup.sh.
• target/release/bundle/rpm/*.rpm and .../deb/*.deb — native installers (Fedora / Debian-based) that add a menu entry and icon.

Useful variants:

cargo tauri build --no-bundle          # only the bare target/release/mtgc binary

Notes:

• The mtgc binary is a single file but relies on the system WebKit/GTK libs being present (installed by devel-setup.sh).
• The binary does not embed card data — first run still downloads the Scryfall bulk into the OS app-data dir. Your library lives there too; to share it between devices, see Sync.
• The [profile.release] settings in Cargo.toml (strip + LTO) make the release build take a few minutes but keep the binary small.

Distributing to Fedora (dnf repo)

Fedora machines get the app, and its updates, from a small dnf repo you host yourself. scripts/rpm-publish.sh builds a signed RPM and adds it to the repo in a directory you choose. It needs:

sudo dnf install rpm-sign createrepo_c

The first run also makes the package signing key. Give it the address the directory will be served at:

RPM_REPO_URL=https://rpm.example.com/mtgc ./scripts/rpm-publish.sh --init-key ~/rpm-mtgc

After that, publishing is just:

./scripts/rpm-publish.sh ~/rpm-mtgc     # or: npm run rpm:publish -- ~/rpm-mtgc

Then, on each machine, add the repo once and install:

sudo dnf config-manager addrepo --from-repofile=https://rpm.example.com/mtgc/mtgc.repo

sudo dnf install mtgc

From then on, sudo dnf upgrade picks up new releases.

• Serve the whole directory. Unlike the F-Droid repo, nothing in it is secret. It holds the RPMs, the signed repodata/, the public key (RPM-GPG-KEY-mtgc) and mtgc.repo. The newest three versions are kept, so a bad release can be undone with sudo dnf downgrade mtgc.
• Back up the signing key, ~/.local/share/mtgc/gnupg. It has no passphrase, so publishing runs unattended. Without it, each machine has to trust a new key before it takes another update.
• Versions work as on Android: 0.1.<commits on HEAD>, see Distributing to phones.
• The RPM is built against this machine's libraries, so it installs on this Fedora release and newer.

Distributing to Debian/Ubuntu (apt repo)

Debian-based machines get the app the same way, from an apt repo you host. scripts/deb-publish.sh builds the .deb here on Fedora and adds it to the repo in a directory you choose. It needs:

sudo dnf install reprepro dpkg

It signs with the same key as the dnf repo. If you haven't made that key yet, pass --init-key the first time. Either way, give the first run the address the directory will be served at:

DEB_REPO_URL=https://deb.example.com/mtgc ./scripts/deb-publish.sh ~/deb-mtgc

After that, publishing is just:

./scripts/deb-publish.sh ~/deb-mtgc     # or: npm run deb:publish -- ~/deb-mtgc

Then, on each machine, add the repo once and install:

sudo curl -fsSLo /etc/apt/sources.list.d/mtgc.sources https://deb.example.com/mtgc/mtgc.sources

sudo apt update && sudo apt install mtgc

From then on, sudo apt upgrade picks up new releases.

• Serve the whole directory. It holds pool/, the signed dists/, the public key (mtgc.asc) and mtgc.sources, which carries the key inline so machines don't need a separate keyring step. It also has a README.html with these install steps, for anyone who opens the address in a browser. conf/ and db/ are reprepro's own state; they're harmless to serve but aren't needed. The newest three versions are kept, so a bad release can be undone with sudo apt install mtgc=<older version>.
• Versions are the same as the RPM's. A build published with --allow-dirty gets a ~dirty suffix, which apt sorts below the clean build of the same version.
• The .deb is built against this machine's libraries, so it needs a distro with at least this Fedora's glibc (2.43 on Fedora 44). Older Debian and Ubuntu releases can't install it.

Distributing to Windows

The Windows installer is cross-built here on Linux and published to a plain downloads folder you host. scripts/windows-publish.sh builds it through cargo-xwin and needs, once:

sudo dnf install mingw-nsis-base llvm lld clang

cargo install --locked cargo-xwin

rustup target add x86_64-pc-windows-msvc

Then, for each release:

./scripts/windows-publish.sh ~/win-mtgc     # or: npm run windows:publish -- ~/win-mtgc

On Windows, download and run the setup.exe. A newer one upgrades the installed app in place.

• Serve the whole directory. It holds the versioned installers (mtgc_0.1.<n>_x64-setup.exe, the newest three), mtgc-latest-x64-setup.exe as a stable link to the newest, and SHA256SUMS.
• Only the NSIS setup.exe can be built off Windows; an MSI needs WiX, which runs only on Windows. The first build downloads the MSVC CRT and Windows SDK into ~/.cache/cargo-xwin.
• The installer isn't code-signed, so SmartScreen warns about an unknown publisher the first time: More info → Run anyway. It fetches WebView2 if the machine lacks it (Windows 10 and 11 normally ship it).
• Versions work as on Android: 0.1.<commits on HEAD>, see Distributing to phones.

Using it

• Add Cards — type a name (typos OK); ↑/↓ then Enter adds a copy.
• Library — filter owned cards by name, colors, commander identity (color identity ⊆ chosen), mana value, power/toughness, price, format legality, type/subtype/keyword, or deck. Hover a row's thumbnail for a full-size preview that tracks the cursor. Rows show which decks a card is in and a warning (⚠) when it's assigned to more decks than you own. Toggle List / Tiles (top-right) to switch between the table and a grid of full card images; the choice is remembered.
• Card Search — the same filters over every card, owned or not. Select rows (or tiles) and bulk-add them to a deck; one undo covers the whole batch.
• Deck contents offer the same List / Tiles toggle and hover previews.
• Decks — create decks and assign owned cards; set per-deck quantities.

Both filter panels share a row of quick toggles: hide Universes Beyond (cards that exist only as another property — Lord of the Rings, Warhammer 40,000, Marvel), hide digital-only (Arena/MTGO cards such as Alchemy rebalances), hide Un-set joke cards, or keep only cards that can be a commander. The three exclusions are derived as every printing, so an ordinary card reprinted into one of those sets — Lightning Bolt appears in Marvel Commander — isn't hidden.

Those three, plus the power/toughness filters, live in reference.db, which is rebuilt rather than migrated. After upgrading, click Update card data once to enable them; until then they're inert rather than broken. Price, format legality and can be a commander work immediately.

Printings

The library counts cards, not printings, but you can say which printing a copy is when it matters. Click a card's image in the Library or a deck to open its preview. The Owned section lists your copies by printing and finish (nonfoil / foil / etched), with a stepper for each, and Add a printing… picks another. Copies you haven't assigned a printing to stay unspecified: "5 copies · 3 by printing · 2 unspecified". Assigning more copies to printings than you own raises the owned count to match. Lowering the owned count drops the most recently added printing entries first.

In a deck, Shown in this deck → Change… picks which printing's art that slot shows, and Default goes back to the usual one. This is display only: it doesn't need to be a copy you own.

Decklist export writes a chosen or tracked printing the way Moxfield and Arena do, and import reads it back:

1 Sol Ring (2X2) 315 *F*
4 Lightning Bolt (2XM) 129

*F* marks foil and *E* etched. A library export writes one line per printing, then a plain line for the unspecified copies. A suffix that doesn't match any printing still imports the card itself.

Library → Import cards… also takes a ManaBox export of a collection or binder, either the .txt or the .csv. Both add to what you already own. The CSV names each copy's exact printing and finish, so it's the better of the two. Condition, language, prices and the other ManaBox fields aren't kept. Proxies count as owned copies. After you pick the file, the import asks for a location to file the cards under, pre-filled with the file's name (a ManaBox export is named after its binder). Leave it blank to keep cards' current locations.

The picker's dates and languages need card data from this version. Until you update it, printings are listed without them. Whenever your card data is missing something the app could use, a notice under the top bar offers Update card data, and Import card data… too on a phone. Dismissing it with Not now lasts until a later version needs something more.

Libraries

Every device starts with one library, Main. To keep others alongside it — a scratch library to try things in, a cube, a trade binder — click the library name at the left of the top bar and choose New library…. The same menu switches between them; Info → Libraries lists them all, and is where you rename or delete them (on a phone, it's the only place).

Each library has its own cards and decks; the selected deck and the "location" for new cards are remembered per library too. Card data is shared.

A new library can sync to your other devices or stay on this one. Synced libraries appear on every signed-in device by themselves; one kept on this device only never leaves it, which makes it the safe place to experiment. The Sync checkbox in Info → Libraries changes your mind either way.

Deleting a synced library asks whether to remove it from this device (it stays on the server and on your other devices, and this one stops downloading it) or delete it everywhere. Other devices keep their copy of a library deleted everywhere, marked as deleted from the server, until you remove it or put it back. Main can be renamed but not deleted.

Libraries' files live in the app-data dir: Main where the one library always lived, the others under libraries/.

Sync

Your library always lives on the device you're using, so the app works the same with or without a network. To keep several devices in step, run an mtgc sync server and sign in to it from each one: Info → Sync server, enter its address, and Sign in…. Sign-in happens in your browser, on the server's own page — with a username and password, or through your single sign-on provider, whichever the server offers — and the browser hands the app back a token for that device alone.

Editing in two places merges rather than one side overwriting the other. Each device remembers the last version of the library it knows the server had, and merges three ways against it — which is what lets it tell "you changed this" from "they deleted it": edit different cards on a phone offline and on the desktop, and both survive. When both sides change the same field, the server's value wins and the change is reported so you can correct it.

Sync runs by itself — at launch, on every switch away from and back to the app, on reconnecting, and every few minutes while open. The top bar shows where it stands (Synced, Offline — changes will sync, …); Sync now in the Info tab forces a pass. Offline, edits simply wait on the device: nothing is lost, and they go out with the next sync that reaches the server.

Each library syncs on its own: a library's edits never reach another one. An older sync server keeps just one library per account, which Main syncs with; update the server to sync the others.

The first time a device signs in to an account that already has a library, and the device has one too, it asks whether to combine them (nothing from either is lost) or use the server's library instead of this device's.

The Info tab also lists the account's signed-in devices, so a lost phone can be signed out from another one.

Printings and older versions. A library with printings in it (see Printings) is saved in a newer format. A device or server running an older version refuses it and says to update, rather than syncing and quietly losing them. Libraries that don't use printings stay readable by older versions. Update the sync server before the first device starts using printings.

Upgrading from folder sync? Earlier versions kept the library as a JSON file in a folder your sync tool watched. Your library is already on each device, so signing in to a server picks up from there; the first device to sign in uploads it. If one device's copy is out of date, use Import library file… on it to combine in the library.json from the synced folder. Builds older still had you manage library.db yourself; the Info tab offers Import old library once for that.

Running the sync server

mtgc-server is a single binary with a SQLite database, shipped as a container image. Inside the container it listens on port 8080 and keeps its database in /data; everything else is environment variables (below).

To run it locally, build the image, then run it with the port forwarded to localhost and a named volume for the data:

docker build -f crates/mtgc-server/Dockerfile -t mtgc-sync-server .

docker run -d --name mtgc-sync-server \
  -p 127.0.0.1:8080:8080 \
  -v mtgc-sync-data:/data \
  -e MTGC_PUBLIC_URL=http://localhost:8080 \
  mtgc-sync-server

docker exec -it mtgc-sync-server mtgc-server user add yourname   # prompts for a password

Then sign in from the desktop app with http://localhost:8080. For more settings, copy crates/mtgc-server/deploy/.env.example to .env beside it (git ignores it) and pass --env-file crates/mtgc-server/deploy/.env instead of the -e. Podman takes the same commands.

The container runs as UID 10001. A named volume, as above, picks up the right ownership by itself; if you bind-mount a host directory instead, chown 10001 it first.

In production, put it behind something that terminates HTTPS — the Android app refuses plain HTTP outside debug builds — and set MTGC_PUBLIC_URL to the https:// address users reach it at. On Kubernetes that means a Deployment with one replica (it's a single SQLite file, so replicas can't share it) and a Recreate strategy, a PersistentVolumeClaim mounted at /data, a Service on port 8080, and an Ingress for TLS. GET /healthz answers ok for probes. Keep MTGC_OIDC_CLIENT_SECRET in a Secret. Run the account commands with kubectl exec -it deploy/<name> -- mtgc-server user add <name>.

A freshly provisioned volume is usually owned by root, which the server (UID/GID 10001) can't write to — it fails at startup with "/data isn't writable". Have Kubernetes hand the volume to its group in the pod spec:

spec:
  securityContext:
    runAsNonRoot: true
    runAsUser: 10001
    runAsGroup: 10001
    fsGroup: 10001

A few volume types ignore fsGroup (hostPath, and some NFS and local-path provisioners). For those, chown 10001:10001 the backing directory once, or add an init container that does it.

To build the image and push it to Docker Hub (glmdev/mtgc):

npm run sync-server:build   # → docker.io/glmdev/mtgc:latest
npm run sync-server:push    # after `docker login docker.io`

Both call scripts/sync-server-image.sh. IMAGE_TAG overrides the latest tag, IMAGE_REPO points it at another repository (e.g. IMAGE_REPO=registry.example.com/mtgc), and CONTAINER_ENGINE=podman picks podman when docker is also installed.

Configuration is all environment variables:

Variable	Default
MTGC_PUBLIC_URL	(required)	The https:// address users reach the server at, exactly as the proxy serves it
MTGC_BIND	0.0.0.0:8080	Listen address
MTGC_DB	mtgc-server.db	SQLite database path
MTGC_LOCAL_AUTH	true	Username/password accounts
MTGC_OIDC_ISSUER	—	Turns on single sign-on, e.g. https://auth.example.com/application/o/mtgc/
MTGC_OIDC_CLIENT_ID, MTGC_OIDC_CLIENT_SECRET	—	A confidential client, with redirect URI ${MTGC_PUBLIC_URL}/auth/callback
MTGC_OIDC_NAME	single sign-on	Shown on the button: "Sign in with …"
MTGC_OIDC_SCOPES	openid email profile
MTGC_ALLOWED_EMAILS	—	Comma-separated allow list of verified emails; unset leaves it to the provider

With both sign-in methods on, the sign-in page offers both; with only single sign-on, it goes straight to the provider. Each provider identity and each local account is its own user with its own library.

Local accounts are managed from the command line; there's no sign-up page, so a server on the internet can't be filled with accounts by strangers:

mtgc-server user add <name> [--display-name <text>]   # prompts for a password
mtgc-server user passwd <name>
mtgc-server user remove <name> --yes                  # also deletes their server-side library
mtgc-server user list

The server keeps the last 50 versions of each library in its database (library_history) as a safety net for recovering by hand.

Develop / test

cargo test -p mtgc-core      # core: db, search, filters, decks, ingest, sync merge + cycle
cargo test -p mtgc           # shell: config, merge-base storage, sign-in listener
cargo test -p mtgc-server    # server: sign-in, compare-and-swap, devices, end-to-end sync
npm run build                # typecheck + build frontend
cargo build                  # build everything incl. the desktop app

The sync merge is a pure function over plain structs (mtgc_core::sync::merge3), and the sync cycle runs over a Remote trait (mtgc_core::sync::remote), so the cases that matter — concurrent edits, a delete racing an edit, a lost reply, a lost write race — are unit tests rather than something you have to reproduce across two devices. crates/mtgc-server/tests/sync_e2e.rs then runs two devices against the real server over HTTP.

To try sign-in by hand, run a server locally (MTGC_PUBLIC_URL=http://127.0.0.1:8080 cargo run -p mtgc-server, after cargo run -p mtgc-server -- user add me) and sign in from the app with that address. From the Android emulator, the host is http://10.0.2.2:8080; debug builds allow plain HTTP.

To typecheck the Android Kotlin without building the APK (it doesn't invoke cargo, so it won't disturb a running dev session):

cd src-tauri/gen/android && ./gradlew :app:compileUniversalDebugKotlin

Android

The Rust core and frontend are platform-agnostic, so the Android build shares all app logic with the desktop; only data provisioning and file access differ.

One-time setup

Install Android Studio and launch it once so its wizard downloads the SDK, then:

./scripts/android-setup.sh

That adds what Android Studio doesn't install by default: the SDK command-line tools, a pinned stable NDK, and the Rust Android targets. It prints the three environment variables to export (ANDROID_HOME, NDK_HOME, JAVA_HOME).

Why the NDK? mtgc-core builds rusqlite with the bundled feature (compiles SQLite from C) and rustls pulls in ring (C/asm), so a C cross-toolchain is required. The bundled SQLite can't be swapped for Android's system libsqlite3 either — the card schema needs FTS5 with the trigram tokenizer, which platform SQLite often lacks.

Why JAVA_HOME? The Android build (Gradle 9.6, AGP 9) runs on JDK 17 through 25. The script prefers Android Studio's bundled JetBrains Runtime, then the newest system JDK in that range, and skips anything newer than 25 until it's been tested.

Build and run

Every Android command needs ANDROID_HOME / NDK_HOME / JAVA_HOME. Source the helper once per shell — it auto-detects all three:

source scripts/android-env.sh      # bash / zsh

source scripts/android-env.fish    # fish

Only the env helper is shell-specific (it has to mutate the calling shell); android-setup.sh is executed rather than sourced, so it works from any shell.

Then, from the project root:

cargo tauri android dev --open   # dev server + open in Android Studio
cargo tauri android build --apk  # standalone release APK

src-tauri/gen/android is committed (unlike the rest of gen/) because AndroidManifest.xml is hand-edited — Android permissions have no tauri.conf.json equivalent.

Working in Android Studio

Use cargo tauri android dev --open rather than opening src-tauri/gen/android directly. Studio's Run button delegates the Rust build to cargo tauri android android-studio-script, which expects a running Tauri dev session — it reads the dev-server address from /tmp/<identifier>-server-addr. Open the Gradle project on its own and the build fails with failed to read missing addr file.

With the dev session running, Studio's device dropdown, Device Manager (emulator), and debugger all work normally.

JetBrains Toolbox users: --open finds Studio by scanning XDG data dirs for a .desktop entry whose Name is exactly Android Studio. Toolbox writes a versioned name instead (e.g. Android Studio Quail 2 2026.1.2 Patch 1), so the lookup misses and the launch fails with a confusing Cmd(["Android Studio"]) ... No such file or directory. android-setup.sh drops in a hidden shim entry (~/.local/share/applications/android-studio.desktop) to fix this; delete that file to undo it.

To build without Studio and without a dev server, use cargo tauri android build — that path needs no addr file.

Distributing to phones (F-Droid)

Releases go out through a small F-Droid repo you host yourself: add it to the F-Droid app once, and every new build then shows up there as an update. scripts/fdroid-publish.sh builds a signed arm64 APK and adds it to the repo in a directory you choose. It needs fdroidserver:

pipx install fdroidserver

The first run also makes the app's signing key and the repo. Give it the address the repo will be served at:

FDROID_REPO_URL=https://fdroid.example.com/repo ./scripts/fdroid-publish.sh --init-keystore ~/fdroid-mtgc

After that, publishing is just:

./scripts/fdroid-publish.sh ~/fdroid-mtgc     # or: npm run android:publish -- ~/fdroid-mtgc

It ends by printing the repo address with its fingerprint (https://…/repo?fingerprint=…); add that in F-Droid under Settings → Repositories.

• Serve only ~/fdroid-mtgc/repo (and archive/, which holds older versions, if you like) — any static file server will do. Never serve the directory itself: it holds the repo signing key (keystore.p12) and its password (config.yml).
• Back up both keys: ~/.local/share/mtgc/android-release.jks with src-tauri/gen/android/keystore.properties (the app key and its password), and the repo directory's keystore.p12 with config.yml. Android only installs an update signed with the same key as the installed app, so without the app key every phone would have to uninstall and reinstall.
• Versions are automatic. The Android versionCode is the number of commits on HEAD, and the version shown is 0.1.<that count>, e.g. 0.1.47, so any commit can ship without a bump. The major and minor come from tauri.conf.json. That's also why pushed history shouldn't be rewritten. The script won't publish uncommitted changes without --allow-dirty, or a versionCode the repo already has.
• A phone with a debug build, or anything signed with another key, has to uninstall it before F-Droid can install the release, and uninstalling deletes the app's data. Sync or Export library… first.

Without keystore.properties, cargo tauri android build still produces an unsigned APK as before.

Card data on a phone

Downloading card data streams ~740MB of JSON to build a ~73MB database, which is slow on mobile and may be killed if the app is backgrounded. Faster: copy reference.db from a desktop install onto the device and use Import card data…. The file is validated before it replaces anything.

Sync on Android

Signing in works as on desktop: the browser opens the server's sign-in page, and returns to the app through the mtgc:// URL scheme (registered by the deep-link plugin from plugins.deep-link in tauri.conf.json). The app needs no storage permission — the library lives in its private storage, and syncing is network only.

Branding

The logo is an original pirate-ship silhouette in the terracotta brand color (#C8553D) — a nod to the MTG card "Pirate Ship", not a reproduction of its art. Source: src-tauri/icons/logo-source.svg. To regenerate the full platform icon set after editing it:

cargo tauri icon src-tauri/icons/logo-source.svg