Annota — ИИ-ассистент для аннотирования научных статей

Превратите свою библиотеку PDF-файлов в интеллектуального научного ассистента.

ИИ читает ваши статьи, выделяет ключевые результаты, объясняет формулы и пишет структурированные заметки — и всё это сохраняется в вашем менеджере библиографии.

Возможности · Быстрый старт · Примеры использования · Скриншоты · Дорожная карта

Что он умеет?

ИИ читает статью → понимает содержание → создает точные аннотации

ИИ генерирует структурированное резюме с ключевыми результатами, методами и выводами

Related MCP server: Zotero MCP Server

✨ Возможности

9 инструментов MCP

3 навыка Claude Code (слэш-команды)

Умный дизайн

• Двухфазный рабочий процесс — Сначала читает полный текст (дешево), затем получает координаты только для целевых предложений (точно). Снижает использование контекста на 63–80%.

• Автоматический пропуск списка литературы — Обнаруживает раздел "References" и пропускает его. Из 21-страничной статьи извлекается только 13 страниц.

• Пакетное аннотирование — Создает 10 выделений за 1 вызов API вместо 10.

• Понятные ошибки — При сбоях возвращаются полезные сообщения, а не просто падение программы.

🚀 Быстрый старт (3 минуты)

Шаг 1: Клонирование и установка

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

Шаг 2: Настройка Claude Code

Добавьте в ~/.claude.json (или через настройки Claude Code > 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"
      }
    }
  }
}

Как найти директорию данных Zotero:

• Windows: Zotero → Правка → Настройки → Дополнительно → Расположение папки данных (по умолчанию: C:\Users\YourName\Zotero)

• macOS: Zotero → Настройки → Дополнительно → Расположение папки данных (по умолчанию: ~/Zotero)

• Linux: по умолчанию ~/Zotero

Шаг 3: Использование

Просто общайтесь с Claude естественным языком:

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

Или используйте слэш-команды:

/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: Перетащите файл из Finder в терминал, чтобы получить полный путь, или нажмите правой кнопкой мыши → "Скопировать как путь".

(Опционально) Глобальная установка навыков

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

📖 Примеры использования

Пример 1: Выделение ключевых результатов

Ввод:

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

Результат:

ИИ определяет результаты в аннотации и выделяет их зеленым цветом

Пример 2: Аннотирование гипотез и теорий

Ввод:

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

Результат:

Гипотезы выделены желтым цветом, с заметками-объяснениями теории на китайском языке

Пример 3: Объяснение формул

Ввод:

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

Результат:

Формула модели DID аннотирована с объяснением переменных на китайском языке

Пример 4: Политические последствия и заметки к выводам

Ввод:

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

Результат:

Выводы выделены с добавлением структурированной заметки о политических последствиях

Пример 5: Полные заметки по прочитанной статье

Ввод:

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

Результат:

ИИ генерирует полное резюме: тема, исследовательский вопрос, метод, ключевые результаты и выводы

Пример 6: Детальные заметки по абзацам

Ввод:

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

Результат:

Каждый важный абзац получает аннотацию на китайском языке с объяснением содержания

Пример 7: Рабочий процесс ИИ в действии

Вот как выглядит Claude Code при обработке статьи:

Claude создает список задач, читает PDF и вызывает инструменты MCP для пошагового создания аннотаций

🎨 Цветовая конвенция

⚡ Как обрабатываются большие PDF-файлы

Для статей длиннее 10 страниц двухфазный рабочий процесс позволяет избежать переполнения контекста:

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

Реальная производительность:

📁 Структура проекта

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

⚠️ Известные ограничения и отказ от ответственности

Прямой доступ к базе данных: Annota записывает аннотации напрямую в базу данных SQLite Zotero, что обходит внутренние механизмы целостности Zotero. Это проектное решение для обеспечения полностью автономного, локального рабочего процесса аннотирования без зависимости от внешних сервисов. Пользователи несут ответственность за свою базу данных — пожалуйста, сделайте резервную копию zotero.sqlite перед использованием. Мы планируем перейти на официальный Zotero Web API / Local API в будущих версиях.

🗺 Дорожная карта

• [ ] Zotero Local API / Web API — Переход с прямого SQLite на официальный API для более безопасной записи

• [ ] Больше навыков — /compare-papers, /extract-tables, /literature-map

• [ ] Маркетплейс шаблонов промптов — Обмен и повторное использование правил аннотирования

• [ ] Командные функции — Общие стандарты аннотирования для исследовательских групп

• [ ] Мульти-бэкенд — Поддержка Adobe Acrobat, Endnote и других PDF-инструментов

🤝 Участие в разработке

Проблемы и PR приветствуются! Если у вас есть идеи для новых навыков или инструментов, пожалуйста, откройте issue.

📄 Лицензия

MIT — Свободно используйте для исследований и коммерческих проектов.

Создано с помощью MCP + Claude Code

Если этот проект помогает вашим исследованиям, подумайте о том, чтобы поставить ⭐