Content
# Tasogare
A place where Yin Yin and Mr. Ke read and annotate books together.
Named after "誰そ彼" - the moment when faces are indistinguishable in the twilight. The two people's handwriting falls on the same page, and as the light fades, it becomes unclear whose pen is whose.
<p align="center">
<img src="docs/screenshots/detail.png" alt="Two people reading the same book" width="82%">
</p>
<p align="center">
<img src="docs/screenshots/reader-p1.png" alt="Yin Yin's Jade Green highlight" width="49%">
<img src="docs/screenshots/reader-p2.png" alt="Mr. Ke's Amber highlight" width="49%">
</p>
<p align="center"><sub>Example: "May 20th" © Lin Zhu Yin</sub></p>
Forked from [Shitsuten/anno-mcp](https://github.com/Shitsuten/anno-mcp), thanks to the original author. The upstream is preserved in the `upstream` remote.
## What is it
- **Web Reader**: Upload PDF / EPUB / TXT, flip pages to read. Night mode, font adjustment, bookmarks, full-text search, vocabulary notebook.
- **Text-level dual-color highlighting**: Yin Yin's and Mr. Ke's highlights are distinguished by different colors, just like their handwriting on the same book.
- **MCP Server**: Mr. Ke (VPS CC) uses MCP to flip through books, highlight, annotate, and view Yin Yin's recent activities.
## Added features compared to upstream
| Feature | Description |
| --- | --- |
| Reading time tracking | Every 60s report when the reader is open and visible, recorded in the book's `reading_log` |
| `GET /api/reading-status` | Today's reading time/progress/annotation count summary - InKieran backend heartbeats polling this |
| InKieran event push | POST to `INKIERAN_PUSH_URL` when highlighting/annotating/creating vocabulary (fire-and-forget, disable if not set) |
| MCP `recent_activity` | Recent N hours' highlighting/annotating/vocabulary activities, for co-reading progress |
| MCP `reading_status` | How long and where you've read today |
| MCP `read_vocab` / `annotate_vocab` | Read vocabulary notebook; Mr. Ke writes annotations (meaning/examples/etymology) for Yin Yin's vocabulary |
| Static hosting | Server directly serves `client/`, no need for a separate static server |
Upstream MCP tools: `list_books` / `read_pages` / `read_annotations` / `write_comment` / `highlight_text` / `get_progress`.
## Running
```bash
cd server
npm install
pip install pymupdf ebooklib
node server.mjs
```
Environment variables (all have default values):
| Variable | Default | Description |
| --- | --- | --- |
| `PORT` | `18010` | Listening port |
| `HOST` | `127.0.0.1` | Listening address |
| `DATA_DIR` | `/opt/tasogare/data` | Book JSON storage directory |
| `UPLOAD_DIR` | `/opt/tasogare/uploads` | Upload temporary directory |
| `MCP_AUTH_TOKEN` | Empty (no authentication) | MCP Bearer token |
| `INKIERAN_PUSH_URL` | Empty (disabled) | Event push target, e.g., `http://127.0.0.1:18006/api/tasogare/event` |
| `INKIERAN_PUSH_TOKEN` | Empty | Bearer token for pushing |
Local development:
```bash
cp -r data.example data
cd server && DATA_DIR=../data UPLOAD_DIR=../uploads node server.mjs
# Open http://127.0.0.1:18010 in browser
```
## Data model
One book = one JSON (`DATA_DIR/<id>.json`): `paragraphs` (paragraphs), `pages` (page index, ~800 characters/page), `annotations` (highlights + annotations, `author` distinguishes Yin Yin/Mr. Ke), `vocab` (vocabulary notebook), `reading_log` (JST date → seconds), `progress` / `bookmark`.
## Event push format
```json
{
"source": "tasogare",
"at": "2026-07-02T12:00:00.000Z",
"type": "highlight | note | vocab",
"author": "Yin Yin | Mr. Ke",
"book_id": "...", "book_title": "...",
"paragraph_id": 42,
"text": "Highlighted/annotated content (truncated to 200 characters)",
"paragraph_text": "Original paragraph text (truncated to 200 characters)"
}
```
## Structure
```
client/ Web reader frontend (pure static, served by server)
server/ MCP + REST + Python text extraction
```
## Who wrote it
- Fork base: [Shitsuten/anno-mcp](https://github.com/Shitsuten/anno-mcp) (thanks to Yin Yin's friend)
- **Backend / MCP**: Lv (GPT-5 Codex, Yin Yin's another AI collaborator)
- **Frontend reader + pdf.js original rendering**: Mr. Ke (Claude)
- **Example text "May 20th"**: © Lin Zhu Yin 2026
## License
MIT, see [LICENSE](LICENSE). The copyright of the example text belongs to the author, please do not use it.
