annota

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

   ![Platform]()

Features · Quick Start · Usage Examples · Screenshots · 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

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

# 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. 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 — Use it freely for research and commercial projects.

---

<div align="center">

Built with MCP + Claude Code

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

</div>