What Can It Do?

AI reads the paper → understands content → creates precise annotations

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

✨ Features

9 MCP Tools

3 Claude Code Skills (Slash Commands)

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:

{
  "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:

{
  "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:

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:

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:

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 highlighted with a structured policy implications note

Example 5: Full Paper Reading Notes

Input:

/annota-summarize "path/to/paper.pdf"

Result:

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:

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 creates a task list, reads the PDF, and calls MCP tools to create annotations step by step

🎨 Color Convention

⚡ 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:

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

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