Metadata-Version: 2.4
Name: annotation-extractor
Version: 0.3.0
Summary: MCP server for extracting annotations and highlights from e-readers (Kobo, Kindle, Boox)
Author: Rohit Kaushik
License-Expression: MIT
Keywords: ai,annotations,boox,ereader,highlights,kindle,kobo,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: mcp>=1.2.0
Description-Content-Type: text/markdown

# annotation-extractor

MCP server for extracting annotations, highlights, and reading progress from e-readers.

Supports **Kobo**, **Kindle**, and **Boox**.

## Install

```bash
pip install annotation-extractor
```

Or from source:

```bash
git clone https://github.com/rkaushik29/annotation-extractor-mcp.git
cd annotation-extractor
pip install -e .
```

## Usage

Connect your e-reader via USB, add the MCP server to your agent, and start asking questions about your reading.

| Client | Setup |
|--------|-------|
| Claude Code | `claude mcp add annotations -- annotation-extractor` |
| Claude Desktop | Add to `claude_desktop_config.json`: `{"mcpServers": {"annotations": {"command": "annotation-extractor"}}}` |
| OpenClaw | `openclaw mcp add annotations -- annotation-extractor` |
| Gemini CLI | Add to `~/.gemini/settings.json`: `{"mcpServers": {"annotations": {"command": "annotation-extractor"}}}` |
| Codex | `codex --mcp-config mcp.json` with `mcp.json`: `{"mcpServers": {"annotations": {"command": "annotation-extractor"}}}` |

### Try it out

Once the MCP is connected and your e-reader is plugged in, try asking your agent:

> "What are my highlights from the last book I read?"

> "Search my annotations for anything about consciousness"

> "Show me all the notes I took while reading Neuromancer"

### Environment variables

If auto-detection doesn't find your device, you can point to the data source directly:

```bash
KOBO_DB_PATH=/path/to/KoboReader.sqlite annotation-extractor
KINDLE_CLIPPINGS_PATH=/path/to/My\ Clippings.txt annotation-extractor
BOOX_EXPORT_PATH=/path/to/boox-export annotation-extractor
```

## Supported e-readers

| Reader | Data source |
|--------|-------------|
| Kobo | `.kobo/KoboReader.sqlite` via USB |
| Kindle | `My Clippings.txt` via USB |
| Boox | Annotation export directory (one `.txt` file per book) via USB |

## Tools

| Tool | Description |
|------|-------------|
| `list_books` | List all books, optionally filtered to those with annotations |
| `get_annotations` | Get highlights and notes for a specific book (by title or ID) |
| `search_annotations` | Full-text search across all highlights and notes |
| `get_reading_progress` | Reading progress, time spent, and status for all books |
| `get_book_details` | Detailed metadata for a specific book |

All tools accept optional `backend_name` (e.g., `"kobo"`, `"kindle"`, `"boox"`) and `db_path` parameters. When omitted, the server auto-detects connected devices.

## Adding a new backend

1. Create `src/annotation_extractor/backends/yourreader.py` implementing `EReaderBackend`
2. Add your backend to `_ALL_BACKENDS` in `registry.py`
3. No changes needed to `server.py` or `models.py`

## Development

```bash
git clone https://github.com/rohitkaushik/annotation-extractor.git
cd annotation-extractor
pip install -e ".[dev]"
pytest
```

## License

MIT
