Annota — Asistente de anotación de documentos impulsado por IA

Convierte tu biblioteca de PDF en un asistente de investigación inteligente.

La IA lee tus documentos, resalta los hallazgos clave, explica fórmulas y escribe notas estructuradas, todo guardado directamente en tu gestor de referencias.

👁 License: MIT
👁 Python 3.10+
👁 MCP
👁 Platform

Características · Inicio rápido · Ejemplos de uso · Capturas de pantalla · Hoja de ruta

¿Qué puede hacer?

La IA lee el documento → comprende el contenido → crea anotaciones precisas

La IA genera un resumen de lectura estructurado con hallazgos clave, métodos y conclusiones

Related MCP server: Zotero MCP Server

✨ Características

9 herramientas MCP

3 habilidades de Claude Code (comandos de barra)

Diseño inteligente

• Flujo de trabajo de dos fases — Lee el texto completo primero (económico), luego solo obtiene coordenadas para las oraciones objetivo (preciso). Reduce el uso de contexto en un 63–80%.

• Salto automático de referencias — Detecta la sección de "Referencias" y la omite. Un documento de 21 páginas extrae solo 13 páginas.

• Anotaciones por lotes — Crea 10 resaltados en 1 llamada a la API en lugar de 10.

• Errores amigables — Los fallos de escritura devuelven mensajes útiles en lugar de bloquearse.

🚀 Inicio rápido (3 minutos)

Paso 1: Clonar e instalar

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

Paso 2: Configurar Claude Code

Añadir a ~/.claude.json (o a través de la configuración de Claude Code > Servidores MCP):

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

Encontrar tu directorio de datos de Zotero:

• Windows: Zotero → Editar → Ajustes → Avanzado → Ubicación del directorio de datos (predeterminado: C:\Users\TuNombre\Zotero)

• macOS: Zotero → Ajustes → Avanzado → Ubicación del directorio de datos (predeterminado: ~/Zotero)

• Linux: predeterminado ~/Zotero

Paso 3: Usarlo

Simplemente habla con Claude de forma natural:

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

O usa comandos de barra:

/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

Consejo de ruta en macOS: Arrastra un archivo desde Finder al terminal para obtener su ruta completa, o haz clic derecho → "Copiar como nombre de ruta".

(Opcional) Instalar habilidades globalmente

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

📖 Ejemplos de uso

Ejemplo 1: Resaltar hallazgos clave

Entrada:

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

Resultado:

La IA identifica los hallazgos en el resumen y los resalta en verde

Ejemplo 2: Anotar hipótesis y teorías

Entrada:

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

Resultado:

Hipótesis resaltadas en amarillo, con notas de explicación en chino para la teoría subyacente

Ejemplo 3: Explicar fórmulas

Entrada:

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

Resultado:

Fórmula del modelo DID anotada con explicaciones de variables en chino

Ejemplo 4: Implicaciones políticas y notas de conclusión

Entrada:

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

Resultado:

Conclusión resaltada con una nota estructurada de implicaciones políticas

Ejemplo 5: Notas de lectura de documento completo

Entrada:

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

Resultado:

La IA genera un resumen de lectura completo: tema, pregunta de investigación, método, hallazgos clave e implicaciones

Ejemplo 6: Notas detalladas párrafo por párrafo

Entrada:

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

Resultado:

Cada párrafo importante obtiene una anotación en chino explicando el contenido

Ejemplo 7: El flujo de trabajo de IA en acción

Así es como se ve Claude Code al procesar un documento:

Claude crea una lista de tareas, lee el PDF y llama a las herramientas MCP para crear anotaciones paso a paso

🎨 Convención de colores

⚡ Cómo maneja PDFs grandes

Para documentos de más de 10 páginas, un flujo de trabajo de dos fases evita el desbordamiento de contexto:

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

Rendimiento en el mundo real:

📁 Estructura del proyecto

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

⚠️ Limitaciones conocidas y descargo de responsabilidad

Acceso directo a la base de datos: Annota escribe anotaciones directamente en la base de datos SQLite de Zotero, lo cual evita los mecanismos de consistencia interna de Zotero. Esta es una elección de diseño para permitir flujos de trabajo de anotación totalmente fuera de línea y locales sin depender de servicios externos. Los usuarios son responsables de su propia base de datos — por favor, haz una copia de seguridad de tu zotero.sqlite antes de usarlo. Planeamos migrar a la API web oficial de Zotero / API local en versiones futuras.

🗺 Hoja de ruta

• [ ] API local de Zotero / API web — Migrar de SQLite directo a la API oficial para escrituras más seguras

• [ ] Más habilidades — /compare-papers, /extract-tables, /literature-map

• [ ] Mercado de plantillas de prompts — Compartir y reutilizar reglas de anotación

• [ ] Funciones de equipo — Estándares de anotación compartidos para grupos de laboratorio

• [ ] Multi-backend — Soporte para Adobe Acrobat, Endnote y otras herramientas de PDF

🤝 Contribución

¡Las incidencias y PRs son bienvenidos! Si tienes ideas para nuevas habilidades o herramientas, por favor abre una incidencia.

📄 Licencia

MIT — Úsalo libremente para investigación y proyectos comerciales.

Construido con MCP + Claude Code

Si este proyecto ayuda a tu investigación, considera darle una ⭐

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers

Tools

• add_child_noteA
• batch_annotateA
• create_pdf_annotationA
• get_item_metadataA
• get_pdf_layout_textA
• get_pdf_text_bulkA
• list_annotationsA
• list_zotero_itemsA