<div align="center">

# Annota — AI-Powered Paper Annotation Assistant

**Turn your PDF library into an intelligent research assistant.**

AI reads your papers, highlights key findings, explains formulas, and writes structured notes — all saved back to your reference manager.

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10+-green.svg)](https://python.org)
[![MCP](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io)
[![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)]()

[Features](#-features) · [Quick Start](#-quick-start-3-minutes) · [Usage Examples](#-usage-examples) · [Screenshots](#-screenshots) · [Roadmap](#-roadmap)

</div>

---

## What Can It Do?

| You say... | AI does... |
|------------|------------|
| "高亮摘要中的发现结果" (Highlight findings in the abstract) | Reads the abstract, identifies findings, highlights them in green |
| "解释第3页的公式" (Explain the formulas on page 3) | Extracts the formula, adds an explanation as a note annotation |
| "写一份结构化阅读笔记" (Write a structured reading note) | Generates a note with contributions, methods, results, limitations — saved to your library |
| "以 MICRO 审稿人视角审阅" (Review as a MICRO reviewer) | Produces a structured review with scores and actionable feedback |

<div align="center">

### AI reads the paper → understands content → creates precise annotations

<img src="assets/note-7.png" width="700" alt="Full paper reading summary note">

*AI generates a structured reading summary with key findings, methods, and conclusions*

</div>

---

## ✨ Features

### 9 MCP Tools

| Tool | What it does |
|------|-------------|
| `search_zotero_items` | Search by title / author / key |
| `list_zotero_items` | Browse recent items |
| `get_item_metadata` | Get authors, year, venue, DOI |
| `get_pdf_text_bulk` | Extract full text (no coords, fast) |
| `get_pdf_layout_text` | Extract text + precise coordinates |
| `list_annotations` | View existing annotations |
| `create_pdf_annotation` | Create highlight / underline |
| `batch_annotate` | Create multiple annotations at once |
| `add_child_note` | Add a note to any item |

### 3 Claude Code Skills (Slash Commands)

| Command | Function |
|---------|----------|
| `/annota-annotate` | Smart annotation with semantic color coding |
| `/annota-summarize` | Structured reading notes saved to your library |
| `/annota-review` | Simulated peer review with scoring rubric |

### Smart Design

- **Two-phase workflow** — Reads full text first (cheap), then only gets coordinates for target sentences (precise). Reduces context usage by 63–80%.
- **Auto-skip references** — Detects "References" section and skips it. A 21-page paper extracts only 13 pages.
- **Batch annotations** — Creates 10 highlights in 1 API call instead of 10.
- **Friendly errors** — Write failures return helpful messages instead of crashing.

---

## 🚀 Quick Start (3 Minutes)

### Step 1: Clone & Install

```bash
git clone https://github.com/dengls24/annota.git
cd annota

python -m venv .venv

# Windows:
.venv\Scripts\activate
# macOS / Linux:
# source .venv/bin/activate

pip install pymupdf mcp
```

### Step 2: Configure Claude Code

Add to `~/.claude.json` (or via Claude Code Settings > MCP Servers):

**Windows:**
```json
{
  "mcpServers": {
    "annota": {
      "command": "C:/path/to/annota/.venv/Scripts/python.exe",
      "args": ["C:/path/to/annota/annota/server.py"],
      "env": {
        "ZOTERO_DATA_DIR": "C:/Users/YourName/Zotero"
      }
    }
  }
}
```

**macOS / Linux:**
```json
{
  "mcpServers": {
    "annota": {
      "command": "/path/to/annota/.venv/bin/python",
      "args": ["/path/to/annota/annota/server.py"],
      "env": {
        "ZOTERO_DATA_DIR": "/Users/YourName/Zotero"
      }
    }
  }
}
```

> **Finding your Zotero data directory:**
> - **Windows**: Zotero → Edit → Settings → Advanced → Data Directory Location (default: `C:\Users\YourName\Zotero`)
> - **macOS**: Zotero → Settings → Advanced → Data Directory Location (default: `~/Zotero`)
> - **Linux**: default `~/Zotero`

### Step 3: Use It

Just talk to Claude naturally:

```
# One command to read a full paper:
/annota-read "path/to/paper.pdf"

# Or natural language:
# Highlight the findings in this paper's abstract in green
"/Users/yourname/Zotero/storage/ABCD1234/paper.pdf"
```

Or use slash commands:
```
/annota-read "path/to/paper.pdf"
/annota-annotate "path/to/paper.pdf"
/annota-summarize "path/to/paper.pdf"
/annota-review "path/to/paper.pdf" ISCA
```

> **macOS path tip:** Drag a file from Finder into the terminal to get its full path, or right-click → "Copy as Pathname".

### (Optional) Install Skills Globally

```bash
# Make skills available in all projects
cp -r .claude/skills/ ~/.claude/skills/
```

---

## 📖 Usage Examples

### Example 1: Highlight Key Findings

**Input:**
```
把这篇论文摘要中的发现结果用绿色标出来
(Highlight the findings in this paper's abstract in green)
"E:\Zotero\storage\ABCD1234\Song et al. - 2025 - AI washing.pdf"
```

**Result:**

<img src="assets/note-2.png" width="700" alt="Green highlights on abstract findings">

*AI identifies findings in the abstract and highlights them in green*

---

### Example 2: Annotate Hypotheses & Theories

**Input:**
```
标注论文中的假设(H1, H2)，并用中文解释每个假设的理论基础
(Annotate the hypotheses (H1, H2) and explain the theoretical basis of each in Chinese)
```

**Result:**

<img src="assets/note-6.png" width="700" alt="Hypothesis annotations with Chinese explanations">

*Hypotheses highlighted in yellow, with Chinese explanation notes for the underlying theory*

---

### Example 3: Explain Formulas

**Input:**
```
解释论文中的核心公式，添加中文注释
(Explain the key formulas in this paper, add Chinese annotations)
```

**Result:**

<img src="assets/note-5.png" width="700" alt="Formula explanation annotations">

*DID model formula annotated with variable explanations in Chinese*

---

### Example 4: Policy Implications & Conclusion Notes

**Input:**
```
标注结论部分的政策启示，添加中文总结笔记
(Highlight policy implications in the conclusion, add a Chinese summary note)
```

**Result:**

<img src="assets/note-4.png" width="700" alt="Conclusion annotations with policy notes">

*Conclusion highlighted with a structured policy implications note*

---

### Example 5: Full Paper Reading Notes

**Input:**
```
/annota-summarize "path/to/paper.pdf"
```

**Result:**

<img src="assets/note-7.png" width="700" alt="Full structured reading note">

*AI generates a complete reading summary: topic, research question, method, key findings, and implications*

---

### Example 6: Detailed Paragraph-by-Paragraph Notes

**Input:**
```
逐段阅读这篇论文，为每个重要段落添加中文批注
(Read this paper paragraph by paragraph, add Chinese annotations to each important section)
```

**Result:**

<img src="assets/note-3.png" width="700" alt="Detailed paragraph notes">

*Each important paragraph gets a Chinese annotation explaining the content*

---

### Example 7: The AI Workflow in Action

Here's what Claude Code looks like when processing a paper:

<img src="assets/note-8.png" width="700" alt="Claude Code workflow">

*Claude creates a task list, reads the PDF, and calls MCP tools to create annotations step by step*

---

## 🎨 Color Convention

| Color | Code | Use for |
|-------|------|---------|
| 🟡 Yellow | `#ffd400` | Default / general highlights |
| 🟢 Green | `#28CA42` | Results, findings, data |
| 🔵 Blue | `#2EA8E5` | Methods, definitions, algorithms |
| 🔴 Red | `#ff6666` | Limitations, issues, problems |
| 🟣 Purple | `#a28ae5` | Contributions, novelty |

---

## ⚡ How It Handles Large PDFs

For papers >10 pages, a **two-phase workflow** avoids context overflow:

```
Phase 1 — Understand (lightweight)
  get_pdf_text_bulk(pdf, skip_refs=True)
  → Full text without coordinates
  → AI identifies which sentences to annotate

Phase 2 — Annotate (precise)
  get_pdf_layout_text(pdf, target_page_only)
  → Coordinates for 1–2 target pages
  batch_annotate(pdf, all_annotations)
  → Write everything in one call
```

**Real-world performance:**

| Paper | Pages | Old approach | New approach | Savings |
|-------|-------|-------------|-------------|---------|
| Conference paper | 2 pages | 41 KB coords | 15 KB text | **63%** |
| Journal article | 21 pages | 21 pages extracted | 13 pages (refs skipped at p.13) | **38%** |
| Survey paper | 19 pages | 19 pages extracted | 10 pages (refs skipped at p.10) | **47%** |

---

## 📁 Project Structure

```
annota/
├── annota/                        # MCP Server (Python)
│   ├── server.py                  # 9 tool registrations
│   ├── zotero_db.py               # SQLite read/write layer
│   ├── pdf_tools.py               # PyMuPDF text extraction
│   └── config.py                  # Constants & configuration
├── .claude/skills/                # Claude Code Skills
│   ├── annota-annotate/SKILL.md   # /annota-annotate
│   ├── annota-summarize/SKILL.md  # /annota-summarize
│   └── annota-review/SKILL.md     # /annota-review
├── docs/                          # Design documents
│   ├── annota-guide.md            # Usage guide (CN)
│   ├── large-pdf-design.md        # Large PDF handling design
│   ├── dev-notes.md               # Pitfalls & solutions
│   └── commercial-plan.md         # Commercialization plan
├── assets/                        # Screenshots
└── README.md
```

---

## ⚠️ Known Limitations & Disclaimer

> **Database Direct Access**: Annota writes annotations directly to the Zotero SQLite database, which [bypasses Zotero's internal consistency mechanisms](https://www.zotero.org/support/dev/client_coding/direct_sqlite_database_access). This is a design choice to enable **fully offline, local-first** annotation workflows without depending on external services. Users are responsible for their own database — **please back up your `zotero.sqlite` before use**. We plan to migrate to the official Zotero Web API / Local API in future versions.

| Limitation | Workaround | Planned Fix |
|-----------|------------|-------------|
| Direct SQLite write (not officially supported) | Back up your database before use | Migrate to Zotero Local API / Web API |
| Write ops need Zotero closed | Close Zotero before annotating | Local API bridge |
| References detection is heuristic | Pass `skip_refs=False` if needed | Improve heuristics |
| Tested primarily on Windows | Should work on macOS/Linux — paths auto-detected | Community testing welcome |

---

## 🗺 Roadmap

- [ ] **Zotero Local API / Web API** — Migrate from direct SQLite to official API for safer writes
- [ ] **More skills** — `/compare-papers`, `/extract-tables`, `/literature-map`
- [ ] **Prompt template marketplace** — Share and reuse annotation rules
- [ ] **Team features** — Shared annotation standards for lab groups
- [ ] **Multi-backend** — Support Adobe Acrobat, Endnote, and other PDF tools

---

## 🤝 Contributing

Issues and PRs are welcome! If you have ideas for new skills or tools, please open an issue.

## 📄 License

[MIT](LICENSE) — Use it freely for research and commercial projects.

---

<div align="center">

**Built with [MCP](https://modelcontextprotocol.io) + [Claude Code](https://claude.ai/code)**

If this project helps your research, consider giving it a ⭐

</div>