Apparatus is a web-based e-reading application. It is intended as an experiment in how generative language models, and foundation models in particular, can enrich the reading experience.
Apparatus is currently in development, but it already includes many table-stakes e-reading features as well as some AI-augmented ones.
Apparatus supports basic reading features like navigation, progress, display configuration, and persistent reading locations.
It exposes an MCP server that allows users to chat about the content of the book as well as the specific content on their screen with any AI client that supports remote MCPs (see installation instructions below).
Users can view AI-generated explanatory notes for any text within the book. These notes take historical and textual context into account, and give answers based on the reader's current location - including avoiding spoilers.
- Saving highlights and notes, including those generated by AI
- Broader range of explanatory notes with more options for querying the AI
- AI-powered full text search
- More books!
The code on main is currently live at https://apparatusweb-staging.up.railway.app/. This is essentially a development environment intended for dogfooding and experimentation, so it has some rough edges. If you'd like to give it a try, I recommend signing in with a username and password instead of via oauth.
The Apparatus MCP server gives LLMs access to your reading data and to the full text of your book, so you can have conversations in any compatible chat client. The server is authenticated via Oauth so to use this feature, you need to use a chat client with support for remote MCP servers over Oauth. Claude Desktop is one chat client where this flow works.
To connect the MCP server in Claude Desktop, follow these steps: [NOTE: This flow is currently broken 😞.]
- add a "custom connector" using the URL https://api.apparatus-ebooks.com/mcp and the name "Apparatus Ebooks"
- click "connect"
- log in to Apparatus and hit "Allow Access"
The MCP server exposes a number of resources and tools that the model can use to answer your questions. For best results, I suggest create a new Project with a note that all your discussions in the project are about what you're reading in Apparatus; otherwise you will have to prompt the model each time to make sure it invokes the right MCP server.
Apparatus comprises three primary components: a TypeScript Next.js web app, a Python FastAPI server, and a Go Chi HTTP service. The TypeScript app is the web interface and it also handles converting authentication from cookies to Oauth tokens. The Python server is the backend for the web app and it also exposes the MCP server. The Go service is internal; it uses the Readium Go Toolkit to manipulate the ebook files and its sole client is the Python server.
Right now the app is deployed on Railway with a Postgres database. It also includes a publication server which exposes the ebook assets for consumption by the ereader web app - this is part of the Readium web architecture (see the credits section below), but this functionality, like the search and download capabilities exposed by the Go service, is proxied through the Python app. The authentication provider is Auth0.
For more technical details, including more notes on other features of this repo, see docs.
This repo is a monorepo and has a VS code workspace to match. Running the app locally means running multiple components, all of which are configured with environment variables. Unfortunately, making and verifying changes to Apparatus currently requires configuring a number of secrets, so it is not contributor-friendly.
However, if you want to dig into the code or try to get the app running, the starting point for technical documentation is in docs.
The foundational e-reading features are built on top of Thorium Web and the Readium CLI, which are both part of the Readium Web project.
The ebooks included in the library so far are from Standard Ebooks. Apparatus does not support any form of DRM and at this stage does not allow users to upload their own books.
Although the app is intended to be fully-featured enough to be useful to a real reader, it is a side project and it may be taken down or modified at any time.
Finally, this repo represents experimentation not only with e-reading designs and features but with ways of writing code and building apps. I have tried to keep the code maintainable and well-documented, but my main priority has been learning.