FitFileSize MCP server

FitFileSize

Live at fitfilesize.com.

Compress a PDF or image to fit under a target file size. Built for the "this portal only accepts files under 4 MB" problem: pick a target, get a file that actually fits, or an honest report of the smallest achievable size.

Accepts PDF, JPEG, PNG, WebP, TIFF and BMP.

The site is FitFileSize; the Python package, CLI and FITPDF_* settings keep the original name, fitpdf.

How it works

The same three steps regardless of what you feed it:

recompression and unused-resource removal (pikepdf). For JPEGs it is an optimised re-encode that reuses the existing DCT coefficients, so the pixels are untouched and only metadata is dropped. Sometimes this alone is enough.

1. Lossless pass first. For PDFs that is object streams, stream

settings for the gentlest one that fits. PDFs step down Ghostscript image DPI and JPEG quality; images step down pixel dimensions and JPEG quality. Twelve rungs are searched in at most four attempts.

1. If still over target, binary-search a ladder of increasingly aggressive

file plus a clear "floor" warning instead of a silent failure.

1. If even the harshest rung cannot fit, you get the smallest achievable

Exact pixel size (images). Exam and ID forms often want both, say 200 x 230 pixels and under 50 KB. Given a width and height, the image is cropped to fill that frame (or padded onto white, if asked) and the ladder becomes JPEG quality alone at that size. The lossless pass and the "already small enough" shortcut are skipped, since neither changes the size.

Only step 1, the ladder's contents, and "render one rung" differ per media type. Those live behind one protocol in src/fitpdf/strategies.py, so the search itself is written once. Adding a third media type means implementing four methods, not touching the search.

Install

Requires Python 3.10+. Ghostscript is needed for the PDF path only; images work without it.

# Windows
winget install ArtifexSoftware.GhostScript

# Debian/Ubuntu (and WSL2)
sudo apt install ghostscript

Then:

pip install -e ".[dev]"

If Ghostscript is not on PATH, point to it with the FITPDF_GS env var.

Use

fitpdf scan.pdf -t 4mb            # fit under 4 MB
fitpdf photo.jpg -t 500kb         # images work the same way
fitpdf scan.pdf -t 500kb -o out.pdf
fitpdf scan.pdf                   # lossless-only pass

A lossy image result is always JPEG, so the output name is re-suffixed to match what was actually produced (logo.png in, logo.fit.jpg out).

Exit codes: 0 target hit, 2 floor reached (target not possible), 1 error.

Web service

A React UI with drag-and-drop upload, a target-size slider bounded by an estimated floor (the smallest the file can likely go), live progress while the ladder runs, and download links that self-destruct minutes after the run finishes (see Retention below).

Architecture

browser ──▶ nginx (SPA + /api proxy) ──▶ FastAPI ──▶ Redis ──▶ RQ worker
                                            │          │          │
                                            └──── shared job volume ────┘

Four pieces, each with one job:

by the CLI or the API. engine.py holds the media-agnostic search; strategies.py holds everything that knows about a specific file format. Neither knows anything about HTTP.

• src/fitpdf/ is the engine: pure Python, no web framework, driven either

work is enqueued, and nothing blocks the request thread.

• src/fitpdf/web/ is a thin API over it. Uploads land on a shared volume,

minutes and can be killed by a timeout, so it must not live inside a request.

• The worker runs Ghostscript out-of-process. A compression can take

hand-maintained mirror of the API in frontend/src/types/api.ts.

• frontend/ is a Vite + React + TypeScript SPA. Its types are a

Shortened. The full README is on GitHub.