ShelfLayer Connect
Folio № 003 — A schematic of the reading room

From a vague
question to a
cited paragraph.

A ShelfLayer MCP consultation is a four-stage operation: the agent calls a tool, the query is scoped, the passages are searched, and context is opened. Below is the blueprint.

The pipeline

One tool call, four movements.

Drawing  ·  QF-001  ·  Query Pipeline, rev. 4 Scale 1:1
Stage 01 · Intake

The agent asks.

Your agent calls an MCP tool with a query, optional shelf, optional book or section scope, and a small limit.

IN: query · scope · limit
OUT: searchable request
Stage 02 · Resolution

The librarian listens.

We use shelves, book metadata, and the user's query terms to narrow the search space before touching the passage index.

IN: query
OUT: shelf · book · section scope
Stage 03 · Retrieval

The stacks are walked.

The scoped corpus is searched with PostgreSQL full-text search, English stemming, phrase search, OR, required terms, and exclusions.

IN: shelf set
OUT: ranked passages
Stage 04 · Delivery

The page is opened.

We return passages with book metadata and structural locators. Agents can then read the section or request a clean citation.

IN: ranked passages
OUT: passages · locators · citations
Input from agent ShelfLayer processing Output to agent Beta pipeline · full-text index
i.
Stage 01 · Intake

The agent asks.

A consultation begins with the simplest gesture in MCP: your agent calls a tool. It can start broad with list_shelves, find a title with list_books, or go straight to search_passages.

Three parameters do most of the work: query is the vocabulary to search, shelf narrows the corpus, and limit keeps agent loops disciplined. Book and section IDs are available when the agent already knows where it is reading.

Shelf

A public category, e.g. philosophy or economics-and-finance.

Query

Keyword search with quoted phrases, OR, required terms, and exclusions.

Book or section

Optional IDs let an agent search inside one book or open a section directly.

Notes

include_notes controls indexes, footnotes, and apparatus.

ii.
Stage 02 · Resolution

The librarian listens.

A working reference librarian thinks in shelves and vocabulary. ShelfLayer gives the agent those handles: shelves, books, tables of contents, sections, and passage IDs.

Because the beta uses keyword full-text search, the best agents ask like researchers: they try older terms, quote exact phrases, and search several variants instead of trusting one modern wording.

Shelf discovery

list_shelves shows the categories the public beta currently holds.

Book navigation

inspect_book exposes the table of contents before an agent reads.

iii.
Stage 03 · Retrieval

The stacks are walked.

Every book is parsed into ordered sections and passages, then indexed alongside its book metadata and shelf membership. Retrieval is deliberately simple right now: PostgreSQL full-text search over passages, scoped by shelf, book, or section when available.

This is not semantic search yet, and the docs say that on purpose. The advantage is transparency: when a result appears, it appeared because the words, shelf, book, and structure actually matched.

iv.
Stage 04 · Delivery

The page is opened.

The response is structured and ready for an agent to inspect. Each passage arrives with IDs, book metadata, section information, and a locator that can be turned into a user-facing citation.

We do not paraphrase, summarise, or "improve" the text. The book gets to speak in its own voice.

A consultation, in full

Request  ·  Response.

REQ  ·  MCP tools/call search_passages 
// The agent has been asked to explain
// thrift and compounding with sources.

{
  "name": "search_passages",
  "arguments": {
    "query": "\"compound interest\" OR thrift economy",
    "shelf": "economics-and-finance",
    "limit": 3
  }
}
RES  ·  passages with locators 
{
  "passages": [
    {
      "passage_id": "psg_...",
      "book_id": "bk_an-inquiry...",
      "title": "An Inquiry into the Nature and Causes...",
      "author": "Smith, Adam",
      "section_id": "sec_...",
      "text": "..."
    },
    /* 2 more passages */
  ]
}
The tool loop

Let the agent narrow before it reads.

Step i. — Discover

list_shelves

Start with categories so the agent knows which part of the public shelf it is asking.

27 shelves
Step ii. — Search

search_passages

Find candidate passages with precise vocabulary and tight scopes.

20M+ passages
Step iii. — Open

inspect_book

Use the table of contents to understand where the passage lives.

book-shaped context
Step iv. — Cite

get_citation

Return a structural locator the final answer can show to a human.

source trail
Marginalia

Notes in the margin.

How do you decide what gets on the shelf? +

The beta starts with public-domain books sourced through Project Gutenberg and Gutendex, then organizes them into practical shelves. Expansion should be deliberate: more open collections first, then licensed or private corpora where the rights and use case are clear.

What about copyright? +

The current public shelf is public-domain material. We should not imply modern publisher licenses until they exist. Enterprise/private shelves are scoped separately around material the customer has the right to use.

Can I bring my own corpus? +

Yes — that is the Enterprise offer. Internal docs, a company wiki, manuals, country law, standards, or another private corpus can become a custom MCP with its own taxonomy and retrieval behavior.

How is this different from a normal RAG setup? +

Three differences. First, the corpus is book-shaped: shelves, books, tables of contents, sections, and passages. Second, retrieval is honest full-text search today, which makes behavior inspectable. Third, the response carries structural citations instead of anonymous chunk IDs.

Do you offer an MCP server? +

Yes — ShelfLayer is a Model Context Protocol server. Agents in MCP-aware hosts can consult it directly. See the MCP guide.

What happens when books disagree? +

The beta returns passages, not verdicts. A good agent should search multiple shelves or books, compare the passages, and say when the source material points in different directions.