MTG Card Analyzer

A collectors dream application, that gives you the ability to take pictures of your cards and have them instantly be recognized and added to your collection. This app will scan each image uploaded attempt to grab the name of the card and analyze the set image in an attempt to match it with a given set.

Status (Jan 2026): runnable on Node 22 with Tesseract.js v3; OCR + fuzzy matching + image hashing work. DB writes are now opt-in (off by default) while we stabilize.

Example

Here is a test extraction:

Original Card

Name Extraction

Extracted Text: g Platinum Angel

Cleaned Extracted Text: gPlatinumAngel

Before Pre Processing

After Pre-Processing

Type Extraction

Extracted Text: E Artifact Creature —- Angel

Cleaned Extracted Text: EArtifactCreatureAngel

Before Pre-Processing

After Pre-Processing

More examples are available here

Getting Up And Running

Prerequisites

• Node 22
• Tesseract.js v3 (npm dependency) with eng.traineddata available (an English traineddata is bundled at repo root)
• Optional: MySQL 8+ if you want to persist collections/needs-attention and hash cache

Install

• Clone: git clone https://github.com/dills122/MTG-Card-Analyzer.git
• Install deps: npm i
• Seed local name dictionary (NeDB): node ./src/db-local/bulk-insert.js

Configure MySQL (optional, only if you want writes)

• Create an RDS instance (or local MySQL). SQL scripts live in src/data/scripts/sql.
• Create secure.config.cjs (template: secure.config.template.cjs) with:

rds: {
    host: '...',
    database: '...',
    user: '...',
    password: '...'
}

Example local container:

docker run -d --name mtg-db -p 3306:3306 \
  -e MYSQL_ROOT_PASSWORD=rootPass122! \
  -e MYSQL_DATABASE=MtgCardCatalog \
  -e MYSQL_USER=app_user \
  -e MYSQL_PASSWORD=app_pass100! \
  mysql:8.0

First Test Run

Once all of the setup is complete to run your first image through the processor you can use one of the test images or use the given command below.

# Run at the base directory of the repo
node index.mjs scan ./src/test-images/PlatinumAngel.jpg

Current Commands

• scan <filePath> : scan a single image and output results
  • flags:
    • --query or -q: enable database writes (default false). When false, runs read-only and skips inserts.
    • --pretty or -p: pretty logging (default true).

Notes:

• If you want NeDB to write somewhere else (e.g., CI), set CARD_NAMES_DB_PATH=/tmp.
• Temp image snippets are written to the system temp dir and cleaned up per run.

Test images are provided at src\test-images

Backfiller utility instructions found here

Running Tests

npm test

Tests stub external calls; no MySQL needed. If you set a custom NeDB path for tests, export CARD_NAMES_DB_PATH=/tmp.

TypeScript Migration (incremental)

• TypeScript tooling is configured to allow JavaScript (allowJs) and to only typecheck (noEmit) so you can start migrating file-by-file.
• Run npm run typecheck (or pnpm typecheck) to get type feedback without touching the runtime.
• Future .ts files can live alongside existing .js under src/ and will be picked up automatically.

Packages Under the Hood

• fuzzyset.js
• image-hash
• jimp
• string-similarity
• tesseract.js