Metadata-Version: 2.4
Name: annotation-extractor
Version: 0.2.1
Summary: MCP server for extracting annotations and highlights from e-readers (Kobo, Kindle, and more)
Author: Rohit Kaushik
License-Expression: MIT
Keywords: ai,annotations,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.

Currently supports **Kobo**, with an extensible backend architecture for Kindle and others (coming soon)

## Quick start

```bash
pip install annotation-extractor

# Or install from source
git clone https://github.com/rohitkaushik/annotation-extractor.git
cd annotation-extractor
pip install -e .
```

## Usage

### With Claude Code

```bash
claude mcp add annotations annotation-extractor
```

### With Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "annotations": {
      "command": "annotation-extractor"
    }
  }
}
```

### Manual

```bash
# Auto-detect mounted e-reader
annotation-extractor

# Or point to a specific Kobo database
KOBO_DB_PATH=/path/to/KoboReader.sqlite annotation-extractor
```

## 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"`) and `db_path` parameters. When omitted, the server auto-detects connected devices.

## Supported e-readers

| Reader | Status | Data source |
|--------|--------|-------------|
| Kobo | Supported | `.kobo/KoboReader.sqlite` via USB |
| Kindle | Planned | `My Clippings.txt` via USB |

## 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
