---

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

---

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

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

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.

---