Source Library

Official13 toolsLive

by Embassy-of-the-Free-Mind · TypeScript

Search 15K rare pre-modern texts translated to English: philosophy, religion, science, literature.

io.github.Embassy-of-the-Free-Mind/sourcelibrary MCP Server

This MCP server provides access to “Source Library,” a digital library containing 15K rare pre-modern texts translated to English, spanning philosophy, religion, science, and literature. It is described as using AI-aided OCR plus translation and scholarly curation, with an emphasis on primary historical sources.

🛠️ Key Features

Search 15K rare pre-modern texts
English translations of pre-modern materials
AI-aided OCR for source text processing
Scholarly curation of historical primary sources
Tool availability: 13 tools

🚀 Use Cases

Searching translated pre-modern philosophy, religion, science, and literature texts
Supporting digital humanities workflows (OCR, translation, curation)
Working with digitized manuscripts and historical references

⚡ Developer Benefits

Topics indicate support for OCR, translation, open-access, and digital-humanities use
Tech/context includes Next.js and MongoDB-Atlas
Multiple tools available (13)

⚠️ Limitations

Only capabilities explicitly described (search, OCR, translation, curation) are supported; no additional functions are stated beyond 13 tools

Topics

alchemyancient-textsdigital-humanitiesmanuscriptsnextjsocropen-accessrenaissancetranslationhermetica

Captured live from the server via tools/list.

search_library

RETURNS A LIST OF BOOKS (works on a topic) — NOT passages. PICK THIS to discover which works exist on a subject. → For quotable text use search_translations (exact words) or search_concept (by meaning); if the user already named an author/work, call get_book directly (or list_books to find the ID) — the AI summary + chapter outline is usually the right first answer. Searches titles, authors, subjects, and (as a secondary signal) translated text. Query tips: single distinctive words or short phrases work best ("memory palace", "ouroboros"); quoted phrases match exactly. Each result includes total_matches (full count) + returned (this page) + offset for pagination.

Parameters8

query	string	required	Search query — prefer single distinctive concepts ("alchemy", "tree of life") over long natural-language phrases. Wrap in "double quotes" for exact phrase.
language	string	optional	Filter by original language (e.g., Latin, German, Greek)
year_from	number	optional	Publication year range start
year_to	number	optional	Publication year range end
has_translation	boolean	optional	Only return books with translations
sort	string	optional
limit	number	optional	Max results per page (default 10, max 100)
offset	number	optional	Pagination offset (use with limit to page through total_matches; default 0)

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Search query — prefer single distinctive concepts (\"alchemy\", \"tree of life\") over long natural-language phrases. Wrap in \"double quotes\" for exact phrase."
    },
    "language": {
      "type": "string",
      "description": "Filter by original language (e.g., Latin, German, Greek)"
    },
    "year_from": {
      "type": "number",
      "description": "Publication year range start"
    },
    "year_to": {
      "type": "number",
      "description": "Publication year range end"
    },
    "has_translation": {
      "type": "boolean",
      "description": "Only return books with translations"
    },
    "sort": {
      "type": "string",
      "enum": [
        "relevance",
        "date_asc",
        "date_desc",
        "title"
      ]
    },
    "limit": {
      "type": "number",
      "description": "Max results per page (default 10, max 100)"
    },
    "offset": {
      "type": "number",
      "description": "Pagination offset (use with limit to page through total_matches; default 0)"
    }
  },
  "required": [
    "query"
  ]
}

search_translations

RETURNS QUOTABLE PASSAGES (page-level snippets + citation URLs), matched by KEYWORD/term. PICK THIS to find a quote or textual evidence on a topic across the whole library. → If the modern word won't literally appear in historical texts, use search_concept (matches by meaning); to list which BOOKS cover a topic use search_library; to dig inside one known book use search_within_book; if the user named an author/work, get_book first (its AI summary is usually the right first read). Query tips: single distinctive terms ("memory palace", "wax tablet") work best; multi-word natural-English queries ("unity of the intellect") may return fewer results because matching is term-based, not phrase-based. Each snippet has a snippet_type — "translation"/"ocr" means it is a verbatim extract from the source text; "summary" means it is AI-generated description (do not quote those as the author's words). Response includes total_matches, returned, and offset for pagination. Cross-cultural tip: for pre-modern or non-Western topics, search source-tradition vocabulary rather than modern English terms — e.g. for seminal economy search "jing" or "bindu" or "istimnāʾ", not "semen retention"; for female homoeroticism search "tribade" or "sahq", not "lesbian". The corpus is indexed via period translations that use tradition-internal terminology.

Parameters9

query	string	required	Search term — prefer single distinctive concepts ("harmony of the spheres", "active intellect") over long natural-language phrases. Multi-word queries match all terms (not phrase); wrap in "double quotes" for exact phrase.
language	string	optional	Filter by a single original language
languages	array	optional	Filter to any of these languages, e.g. ["Sanskrit", "Arabic", "Chinese"]. Use instead of language when targeting multiple traditions.
exclude_languages	array	optional	Exclude these languages, e.g. ["Latin", "French", "German", "English"] to surface non-Western sources.
year_from	number	optional
year_to	number	optional
book_id	string	optional	Search within a specific book
limit	number	optional	Max results per page (default 20, max 50)
offset	number	optional	Pagination offset (use with limit to page through total_matches; default 0)

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Search term — prefer single distinctive concepts (\"harmony of the spheres\", \"active intellect\") over long natural-language phrases. Multi-word queries match all terms (not phrase); wrap in \"double quotes\" for exact phrase."
    },
    "language": {
      "type": "string",
      "description": "Filter by a single original language"
    },
    "languages": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Filter to any of these languages, e.g. [\"Sanskrit\", \"Arabic\", \"Chinese\"]. Use instead of language when targeting multiple traditions."
    },
    "exclude_languages": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Exclude these languages, e.g. [\"Latin\", \"French\", \"German\", \"English\"] to surface non-Western sources."
    },
    "year_from": {
      "type": "number"
    },
    "year_to": {
      "type": "number"
    },
    "book_id": {
      "type": "string",
      "description": "Search within a specific book"
    },
    "limit": {
      "type": "number",
      "description": "Max results per page (default 20, max 50)"
    },
    "offset": {
      "type": "number",
      "description": "Pagination offset (use with limit to page through total_matches; default 0)"
    }
  },
  "required": [
    "query"
  ]
}

search_concept

RETURNS QUOTABLE PASSAGES matched by MEANING (cosine similarity on Gemini embeddings, 768d) — paraphrases and adjacent phrasings match even with zero keyword overlap. PICK THIS when the modern term won't literally appear in historical texts — e.g. "distributed cognition" maps to passages about active intellect, art of memory, wax tablet metaphors; "social contract" maps to pre-Hobbesian discussions of consent and authority. → For exact words/distinctive terms use search_translations (cheaper, more precise); to list which BOOKS cover a topic use search_library; if the user named an author/work, get_book first (semantic search is expensive — reserve it for cross-corpus discovery). Similarity calibration: 0.70+ is a strong match, 0.55–0.70 is worth reading but verify, below 0.55 is mostly conceptual drift. Set max_per_book to diversify results across many books rather than cluster on one source. Each passage carries a snippet_type — quote only "translation" snippets, never "summary". Cross-cultural tip: for pre-modern or non-Western topics, also try source-tradition vocabulary — e.g. for seminal economy try "jing preservation" or "bindu yoga" or "istimnāʾ"; for masturbation try "mollities" (Latin) or "hastamaithuna" (Sanskrit) or "shouyin" (Chinese). The corpus is indexed via period translations that use tradition-internal terminology, so adjacent/euphemistic terms often surface material that modern English keywords miss.

Parameters8

query	string	required	A concept or natural-language description — full sentences are fine (e.g. "tools that extend the mind beyond the body"). Unlike search_translations, this does NOT require words that appear in the corpus.
language	string	optional	Filter by a single original language
languages	array	optional	Filter to any of these languages, e.g. ["Sanskrit", "Arabic", "Chinese"]. Use instead of language when targeting multiple traditions.
exclude_languages	array	optional	Exclude these languages, e.g. ["Latin", "French", "German", "English"] to surface non-Western sources.
year_from	number	optional	Restrict to books published in or after this year (filters out modern editions and translations).
year_to	number	optional	Restrict to books published in or before this year.
max_per_book	number	optional	Cap on passages from any single book. Useful when one book dominates the conceptual neighborhood; set to 1–2 for diverse author/work coverage.
limit	number	optional	Max passages (default 15, max 50)

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "A concept or natural-language description — full sentences are fine (e.g. \"tools that extend the mind beyond the body\"). Unlike search_translations, this does NOT require words that appear in the corpus."
    },
    "language": {
      "type": "string",
      "description": "Filter by a single original language"
    },
    "languages": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Filter to any of these languages, e.g. [\"Sanskrit\", \"Arabic\", \"Chinese\"]. Use instead of language when targeting multiple traditions."
    },
    "exclude_languages": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Exclude these languages, e.g. [\"Latin\", \"French\", \"German\", \"English\"] to surface non-Western sources."
    },
    "year_from": {
      "type": "number",
      "description": "Restrict to books published in or after this year (filters out modern editions and translations)."
    },
    "year_to": {
      "type": "number",
      "description": "Restrict to books published in or before this year."
    },
    "max_per_book": {
      "type": "number",
      "description": "Cap on passages from any single book. Useful when one book dominates the conceptual neighborhood; set to 1–2 for diverse author/work coverage."
    },
    "limit": {
      "type": "number",
      "description": "Max passages (default 15, max 50)"
    }
  },
  "required": [
    "query"
  ]
}

search_within_book

SEARCHES INSIDE ONE BOOK (requires book_id) — runs keyword AND scoped semantic search in parallel over that book's pages and merges them, so it handles both literal terms ("ouroboros") and conceptual queries ("the marriage of opposites"). PICK THIS once you have a candidate book and want every relevant page in it. → To find the book first, use search_library or search_concept (then pass its book_id here). Faster than a global re-search because it's scoped to one book's 100-500 pages. Returns OCR and translation snippets with page numbers, ready to cite.

Parameters2

book_id	string	required	The book ID to search within
query	string	required	Search query

Raw schema

{
  "type": "object",
  "properties": {
    "book_id": {
      "type": "string",
      "description": "The book ID to search within"
    },
    "query": {
      "type": "string",
      "description": "Search query"
    }
  },
  "required": [
    "book_id",
    "query"
  ]
}

list_books

BROWSES/FILTERS THE CATALOG by metadata (author/title fragment, language, category, translation recency) — no content/topic matching. PICK THIS to see WHAT EXISTS by an author or in a tradition. Returns books with title, author, language, year, and translation progress. → For a relevance-ranked topic search use search_library; for passages on a theme use search_translations (exact words) or search_concept (by meaning).

Parameters5

search	string	optional	Filter by title or author
language	string	optional
category	string	optional
sort	string	optional
limit	number	optional	Max results (default 100, max 200)

Raw schema

{
  "type": "object",
  "properties": {
    "search": {
      "type": "string",
      "description": "Filter by title or author"
    },
    "language": {
      "type": "string"
    },
    "category": {
      "type": "string"
    },
    "sort": {
      "type": "string",
      "enum": [
        "recent-translation",
        "recent",
        "title-asc",
        "title-desc"
      ]
    },
    "limit": {
      "type": "number",
      "description": "Max results (default 100, max 200)"
    }
  }
}

get_book

READ PIPELINE step 1 — DISCOVER. START HERE for any named work or author. Returns the book's AI-generated summary, chapter list, edition metadata, DOI, page counts, and IIIF manifest. The summary is typically a multi-paragraph orientation covering the book's argument, structure, and significance — often answering the question without further searching. Then: get_book_text to read a chapter or page range (step 2), get_quote / get_quotes to lock specific pages with full citation apparatus (step 3). search_within_book locates passages inside this book.

Parameters1

book_id

string

required

The book ID

Raw schema

{
  "type": "object",
  "properties": {
    "book_id": {
      "type": "string",
      "description": "The book ID"
    }
  },
  "required": [
    "book_id"
  ]
}

get_book_text

READ PIPELINE step 2 — READ. Read a book's text. Call get_book first (step 1) for the chapter list, then come here. Preferred: use the chapter param to read one chapter at a time (includes [Page N] markers for citation). Alternatively, use from/to for explicit page ranges (e.g. from=1 to=50). When you find passages worth quoting, hand the page numbers to get_quote / get_quotes (step 3) for verbatim text + a citation link. TRUNCATION: the response always includes truncated: true/false. When truncated=true, the truncation_note field gives the exact next from/to values to call — this means content was cut short by a page-budget limit, NOT that the book ended. An AI agent MUST NOT infer end-of-book from pages_returned alone; check truncated first. Budget limits apply to anonymous callers (~50 pages per 24h); sign in at sourcelibrary.org/auth/signin or get an API key at sourcelibrary.org/developers for higher limits.

Parameters7

book_id	string	required	The book ID
chapter	number	optional	Chapter index (0-based). Preferred over from/to — returns pre-structured chapter text with embedded [Page N] markers.
part	number	optional	Part number (1-based) for large chapters split into multiple parts
content	string	optional	Which text to include: ocr (original language), translation (English), or both (default)
from	number	optional	Start page number (inclusive). Use with to for explicit page ranges.
to	number	optional	End page number (inclusive). Recommended chunk size: 50 pages. If the response has truncated=true, use the next from/to from truncation_note.
format	string	optional	json (default, structured with per-page fields) or plain (concatenated text with page markers)

Raw schema

{
  "type": "object",
  "properties": {
    "book_id": {
      "type": "string",
      "description": "The book ID"
    },
    "chapter": {
      "type": "number",
      "description": "Chapter index (0-based). Preferred over from/to — returns pre-structured chapter text with embedded [Page N] markers."
    },
    "part": {
      "type": "number",
      "description": "Part number (1-based) for large chapters split into multiple parts"
    },
    "content": {
      "type": "string",
      "enum": [
        "ocr",
        "translation",
        "both"
      ],
      "description": "Which text to include: ocr (original language), translation (English), or both (default)"
    },
    "from": {
      "type": "number",
      "description": "Start page number (inclusive). Use with to for explicit page ranges."
    },
    "to": {
      "type": "number",
      "description": "End page number (inclusive). Recommended chunk size: 50 pages. If the response has truncated=true, use the next from/to from truncation_note."
    },
    "format": {
      "type": "string",
      "enum": [
        "json",
        "plain"
      ],
      "description": "json (default, structured with per-page fields) or plain (concatenated text with page markers)"
    }
  },
  "required": [
    "book_id"
  ]
}

get_quote

READ PIPELINE step 3 — CITE. Get the exact verbatim text of a single page plus its citation apparatus. ALWAYS use before putting text in quotation marks. The response headline is citation_link (the stable sourcelibrary.org/q/… shortlink) — present it to the user alongside the quote. Render as: > [exact translation text, verbatim] > — [Author], p. [N]. [citation_link] For several pages of one book at once, use get_quotes.

Parameters2

book_id	string	required	The book ID
page	number	required	Page number

Raw schema

{
  "type": "object",
  "properties": {
    "book_id": {
      "type": "string",
      "description": "The book ID"
    },
    "page": {
      "type": "number",
      "description": "Page number"
    }
  },
  "required": [
    "book_id",
    "page"
  ]
}

get_quotes

READ PIPELINE step 3 — CITE, in batch. Get verbatim text + citation_link for SEVERAL pages of a single book in one round-trip, to assemble a multi-passage dossier. Specify either pages (an explicit array, e.g. [12, 40, 41]) or an inclusive from/to range. Max 25 pages per call. Each entry carries its own citation_link to present alongside the quote.

Parameters4

book_id	string	required	The book ID
pages	array	optional	Explicit list of page numbers (e.g. [12, 40, 41]). Use this OR from/to.
from	number	optional	Start page (inclusive) of a range. Use with to.
to	number	optional	End page (inclusive) of a range. Use with from.

Raw schema

{
  "type": "object",
  "properties": {
    "book_id": {
      "type": "string",
      "description": "The book ID"
    },
    "pages": {
      "type": "array",
      "items": {
        "type": "number"
      },
      "description": "Explicit list of page numbers (e.g. [12, 40, 41]). Use this OR from/to."
    },
    "from": {
      "type": "number",
      "description": "Start page (inclusive) of a range. Use with to."
    },
    "to": {
      "type": "number",
      "description": "End page (inclusive) of a range. Use with from."
    }
  },
  "required": [
    "book_id"
  ]
}

search_images

Search 110,000+ historical illustrations, emblems, engravings, diagrams, AND 23,000+ artworks (paintings, prints, sculptures). Filter by type, subject, figure, symbol, year.

Parameters9

query	string	optional	Text search (e.g., "ouroboros", "tree of life")
type	string	optional	Image type (woodcut, engraving, emblem, diagram)
subject	string	optional
figure	string	optional
symbol	string	optional
year_from	number	optional
year_to	number	optional
book_id	string	optional
limit	number	optional	Max results (default 20, max 50)

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Text search (e.g., \"ouroboros\", \"tree of life\")"
    },
    "type": {
      "type": "string",
      "description": "Image type (woodcut, engraving, emblem, diagram)"
    },
    "subject": {
      "type": "string"
    },
    "figure": {
      "type": "string"
    },
    "symbol": {
      "type": "string"
    },
    "year_from": {
      "type": "number"
    },
    "year_to": {
      "type": "number"
    },
    "book_id": {
      "type": "string"
    },
    "limit": {
      "type": "number",
      "description": "Max results (default 20, max 50)"
    }
  }
}

submit_feedback

Submit feedback, bug reports, or feature requests to the Source Library team.

Parameters3

message	string	required	Your feedback (2-5000 chars)
name	string	optional
email	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "Your feedback (2-5000 chars)"
    },
    "name": {
      "type": "string"
    },
    "email": {
      "type": "string"
    }
  },
  "required": [
    "message"
  ]
}

share_findings

Share a research dossier back to the Source Library team — a title, an optional summary, and an ordered list of citations (the passages your thesis rests on). Each citation is a reference { book_id, page, note }, NOT copied text: the library re-renders the canonical quote from the reference, so links stay authoritative. Use this when the user has assembled a thesis backed by passages across one or more books and wants to contribute it back. Like submit_feedback, this goes to the team for review (not an instant public page).

Parameters5

title	string	required	Title of the dossier / thesis (2-300 chars)
summary	string	optional	Optional prose summarizing the argument (max 5000 chars)
citations	array	required	Ordered list of supporting passages (1-50). Get book_id + page from get_quote / search_translations.
name	string	optional
email	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Title of the dossier / thesis (2-300 chars)"
    },
    "summary": {
      "type": "string",
      "description": "Optional prose summarizing the argument (max 5000 chars)"
    },
    "citations": {
      "type": "array",
      "description": "Ordered list of supporting passages (1-50). Get book_id + page from get_quote / search_translations.",
      "items": {
        "type": "object",
        "properties": {
          "book_id": {
            "type": "string",
            "description": "The book ID"
          },
          "page": {
            "type": "number",
            "description": "Page number"
          },
          "note": {
            "type": "string",
            "description": "Optional note on why this passage matters"
          }
        },
        "required": [
          "book_id",
          "page"
        ]
      }
    },
    "name": {
      "type": "string"
    },
    "email": {
      "type": "string"
    }
  },
  "required": [
    "title",
    "citations"
  ]
}

propose_collection

Propose a themed collection of books to the Source Library team — a title, a rationale (why these books belong together and what thread connects them), and an ordered list of book ids. Get book ids from search_library / list_books / get_book. Like submit_feedback and share_findings, this goes to the team for REVIEW — it does NOT create a public collection instantly; a curator reviews and approves it. Use this when the user has identified a coherent set of books worth grouping and wants to contribute that curation back.

Parameters6

title	string	required	Title of the proposed collection (2-200 chars)
rationale	string	required	Why these books belong together and what connects them (max 5000 chars)
book_ids	array	required	Ordered list of book ids to include (1-200). Get ids from search_library / list_books / get_book.
suggested_slug	string	optional	Optional URL slug suggestion, e.g. "renaissance-astronomy"
name	string	optional
email	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Title of the proposed collection (2-200 chars)"
    },
    "rationale": {
      "type": "string",
      "description": "Why these books belong together and what connects them (max 5000 chars)"
    },
    "book_ids": {
      "type": "array",
      "description": "Ordered list of book ids to include (1-200). Get ids from search_library / list_books / get_book.",
      "items": {
        "type": "string",
        "description": "A book id"
      }
    },
    "suggested_slug": {
      "type": "string",
      "description": "Optional URL slug suggestion, e.g. \"renaissance-astronomy\""
    },
    "name": {
      "type": "string"
    },
    "email": {
      "type": "string"
    }
  },
  "required": [
    "title",
    "rationale",
    "book_ids"
  ]
}

README.md23 KBView on GitHub

Source Library

A digital library of historical primary sources with AI-aided OCR, translation, and scholarly curation.

🌐 Visit Library • 📖 Docs • 🗺️ System Map • 🤝 Contribute

🎬 Experience Source Library

Your browser does not support the video tag.

Explore thousands of digitized historical texts with AI-enhanced translations and scholarly curation.

🎯 About Source Library

Source Library is an open digital library dedicated to making early printed books and primary sources readable and citable. We specialize in alchemy, Hermetica, Kabbalah, Rosicrucianism, and early modern science—texts that bridge historical scholarship with contemporary exploration.

🌟 Why Source Library?

✨ Originals First — Read the original language text with AI-enhanced translations alongside
🎓 Citable Scholarship — Every book gets a DOI and scholarly metadata (USTC alignment, edition tracking)
🏛️ Partner Subdomains — Institutions like the Bibliotheca Philosophica Hermetica curate reading rooms on their own domains
🔍 Discovery — Collections, galleries of illustrations, and semantic search surface overlooked texts
✅ Rigorous QA — Manual verification, image quality scoring, and OCR validation before publication

The platform ingests ~15K pages monthly from Internet Archive, Gallica, Bodleian, Wellcome, and other digital heritage partners.

🚀 Quick Start

💻 Development Environment

bash

# 🍴 Clone and install
git clone https://github.com/Embassy-of-the-Free-Mind/sourcelibrary-v2.git
cd sourcelibrary-v2
npm install

# ⚙️ Configure environment (see .env.example for required variables)
# Must include: MongoDB Atlas connection, Google Gemini API key, Vercel Blob token

# ▶️ Start dev server
npm run dev

Open http://localhost:3000

📋 Tech Stack

🎨 Frontend	Next.js 16, React 19, TailwindCSS, Lucide icons
⚙️ Backend	Next.js API routes, AWS Lambda for async processing
💾 Database	MongoDB Atlas (primary), Supabase (embeddings)
🤖 AI/ML	Google Gemini 3.1 (OCR, translation, summarization)
🗂️ Storage	Vercel Blob (images), AWS S3 (archive), Cloudflare R2 (archive)
🔐 Auth	NextAuth v5 with MongoDB adapter
🚀 DevOps	Vercel (hosting), GitHub (VCS), Playwright (E2E tests)
✔️ Testing	Vitest (unit/integration), Playwright (E2E)
🔎 Search	PostgreSQL FTS + semantic search via Supabase

📦 Key Dependencies:

sharp — Image resizing and cropping
@google/generative-ai — Gemini API integration
xml2js — USTC metadata parsing
@modelcontextprotocol/sdk — MCP server for agent integration
stripe — Donation and subscription handling

📚 Core Features

⚡ Page pagination — Instant navigation between 100+ pages
🔍 Full-text search — Query across OCR'd text and translations
📌 Quote generation — Copy and cite passages with DOI links

🔄 Processing Pipeline

🧩 Smart split detection — Automatic gutter detection for two-page spreads (Gemini AI or ML-based)
✍️ High-accuracy OCR — Gemini Vision API with language-specific models (Latin, German, Greek, Arabic, etc.)
🗣️ Context-aware translation — Maintains continuity across pages for scholarly accuracy
🖼️ Gallery extraction — AI-powered detection and cataloging of illustrations

🎨 Curation & Discovery

📑 Themed collections — Editorial collections (e.g., "Alchemy & Transmutation," "Kabbalah & Mysticism")
🏛️ Gallery browsing — Curated images from all books (museum-quality metadata)
📚 Related editions — Link across translations, reprints, and derivative works
🔗 Authority linking — Connect to USTC, VIAF, and other scholarly databases

📤 Scholarly Export

📱 EPUB generation — Multi-format ebook export
📄 PDF with annotations — Preserve layout, add scholarly notes
🆔 DOI minting — Version books via Zenodo integration for long-term citation

🏢 Tenant Subdomains

🏛️ Isolated reading rooms — Partners host curated subsets on custom domains (e.g., bph.sourcelibrary.org)
🎨 Branding & navigation — Full UI customization per tenant
🔒 Access control — Public or members-only collections

🏗️ Architecture Overview

📊 Data Model

📚 Books contain structured metadata:

🏛️ Bibliographic — Title, author, language, publication date, USTC ID
🖼️ Images — Links to source (Internet Archive, Gallica, etc.), archival status
⚙️ Processing — OCR status, translation language, extraction metadata
🎨 Curation — Collections, tier (featured/standard), visibility flags

📄 Pages store individual page data:

📸 Original image — Source photo or PDF page
✂️ Split coordinates — Crop boundaries (0-1000 scale) for two-page spreads
✍️ OCR output — Raw Gemini extraction + language metadata
🗣️ Translation — English translation with scholarly notes
🖼️ Illustrations — Detected images with quality scores and descriptions

🖼️ Gallery images are extracted illustrations:

🏷️ Metadata — Subject, figures, symbols, style, techniques, period
⭐ Quality score — 0–1.0 rating (filters below 0.5)
🔗 Provenance — Source book and page, linked back

🎨 Image Tier System

All page images are resized on-demand via /api/image:

Tier	Dimensions	Quality	📱 Use Case
Thumbnail	400px wide	70% JPEG	Grids, navigation, social sharing
Display	1200px wide	80% JPEG	Main reading view, comfortable for annotation
Full	2400px wide	90% JPEG	Magnifier, fullscreen detail, printing

Split pages are cropped non-destructively via coordinates; original images are always preserved.

🔄 Processing Pipeline

code

📥 Import → ✂️ Split Detection → ✍️ OCR → 🗣️ Translation → 🎨 Enrichment → 🌍 Publishing

📥 Import — Upload images, import from IA/Gallica via IIIF, or paste URLs
✂️ Split Detection — Detect two-page spreads; mark crop boundaries
✍️ OCR — Gemini Vision extracts text per page language
🗣️ Translation — Gemini translates to English with prior-page context for continuity
🎨 Enrichment — Extract illustrations, generate summaries, assign collections
🌍 Publishing — Set visible: true, mint DOI, push to search index

Batch endpoints process up to 5 pages/request using Gemini Batch API (50% cheaper).

🔌 API Routes (Key)

Base URL: https://sourcelibrary.org (production) or http://localhost:3000 (local dev with .env.local configured).

Common 404 mistake: paths like /api/bph/books or /api/bph/books/[id] do not exist. BPH catalogue APIs live under /api/embed/bph/.... There is also no top-level /api/[tenant]/books route — tenant book listings use /api/books/library or the embed routes below.

Public read APIs (no auth required today)

Endpoint	Method	Purpose
`/api/search?q=<query>`	GET	Full-text search across books and page translations
`/api/books?limit=100&offset=0`	GET	Simple book list (global catalogue; `visible: true`, indexed only)
`/api/books/library?limit=100&skip=0`	GET	Rich browse API — search, sort, filters, collections
`/api/books/[id]`	GET	Book metadata (accepts Mongo `id` or `slug`)
`/api/books/[id]/quote?page=<n>`	GET	Citable quote + formatted citations (inline, footnote, BibTeX, DOI)
`/api/gallery?limit=24`	GET	Illustration / artwork search
`/api/image?url=<encoded-url>&w=400`	GET	On-demand image resize & crop
`/api/embed/bph/books?limit=24`	GET	BPH catalogue (paginated, searchable)
`/api/embed/bph/books/[slug]`	GET	Single BPH book detail
`/api/embed/bph/featured`	GET	Featured BPH books
`/api/embed/bph/collections`	GET	BPH collection list
`/api/embed/bph/languages`	GET	BPH language facets
`/api/embed/bph/suggest?q=alch`	GET	BPH search autocomplete
`/api/embed/bph/stats`	GET	BPH catalogue stats

Tenant-scoped listing (not `/api/bph/...`)

Use one of these patterns to filter by partner tenant (e.g. BPH):

Approach	Example
Embed prefix (recommended for BPH)	`GET /api/embed/bph/books?limit=24`
Library API + query param	`GET /api/books/library?tenant_slug=bph&limit=24`
Host header (subdomain)	Call `https://bph.sourcelibrary.org/api/books/library?limit=24` — the proxy injects tenant context
Manual header (advanced)	`curl -H "x-tenant-slug: bph" https://sourcelibrary.org/api/books/library?limit=24`

The /api/[tenant]/books/[id]/... paths that exist in the codebase are editor/processing routes (batch OCR, index rebuild, etc.) — not public catalogue listings.

Authenticated / internal APIs

These require a signed-in session cookie, editor role, or (for some dataset endpoints) a Bearer API key. Calling them without auth returns 401 or 403.

Endpoint	Method	Purpose
`/api/books`	POST	Create a new book (editor)
`/api/books/[id]`	PATCH	Update book metadata (curator+)
`/api/books/[id]/batch-ocr-async`	POST	Queue batch OCR job
`/api/books/[id]/batch-translate-async`	POST	Queue batch translation job
`/api/pages/[id]`	PATCH	Update page OCR/translation
`/api/jobs/[id]/process`	POST	Async job processor (Lambda)

Full narrative API walkthrough: docs/blog-source-library-api.md. MCP tools (search, quote, read): mcp-server/README.md.

🧪 Trying the API (curl, Postman, browser)

All examples below hit production and need no API key. Replace the base URL with http://localhost:3000 when running locally (MongoDB + env vars required).

curl

bash

# Search translated text
curl -s "https://sourcelibrary.org/api/search?q=quintessence&limit=5" | jq .

# List books (global catalogue)
curl -s "https://sourcelibrary.org/api/books?limit=5" | jq .

# Browse with filters and sort
curl -s "https://sourcelibrary.org/api/books/library?limit=5&sort=recent-translation&has_translation=true" | jq .

# BPH catalogue — note /api/embed/bph/, NOT /api/bph/
curl -s "https://sourcelibrary.org/api/embed/bph/books?limit=5&translated=true" | jq .

# BPH via tenant_slug on the library endpoint
curl -s "https://sourcelibrary.org/api/books/library?tenant_slug=bph&limit=5" | jq .

# Book metadata (id or slug)
curl -s "https://sourcelibrary.org/api/books/know-thyself-reger-von-ehrenhart" | jq .

# Citable quote for a page
curl -s "https://sourcelibrary.org/api/books/6836f8ee811c8ab472a49e36/quote?page=57" | jq .

# Gallery search
curl -s "https://sourcelibrary.org/api/gallery?subject=alchemy&limit=5" | jq .

Pretty-printing with jq is optional; omit | jq . to see raw JSON.

Postman

Create a new GET request.
Set URL to e.g. https://sourcelibrary.org/api/embed/bph/books
On the Params tab add query keys: limit = 24, sort = title, translated = true
Leave Auth as No Auth for the public endpoints above.
Send — expect 200 with JSON body.

Get Books

Browser

Public GET endpoints can be opened directly:

📁 Directory Structure

code

src/
├── app/                         # 🎨 Next.js App Router
│   ├── book/[id]/               # 📖 Book detail, reading, processing
│   │   ├── page.tsx             # Main book hub
│   │   ├── split/page.tsx       # Split detection workflow
│   │   └── page/[pageId]/page.tsx      # Individual page view
│   ├── api/                     # 🔌 All API routes
│   │   ├── books/               # Book CRUD & batch ops
│   │   ├── pages/               # Page processing
│   │   ├── image/               # Image proxy & cropping
│   │   ├── jobs/                # Async job tracking
│   │   └── search/              # Full-text & semantic
│   ├── [tenant]/                # 🏢 Tenant subdomain routes
│   ├── gallery/                 # 🖼️ Illustration browsing
│   ├── collections/             # 📑 Collection pages
│   └── admin/                   # ⚙️ Admin dashboard
├── hooks/                       # 🎣 Reusable React hooks
└── lib/                         # 🛠️ Business logic & utilities
    ├── mongodb.ts               # Database operations
    ├── image-extraction.ts      # Illustration detection
    └── auth-helpers.ts          # Authentication utilities

scripts/
├── workers/                     # ⚙️ Lambda worker functions
│   ├── pipeline-orchestrator.mjs # Main processing pipeline
│   ├── image-extract-worker.mjs # Gallery extraction
│   └── ...
├── maintenance/                 # 🔧 One-off maintenance scripts
├── migrations/                  # 📊 Database schema updates
└── audit-bph-leaks.mjs          # 🔒 Tenant security verification

tests/
├── unit/                        # ✔️ Vitest unit tests
└── integration/                 # 🔗 Integration tests

prompts/                        # 🤖 AI system prompts
├── ocr/
├── translation/
├── split-detection/
└── ...

.claude/                        # 🧠 AI agent context
├── docs/                       # 📚 Detailed architecture docs
├── skills/                     # 🎯 Specialized agent skills
└── handoffs/                   # 📋 Incident reports & lessons

🔄 Common Workflows

📥 Importing Books from Internet Archive

typescript

// From the UI or via API
POST /api/books
{
  "ia_id": "thehermetic00fludd",
  "title": "The Hermetic and Alchemical Writings",
  "author": "Arthur Edward Waite",
  "language": "en",
  "ustc_id": "123456"
}

The system:

📥 Fetches page images from IA IIIF
✂️ Detects splits and generates crop coordinates
📤 Queues for OCR and translation
🌍 Publishes when processing completes

✂️ Processing a Split Book

🖥️ Visit /book/[id]/split
🖱️ Adjust split line visually (drag or Gemini AI auto-detection)
✅ Click "Apply Split" — creates two virtual pages with crop coordinates
📸 Original images preserved; OCR runs on cropped versions

✍️ Batch OCR with Gemini Batch API

typescript

POST /api/books/[id]/batch-ocr-async
{
  "page_ids": ["page-1", "page-2", "page-3"],
  "language": "la"
}

Returns a job ID; Gemini processes offline, saves results when complete. 50% cheaper than standard API.

🎓 Generating a Scholarly Edition

typescript

POST /api/books/[id]/editions
{
  "title": "The Emerald Tablet: First Complete English Translation",
  "translator": "Jane Doe",
  "language": "en",
  "format": "epub"
}

System generates:

📝 Scholarly front matter (introduction, translator bio, etc.)
📱 EPUB with TOC and metadata
🆔 DOI via Zenodo integration
📚 Citation metadata (BibTeX, RIS)

🧪 Testing

🚀 Run Tests

bash

# Unit tests
npm run test:unit

# Integration tests
npm run test:integration

# End-to-end tests (Playwright)
npm run test:e2e

# Coverage report
npm run test:coverage

# Watch mode
npm run test:watch

✅ E2E Test Examples

📥 Book import — Validate IA ingestion pipeline
✂️ Split detection — Verify gutter detection accuracy
🌐 Translation — Confirm source/translation alignment
🔒 Tenant subdomain — Ensure content isolation (no leaks)
🔍 Search — Test full-text and semantic indexing

🚀 Deployment

🔄 Staging (Preview)

Every pushed branch auto-deploys to Vercel preview:

bash

git push origin feat/my-feature
# ↓ Vercel builds and deploys
# ↓ Preview URL in GitHub PR

🌍 Production

Merge to main via PR → automatic Vercel deploy to sourcelibrary.org

✅ Pre-deployment checklist:

Tests pass (npm run test)
TypeScript check passes (npx tsc --noEmit)
No hardcoded secrets or credentials
Tenant subdomain leak audit passes (node scripts/audit-bph-leaks.mjs)
PR reviewed and approved

🔑 Environment Variables

Required (.env.local):

code

MONGODB_URI=mongodb+srv://...
NEXTAUTH_SECRET=<random-secret>
GOOGLE_API_KEY=<gemini-key>
VERCEL_BLOB_TOKEN=<vercel-blob-token>
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...

Optional:

code

STRIPE_SECRET_KEY=<for-donations>
ZENODO_TOKEN=<for-doi-minting>
SUPABASE_URL=<for-embeddings>

📖 Documentation

🗺️ System Map — Comprehensive architecture diagram and file index
🏗️ ARCHITECTURE.md — Data model, workflows, and design decisions
🤖 AGENTS.md — Technical context for AI agents and automated workers
📋 CLAUDE.md — Development workflow, PR conventions, critical invariants
🔐 AUTH_IMPLEMENTATION.md — NextAuth setup and tenant auth
📦 Batch OCR Workflow — Using Gemini Batch API
🔌 API Documentation — REST API reference
🖼️ Image Processing — How cropping and resizing works

🤝 Contributing

We welcome contributions! Start with CONTRIBUTING.md — setup, the branch/PR workflow, how deploys work (and the Vercel setup you should NOT do), and the data-safety rules. Deeper doctrine lives in the development workflow. The short version:

🌿 Create a feature branch (off main):

bash

# Using git worktree for multi-session safety
git worktree add .claude/worktrees/feat-xyz feat/xyz
cd .claude/worktrees/feat-xyz

✏️ Make changes and test:

bash

npm run lint
npm run test
npm run test:e2e

📤 Push and create a PR:

bash

git push origin feat/xyz
gh pr create --base main

📋 PR guidelines:
- One concern per PR — Don't bundle refactors with features
- Verify deletions — Always grep -rn before deleting code
- Run type check — npx tsc --noEmit before submitting
- Describe scope — State what's in scope AND out of scope

🎯 What We're Looking For

🐛 Bug fixes with test coverage
✨ Feature implementations aligned with project mission
⚡ Performance improvements with benchmarks
📝 Documentation improvements
♿ UX/accessibility enhancements
🏢 Tenant integration examples

📢 Reporting Issues

🐛 Bugs — Include reproduction steps, expected vs. actual behavior
💡 Feature requests — Explain the use case and user impact
❓ Questions — Open an issue

🛡️ Security & Data Protection

🚫 No deletion without approval — All book/page deletions require explicit confirmation
🔒 Tenant isolation — Tenant subdomains are closed systems (no cross-tenant leaks)
🔐 Secret management — All secrets via environment variables, never hardcoded
⚖️ AGPL licensing — Contributions must respect AGPL-3.0-or-later

See CLAUDE.md Security for detailed security policies.

📊 Current Status

As of July 2026 — these move weekly; live numbers at sourcelibrary.org/data.

📈 Active Corpus:

📚 ~29K books with visible: true
✅ ~15K fully processed (OCR'd and translated)
🌍 ~14K with full English translations
🖼️ 200K+ catalogued illustrations in the gallery

⚙️ Processing Capacity:

📥 15K+ pages/month ingestion
🗣️ Multi-language support (Latin, German, Greek, Arabic, Sanskrit, Chinese, etc.)
💰 Batch API for 50% cost reduction

🏢 Platform Tenants:

🔮 Bibliotheca Philosophica Hermetica — Hermetica & esoterica
⚗️ Kloss Collection — Medical alchemy
🤝 Additional partners in development

📝 License

Source Library is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). All contributions must respect this license.

See LICENSING.md for details on third-party licenses and attribution.

📞 Support & Community

🐛 Found a bug? Open an issue
🤝 Want to collaborate? Contribute
🌐 Visit the site — sourcelibrary.org

📖 Digitizing history. Making primary sources readable. Building open scholarship.

↑ Back to top

code

src/
├── app/              # All routes, pages, and API endpoints
│   ├── api/          # API routes
│   ├── book/         # Book pages (detail, read, pipeline)
│   └── page.tsx      # Homepage
├── components/       # Reusable React components
├── hooks/            # Reusable React hooks for component logic
└── lib/              # Business Logic, Utilities (mongodb, ai, types), and Services

Install

Tools (13)

search_librarysearch_translationssearch_conceptsearch_within_booklist_booksget_bookget_book_textget_quote

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://sourcelibrary.org/api/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "sourcelibrary": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://sourcelibrary.org/api/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

io.github.Embassy-of-the-Free-Mind/sourcelibrary MCP Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

search_library

search_translations

search_concept

search_within_book

list_books

get_book

get_book_text

get_quote

get_quotes

search_images

submit_feedback

share_findings

propose_collection

Source Library

🎬 Experience Source Library

🎯 About Source Library

🌟 Why Source Library?

🚀 Quick Start

💻 Development Environment

📋 Tech Stack

📚 Core Features

📖 Reading & Navigation

🔄 Processing Pipeline

🎨 Curation & Discovery

📤 Scholarly Export

🏢 Tenant Subdomains

🏗️ Architecture Overview

📊 Data Model

🎨 Image Tier System

🔄 Processing Pipeline

🔌 API Routes (Key)

Public read APIs (no auth required today)

Tenant-scoped listing (not /api/bph/...)

Authenticated / internal APIs

🧪 Trying the API (curl, Postman, browser)

curl

Postman

Browser

📁 Directory Structure

🔄 Common Workflows

📥 Importing Books from Internet Archive

✂️ Processing a Split Book

✍️ Batch OCR with Gemini Batch API

🎓 Generating a Scholarly Edition

🧪 Testing

🚀 Run Tests

✅ E2E Test Examples

🚀 Deployment

🔄 Staging (Preview)

🌍 Production

🔑 Environment Variables

📖 Documentation

🤝 Contributing

🎯 What We're Looking For

📢 Reporting Issues

🛡️ Security & Data Protection

📊 Current Status

📝 License

📞 Support & Community

Install

Remote endpoint

Related servers

Tenant-scoped listing (not `/api/bph/...`)