library-mcp

A specialized "library keeper" sub-agent for the Pythia stack: ingest PDF/EPUB books, then answer questions grounded in them via local embedding search.

Two MCP servers, one shared knowledge base:

• library-parse:

  • learn(file_name) extracts, chunks, and embeds a book from a shared inbox/attachment-cache directory into knowledge.db, classifying it as a book/article/notes deterministically (structural markers, no LLM) and extracting a real title from file metadata when present.

  • learn_text(title, text, source_url) ingests already-extracted text (e.g. a fetched web page), the same way, minus the file-parsing step.

  • forget(title) removes a learned book by title or partial title, refusing on zero or multiple matches rather than guessing.

  • list_learned() lists everything in the store, including in-progress embedding jobs, with each book's doc_type.

• library-keeper:

  • ask_library(question) embeds the question, searches the shared store, and hands matches to a small local reasoning model that decides whether to answer (with citations) or search again for connected knowledge, bounded at a few attempts. The frontier model calls this once and gets one synthesized answer back. Deterministically logs a "knowledge gap" (never from parsing the model's own wording) when a question can't be confidently answered.

  • list_knowledge_gaps() lists open gaps — questions worth adding a source for — for human review.

Both servers always talk to the same fixed local address for embeddings and reasoning — that address is set once, in a config file, and can't be changed by a book's content or by anything a user types. So there's nothing in a PDF or a chat message that could redirect this to some other server.

More on how this was actually built and debugged — including the real bugs found along the way (a small reasoning model not following instructions reliably, an EPUB's table of contents accidentally confusing search results, a tricky container-permissions issue) — is written up in the Pythia stack's own docs: hermes-stack/docs/architecture/library-mcp.md.

Development

python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/pytest

Related MCP server: EPUB Reader MCP Server

License

MIT.