# shelf-mcp

A personal library MCP server for books, movies, TV shows and games. Runs as a
remote MCP server so the same library is reachable from Claude on desktop and
mobile, and adds items from a photo of a shelf.

Runs entirely on free tiers: **Prefect Horizon** for hosting and OAuth, **Neon**
for Postgres, **Open Library** and **Google Books** for metadata.

## How the photo scan works

There is no OCR or vision service in this server, on purpose. When you attach a
shelf photo in the Claude app, the model reads the spines itself and calls
`stage_scan` with structured candidates. The server resolves each against Open
Library and Google Books, checks for duplicates by ISBN and title similarity,
scores its confidence, and returns the batch for review. Nothing enters the
library until you approve it and `confirm_import` runs.

That staging step is not ceremony. Spine reading fails in predictable ways —
vertical text, occluded spines, publisher logos read as authors — and the
resolver corrects most of it, but not all.

## Layout

```
server.py            MCP tools. Thin wrappers, no logic.
shelf/
  config.py          Environment settings
  db.py              asyncpg pool (PgBouncer-safe)
  models.py          Shared types and input models
  enrich/            Open Library + Google Books, confidence scoring
  repo/              SQL only
  service/           Business logic — the REST API will import this
migrations/          Schema
```

The service layer never imports FastMCP. When the web app arrives it sits beside
`server.py` and calls the same functions.

## Setup

Requires Python 3.11+.

```bash
git clone <your-repo> && cd shelf-mcp
pip install -e .

# Neon console -> Connect -> Pooled connection string
export DATABASE_URL="postgresql://...-pooler.../neondb?sslmode=require"

psql "$DATABASE_URL" -f migrations/001_generalize_schema.sql
fastmcp inspect server.py:mcp      # shows what Horizon will see
python server.py                   # local stdio run
```

## Deploying to Horizon

1. Push to GitHub.
2. At [horizon.prefect.io](https://horizon.prefect.io), sign in with GitHub and
   pick the repo.
3. Entrypoint `server.py:mcp`. Turn **Authentication** on.
4. Add `DATABASE_URL` as a secret.
5. Deploy. Test each tool in the Inspector before connecting anything.
6. In Claude: Settings → Connectors → Add custom connector → paste
   `https://<name>.fastmcp.app/mcp`.

Connectors are account-level, so it appears on your phone with no separate
mobile setup. Pushes to `main` redeploy automatically.

## The data model, briefly

Three ideas do most of the work:

**Ownership and progress are separate.** Ownership belongs to the object
(`owned`, `wishlist`, `lent`, `borrowed`, `sold`, `gone`); progress belongs to
you (`unstarted`, `in_progress`, `finished`, `abandoned`). You can finish a book
and lend it out, and both facts survive.

**Progress is a history.** One row per read-through, watch-through or
playthrough, each with its own dates and rating. Rereading appends rather than
overwriting, so your 2019 opinion is still there. A partial unique index allows
only one `in_progress` record per item.

**Copies are separate from items.** One canonical set of metadata, many things
you own. The paperback and the audiobook of the same book are one item with two
copies.

Kinds and statuses are `text` with `CHECK` constraints rather than Postgres
enums, so adding `boardgame` or `podcast` later is a constraint swap instead of
an `ALTER TYPE` dance.

## Enrichment coverage

Books resolve well. Movies, TV and games do not resolve at all — TMDB and IGDB
both require credentials, and wiring them in would cost this server its
"free, no signup" property. Add them in `shelf/enrich/` behind an optional key
when you want them; nothing else has to change.

## Backups

Neon's free plan keeps a 6-hour restore window and has no scheduled backups.
This is your canonical data, so dump it somewhere periodically:

```bash
pg_dump "$DATABASE_URL" --no-owner --no-acl -Fc -f "shelf-$(date +%F).dump"
```

## Not done yet

- Movies, TV and games work as data but have no enrichment.
- No REST API yet; the service layer is shaped for one.
- Covers are stored as URLs pointing at Open Library and Google, not copied.