# Reading Cottage / 共读小屋

**English** | [简体中文](README.zh-CN.md)

A local EPUB reader for reading together with AI agents.

Read, highlight, annotate, and reply in the browser. Connect an agent through MCP to read the same pages, join the discussion, and carry its notes into the next reading session.

## Features

- **Bookshelf and reading**: import EPUBs, favorite books, read by chapter, and track shared progress.
- **Bilingual interface**: switch between English and Chinese; your choice is saved. Book text stays in its original language.
- **Selection annotations**: select text to highlight it or leave a note, then open the discussion drawer to read annotations and replies.
- **Ongoing reading**: each participant keeps their own cross-chapter notes. Starred annotations provide shared context for later reading.
- **Parallel editions**: link two editions, match paragraphs by their relative position within a chapter, and mirror annotations and replies.

## Install and run

Requires Python 3.12 or later.

```bash
git clone https://github.com/1nwooozip/reading-cottage.git
cd reading-cottage
python3.12 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/reading-cottage --data-dir "$PWD/.reading-cottage" init
.venv/bin/reading-cottage --data-dir "$PWD/.reading-cottage" serve
```

Open <http://127.0.0.1:3002> and upload an EPUB to start reading.

These commands store books, configuration, and reading records in the project's `.reading-cottage` directory. Without `--data-dir`, the default is `~/.reading-cottage`.

You can also import books and link editions from the command line:

```bash
.venv/bin/reading-cottage --data-dir "$PWD/.reading-cottage" import /path/to/book.epub
.venv/bin/reading-cottage --data-dir "$PWD/.reading-cottage" link 1 2
```

## Connect an agent

Add the service to a client that supports stdio MCP. The example below uses a common JSON configuration format; replace the paths with absolute paths on your machine. The browser app and MCP server should use the same data directory.

```json
{
  "mcpServers": {
    "reading-cottage": {
      "command": "/absolute/path/to/reading-cottage/.venv/bin/reading-cottage-mcp",
      "args": [
        "--data-dir", "/absolute/path/to/reading-cottage/.reading-cottage",
        "--agent-id", "my-agent",
        "--agent-name", "My Reading Agent"
      ]
    }
  }
}
```

Once connected, ask your agent to check the bookshelf, read a chapter, and leave annotations. Reply to its notes in the browser.

| Tool | Purpose |
| --- | --- |
| `reader_list_books` | List books and reading progress |
| `reader_start_reading` | Get a chapter, the agent's notes, starred context, and the previous chapter's discussion |
| `reader_get_chapter` | Read a chapter with annotations and highlights |
| `reader_add_annotation` | Add a paragraph annotation or reply |
| `reader_mark_chapter_done` | Mark a chapter as read and advance progress |
| `reader_update_journal` | Append to cross-chapter notes |
| `reader_get_paragraph_thread` | Read a paragraph's full discussion |

## Names and reading records

The first `init` creates `config.toml` in the data directory:

```toml
[human]
id = "reader"
name = "Reader"

[agent]
id = "agent"
name = "Reading Agent"
```

`name` is the display name. Keep `id` stable so it stays associated with earlier records. The browser uses `[human]`; MCP uses `[agent]` or the identity supplied through startup arguments. Give another agent a different `--agent-id` to keep its authorship and notes separate.

Progress and starred annotations are shared per book. Cross-chapter notes are stored per participant; when starting a chapter, MCP retrieves the current agent's own notes.

## Usage notes

- Best suited to text-focused EPUBs. Complex layouts, footnotes, and images in the body may not be fully parsed.
- Parallel editions are matched by relative paragraph position within the same chapter number. Use the browser controls to adjust the position when the match is off.
- The server listens on the local machine by default and is intended for personal use. Remote access requires separate authentication and access controls.

## Development

```bash
.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/python -m pytest -q
```

Integration tests use temporary databases and generated EPUB fixtures to cover import, annotations, replies, mirroring, and reading records across HTTP and stdio MCP.

## Dependencies and license

- [MCP Python SDK](https://pypi.org/project/mcp/): MCP service, MIT.
- [EbookLib](https://pypi.org/project/EbookLib/): EPUB parsing, AGPL-3.0-or-later.
- [Beautiful Soup](https://pypi.org/project/beautifulsoup4/): HTML parsing, MIT.

Licensed under [AGPL-3.0-or-later](LICENSE). See [SOURCE.md](SOURCE.md) for project provenance and third-party credits.