# 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

```bash
npm install
npm start
```

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

```json
{
  "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:

```bash
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.