metabook-py

📚 X-ray any book's structure — chapters, paragraphs, sentences, clauses, words — as clean JSON. REST + MCP, Project Gutenberg search or your own EPUB. No book text ever leaves the API.

API docs · MCP server · Desktop example · Workflow

Overview

Metabook is a Book Structure API: give it a title, an ISBN, a Gutenberg ID, or an EPUB file, and it returns the book's structural schema — what kind of book it is and how it's shaped — without ever returning the text itself.

Under the hood it locates the book via Gutendex (or walks your uploaded EPUB's spine), downloads and cleans the text, detects the structural schema, and counts everything at every level.

title / ISBN / Gutenberg ID ──► Gutendex ──► fetch + clean ──┐
                                                             ├──► detect schema ──► counts-only JSON
your .epub ──► Vercel Blob ──► package doc + spine XHTML ────┘

✨ Features

• 🔍 Fuzzy search — find books by title or author via Gutendex, or go straight to an ISBN / Gutenberg ID
• 🧬 Schema detection — classifies each book as scripture, sectioned_book, standard_book, essay_collection, or flat, with a confidence rating
• 🔢 Counts, not content — chapters, paragraphs, sentences, clauses, and words per node; a word node is just its index. No book text is ever included in a response
• 📤 Bring your own EPUB — POST /api/books/upload stores the file in Vercel Blob and analyses it with the same pipeline
• 🔌 Two interfaces, one service layer — a FastAPI REST API and a FastMCP server share the same core
• 🖥️ Native desktop client — a GPUI example app with an animated structure tree and a synced JSON code editor

Detail levels

The detail parameter controls how deep the returned tree nests beneath each paragraph:

🚀 Quick start

make setup              # install dependencies (uv sync)
make dev                # run the API with auto-reload on :8000
make test               # run the test suite
make docker-up          # or run it via docker compose

Then open the interactive docs at http://127.0.0.1:8000/api/docs, or try:

curl "http://127.0.0.1:8000/api/books/structure?title=Pride+and+Prejudice&detail=sentence"

EPUB uploads

Uploads need a Vercel Blob read-write token in the environment (or .env / .env.local):

export BLOB_READ_WRITE_TOKEN=vercel_blob_rw_...

If the project is linked to Vercel, vercel env pull writes the token to .env.local (gitignored), which the app loads automatically — values there override .env.

🌐 REST API

Interactive OpenAPI docs live at /api/docs.

🤖 MCP server

A FastMCP server is mounted at /mcp, so agents can use the same service layer through three tools:

🖥️ Desktop example (GPUI)

example/ is a native macOS client built with GPUI and gpui-component: fuzzy search or EPUB upload, an animated lazily-materialised structure tree, and a read-only JSON code editor (tree-sitter highlighting, folding) that scrolls to and highlights whichever node you select in the tree. Light and dark themes, spring animations, routed form transitions.

More screenshots

Search results	Dark mode

Run it (API first, then the app):

make dev

cd example && cargo run

See example/README.md for the Metabook.app bundle (with app icon) and METABOOK_API configuration.

🌳 Branching and release

CI/release pipeline scaffolded from exegia/corpora-py: same branch model, GitHub Actions workflows, composite actions, and make-driven release automation.

See .github/WORKFLOW.md for the full branch model, versioning rules, and workflow reference. Quick summary:

<type>/<slug> --PR--> dev --(daily/manual)--> next --cut--> release/vX.Y.Z --draft PR--> main
                 (deleted on merge)         (preview)                       (deleted on release)

Common commands

make help                # list all targets
make ci                  # everything CI runs on a PR (lint + test)
make pack                # build the publishable wheel
make rulesets-diff       # rulesets GitHub currently has
make rulesets-apply      # push .github/rulesets/*.json

Bootstrap

There are no dev / next branches until the first wrapup. Run the Release workflow manually (Actions → Release → Run workflow), or locally:

make bootstrap-lanes

📄 License

MIT © Emmanuel De Freitas