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.

Related MCP server: Co-Reading MCP

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> 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).

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.

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.