co-reading-mcp

A local MCP server for low-token co-reading: import a book, split it into chapter-sized chunks, read it chunk by chunk, and keep notes so a session can resume without re-reading the whole book.

Why

Sending a whole novel into the conversation burns through context immediately and has to be repeated every turn. This server keeps the book on disk and only loads the chunk currently being read, plus a small notes file to restore context between sessions.

Setup

npm install
npm start

Configure as a stdio MCP server (e.g. in Claude Desktop/Code config):

{
  "mcpServers": {
    "co-reading": {
      "command": "node",
      "args": ["/absolute/path/to/co-reading-mcp/src/server.js"]
    }
  }
}

Data is stored under data/ (override with CO_READING_DATA_DIR).

Remote mode (e.g. for the mobile app)

The Claude mobile app can't run a local stdio process — it needs an HTTPS endpoint added as a custom connector. Run the remote HTTP transport instead:

MCP_AUTH_TOKEN=<a long random secret> PUBLIC_BASE_URL=https://your-domain.com PORT=3000 npm run start:remote

This serves MCP over Streamable HTTP at http://<host>:3000/mcp. Requests must include Authorization: Bearer <MCP_AUTH_TOKEN>; without a token set, auth is disabled (fine for local testing, not for a public VPS).

The server also exposes a minimal single-user OAuth 2.0 shim (/.well-known/oauth-authorization-server, /register, /authorize, /token) so it can be added via Claude's official "Add custom connector" UI, which requires an OAuth-capable remote MCP server. There's no real login — anyone who can reach the server is handed the configured MCP_AUTH_TOKEN. Set PUBLIC_BASE_URL to the externally-reachable HTTPS URL (no trailing slash) so the OAuth metadata points to the right host.

To deploy on a VPS:

1. Copy the repo to the VPS and npm install.
2. Run start:remote behind a process manager (e.g. pm2 start npm --name co-reading -- run start:remote) so it survives disconnects/reboots.
3. Put a reverse proxy (Caddy or Nginx) in front of it for HTTPS — the mobile app requires https://. A minimal Caddyfile:

   your-domain.com {
     reverse_proxy localhost:3000
   }
   

4. In the Claude mobile app, go to Settings → Connectors → Add custom connector, and enter https://your-domain.com/mcp with the bearer token.

Web upload page

Besides the MCP tools, the remote server also serves a small mobile-friendly web page at https://your-domain.com/ for uploading .txt/.epub files by drag-and-drop or file picker (handy for adding books straight from your phone without going through the chat). It's protected with HTTP Basic Auth using the same MCP_AUTH_TOKEN as the password (any username works) so strangers can't use it to fill up your VPS. Uploaded books go through the same import pipeline as import_book and immediately show up in list_books.

Tools

• import_book — import a .txt or .epub file (by filePath) or raw text, auto-split into chapters and size-bounded chunks (~6000 chars, to stay under MCP read truncation limits). EPUB chapter boundaries (spine order) are preserved; title defaults to the EPUB's own metadata title.
• list_books — list imported books with chunk counts and last-read position.
• list_chunks — list a book's chunks (chapter/part breakdown) without text.
• read_chunk — read one chunk; omit chunkId to continue from the last-read position. Updates progress automatically.
• get_progress / set_progress — inspect or manually move the reading position.
• read_notes / append_notes — read/append timestamped discussion notes, used to restore context cheaply between sessions instead of re-reading the book.
• add_annotation / list_annotations — margin annotations anchored to a quoted passage within a chunk, tagged by author (human/claude); shown inline when reading a chunk. When both authors annotate an overlapping quote, a shared card is created automatically.
• list_cards — list shared cards (passages both human and claude annotated) for a book or chunk.
• search_book — case-insensitive substring search across all chunks, returning matches with context.

Chapter detection

Chapters are detected by heading patterns (第X章, Chapter N, numbered headings). Text without recognizable chapter markers is imported as a single chapter and split purely by size.