# 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)
--- ## 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 |
### AI reads the paper → understands content → creates precise annotations Full paper reading summary note *AI generates a structured reading summary with key findings, methods, and conclusions*
--- ## ✨ 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:** 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:** 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:** 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:** 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:** 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:** 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: 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. ---
**Built with [MCP](https://modelcontextprotocol.io) + [Claude Code](https://claude.ai/code)** If this project helps your research, consider giving it a ⭐