# lantern-mcp

A CLI and MCP server for [Lantern](https://lantern.mediahist.org), the full-text search platform of the [Media History Digital Library](https://mediahistoryproject.org) — the digitised entertainment trade press. *Variety*, *Billboard*, the *New York Clipper*, *Motion Picture Herald*, *Boxoffice*, the studio year books and the fan magazines: roughly two million scanned pages of the industry writing about itself, from the 1900s to the 1960s.

No API key, no account, no registration.

## What it gives you

Search resolves to an **individual scanned leaf** and returns that leaf's **keyword-in-context excerpt inline**, so judging a hit costs no second request. Every result links back to the page on the Internet Archive, with the search term pre-highlighted.

```sh
lantern search '"Gone with the Wind"' --from-year 1939 --to-year 1941 --per-page 3
```

```
# "Gone with the Wind" [1939–1941] — 4475 results, page 1 of 1492
[1] December 1939  motionpictureher137unse
    leaf 213 · Periodicals
    ... the première of {Gone} {with} {the} {Wind} in Atlanta ...
    motionpictureher137unse_0213
        http://archive.org/stream/motionpictureher137unse#page/n212/mode/2up/search/...
```

## Install

```sh
uv tool install --force --reinstall .
```

That puts `lantern` on your `PATH`. To register the MCP server with Claude Code, Codex or Gemini:

```sh
uv run lantern-mcp-install                            # basic search tool only
uv run lantern-mcp-install --enable-advanced-search   # plus filters and facets
```

The CLI always exposes every filter; the MCP server hides the advanced ones behind that flag, because a tool schema sits in the model's context permanently whether it is used or not.

## Commands

### `search`

```sh
lantern search '"Technicolor"'                            # 86,314 results
lantern search '"Technicolor" AND Warner'                 # 33,868 results
lantern search '"Gone with the Wind"' --title Variety --sort date_asc
lantern search '"Gone with the Wind"' --collection 'Hollywood Studio System'
```

| Flag | Meaning |
| --- | --- |
| `--pages N\|N-M\|all` | which result pages to fetch (default: 1) |
| `--per-page N` | results per request, up to 100 |
| `--from-year` / `--to-year` | year of publication, inclusive |
| `--collection` | exact collection value, e.g. `Early Cinema` |
| `--title` | exact publication title, e.g. `Variety` |
| `--format` | exact format, e.g. `Periodicals`, `Books`, `Annuals` |
| `--language` | exact language, e.g. `English` |
| `--sort` | `relevance` (default), `date_asc`, `date_desc` |
| `--json` | emit JSON instead of text |

Every filter is optional and absent by default. The active ones are echoed back in the result header, so a small total is always traceable to what produced it.

**A query is required.** Lantern has no browse-everything mode: an empty query returns 0 results, and so does `*`, which is matched literally rather than as a wildcard. There is no filters-only search, so the CLI refuses one rather than returning a confident zero.

### `facets`

The filters match whole strings, so `Vaudeville` for `Theatre and Vaudeville` returns zero with no error — indistinguishable from an empty archive. `facets` is how you get the value verbatim:

```sh
lantern facets title '"Gone with the Wind"'
```

```
# title values for "Gone with the Wind" — 21 listed
      1331  Motion Picture Herald
      1242  Boxoffice
      1231  Variety
      1014  Motion Picture Daily
       686  The Exhibitor
       523  Showmen's trade review
```

The counts describe that query's result set — which trade papers carry a term, and in what numbers. They are **never** corpus-wide: facet counts are computed over the hits, so a query is required here too. Without one every value comes back as `0`, which reads as an empty archive rather than as the missing argument it is.

Fields: `collection`, `title`, `format`, `language`. There is no `year`, because year is a *range* filter rather than a list facet.

### `get`

```sh
lantern get motionpictureher137unse_0213
```

Prints the path to the cached OCR text of that one leaf.

**This is expensive per volume, not per page.** Lantern indexes text it does not host: the scans live on the Internet Archive, which publishes OCR per *volume* and never per page. So reading one leaf means fetching that volume's OCR entire — 8 to 25 MB — and slicing the leaf out locally. The volume is then cached, so every later leaf of the same volume is free. Sweeping one publication is dramatically cheaper than sweeping across many.

Most of the time you do not need it: `search` already returns the excerpt.

## Query syntax

**The default operator is `OR`, not `AND`.** This is the single most important thing to know about this source, and it fails silently:

```sh
lantern search 'Technicolor Warner'          # 332,891 — pages holding EITHER word
lantern search '"Technicolor" AND Warner'    #  33,868 — pages holding both
```

Nothing in the first result set announces that it is mostly pages containing the word *Warner*. The CLI prints a warning when it sees two or more unquoted words for exactly this reason.

- `"quoted phrases"` match exactly.
- `AND`, `OR` and `NOT` all work. They partition cleanly: for one sample query, `A AND B` returned 788 and `A NOT B` returned 995, summing to the 1,783 of `A` alone.
- **Wildcards and proximity do not work and fail silently.** A trailing `*` returns near-zero rather than expanding, and `"a b"~2` breaks the phrase and degrades to `OR`, returning more results than the corpus has relevant pages.

## Totals

Reported totals are **true match counts**, not a relevance-ranked tail: paging reaches exactly the reported total, and the last page holds the expected remainder. A total may therefore be quoted as a count, and `--sort date_asc` is safe on any query.

Facet counts are the exception: they sum to *more* than the total, because a volume can belong to several collections at once.

## Rate limiting

Lantern's `robots.txt` states `crawl-delay: 5` for every user agent, and that is where this client's default pacing comes from — it is the site's published wish rather than a guess. Requests are spaced by a **cross-process** limiter, so several concurrent CLI invocations still share one budget.

Override with `LANTERN_MIN_REQUEST_INTERVAL` (seconds). Lowering it is asking for trouble on a free service that no one is being paid to run.

## Caching

OCR downloads only — never search results. Under `$XDG_CACHE_HOME/lantern-mcp`, overridable with `--cache-dir` or `LANTERN_CACHE_DIR`. Volumes are cached whole and gzipped; individual leaves are written out beside them as plain text.

## License

Apache 2.0.