mangabaka-seeder

mbseed is a command-line tool for seeding edits to the MangaBaka manga/comics database, in the spirit of yambs for MusicBrainz.

Today it does one thing well: given a Webtoons series URL, it finds every cover that series has used, current and historical, and requests them added to the matching MangaBaka series. The current poster becomes the main (default) cover for the edition's language.

More sources (Tapas, Tappytoon, …) and more kinds of edits are planned; see docs/ARCHITECTURE.md for how they plug in.

How it works

1. Read the series. It reads the Webtoons page: title, title_no, language, and official or canvas.
2. Find the MangaBaka series. It searches MangaBaka by title and picks the series whose Webtoons link has the same title_no.
3. Collect covers.
   • Current: the portrait poster, the square thumbnail, and the banner and hero art.
   • Historical: the cover images in archived copies of the series page on the Wayback Machine, up to one snapshot per month.
4. Check each image.
   • It downloads each image to get its size and hash.
   • It classifies the image by shape: portrait → volume, square → other, wide → banner.
   • It drops duplicates and images MangaBaka already has.
5. Build the submission. The submission keeps all existing covers and adds the new ones. The current poster is the default, or the square for canvas series, which have no poster. Every new cover gets a note recording where and when it was seen.
6. Rehost the images. MangaBaka may not be able to download from Webtoons' image server, so new covers are re-uploaded to a durable image host: catbox.moe by default, or your own S3-compatible bucket.
7. Hand it to you. It either submits through the MangaBaka API (with your confirmation) or opens a local review page to help you enter it by hand.

Nothing is uploaded or sent to MangaBaka without your confirmation, and API submissions always go to review (save_mode: "review"). You choose the content rating; the default is safe.

Installation

Requires Node.js 22 or newer.

npm install
npm run build
npm link        # puts `mbseed` on your PATH

Usage

Usage: mbseed [options] <URL>

Options:
  --action <print|serve|submit>  What to do with the seed
                                 (default: submit if MANGABAKA_TOKEN is set, else serve)
  --series <id>                  MangaBaka series id (skips automatic matching)
  --no-history                   Only use covers currently on the source page
  --history-limit <n>            Max archived snapshots to inspect (default 60)
  --content-rating <rating>      safe | suggestive | erotica | pornographic
                                 (default: asked interactively, Enter = safe;
                                 required together with --yes)
  --image-host <catbox|s3|direct>
                                 Where to rehost new covers (default catbox)
  --json                         With --action print: print the seed as JSON
  --yes                          With --action submit: don't ask for confirmation
  --addr <host:port>             With --action serve: listen address (default localhost:8999)
  --verbose                      Log every HTTP request
  -h, --help                     Show help

Environment:

Variable	Purpose
MANGABAKA_TOKEN	Personal access token (mb-…). Enables --action submit.
MANGABAKA_API	API base URL (default https://api.mangabaka.org).
MBSEED_IMAGE_HOST	Default for --image-host.
CATBOX_USERHASH	Optional. Attaches catbox uploads to your catbox account so you can manage or delete them.
MBSEED_S3_ENDPOINT, MBSEED_S3_BUCKET, MBSEED_S3_REGION, MBSEED_S3_ACCESS_KEY_ID, MBSEED_S3_SECRET_ACCESS_KEY, MBSEED_S3_PUBLIC_URL	Settings for --image-host s3 (Cloudflare R2, Backblaze B2, MinIO or AWS).

Without API access (most users)

MangaBaka's submissions API is only open to contributors, or to users with at least 25 approved submissions. Without a token, mbseed starts a local review page:

mbseed https://www.webtoons.com/en/fantasy/tower-of-god/list?title_no=95
# → Review page at http://localhost:8999

The page shows each new cover with its thumbnail, size, suggested type, language, note and a content-rating selector (preset to safe). To use it:

1. Tick the covers you want.
2. Click Rehost selected.
3. Copy the hosted URLs.
4. Use the link to open MangaBaka's cover form for the series and paste them in. The form can't be pre-filled automatically.

With API access

export MANGABAKA_TOKEN=mb-...
mbseed https://www.webtoons.com/en/fantasy/tower-of-god/list?title_no=95

mbseed asks for the content rating (Enter = safe), fetches the current cover set and shows MangaBaka's preview diff. After you confirm, it rehosts the images and submits the request for review. For unattended runs, pass both --yes and --content-rating. If the API refuses access (403), it falls back to the review page.

Just looking

mbseed --action print https://www.webtoons.com/en/fantasy/tower-of-god/list?title_no=95
mbseed --action print --json <URL> > seed.json

Supported sources

Source	URLs	Current covers	Historical covers
WEBTOON (official & canvas)	https://www.webtoons.com/<lang>/…/list?title_no=N, m.webtoons.com	poster, square, banner, foreground	Wayback Machine

Each Webtoons language edition has its own title_no. Run mbseed once per edition URL; the covers are tagged with that edition's language.

Notes and limitations

• Image hosting. By default, covers are re-uploaded to catbox.moe, where files are permanent and need no account. The hosted URL still has to work when a MangaBaka reviewer looks at the request.
  • Avoid temporary hosts (e.g. litterbox): links can expire before review.
  • imgur is rejected by MangaBaka.
  • Skip rehosting with --image-host direct if you know MangaBaka can fetch the Webtoons URLs directly.
  • Uploads are cached by image hash, so rerunning doesn't upload the same image twice.
• Content rating. The tool can't judge content, so you choose the rating. For titles Webtoons marks as mature, it warns you to consider a rating above safe.
• Some covers may only exist in the archive. If an old cover is no longer on Webtoons' server, its archive.org copy is used instead.
• Not everything is a cover. Some historical images are promotional or landing-page art. Review the list before submitting.
• Requests are rate-limited to stay polite to Webtoons, the Wayback Machine and MangaBaka.

Development

npm test           # vitest, fixture-based, no network
npm run typecheck
npm run dev -- --action print <URL>   # run from source with tsx

To add a new source, see docs/ARCHITECTURE.md § 4.1. To add a new image host, see § 4.6.