Estud Ia MCP

📚 EstudIA MCP Server

Servidor MCP (Model Context Protocol) y API educativa para gestión inteligente de documentos por aula (classroom), búsqueda semántica, OCR, personalización automática del perfil del estudiante y asistente conversacional con RAG.

Estado: Activo · Versión: 2.0.0 · Stack principal: Python · FastMCP · Supabase · Google Gemini

🧠 Visión General

EstudIA MCP convierte un conjunto de documentos educativos (PDF, imágenes, texto plano) en una base de conocimiento consultable mediante:

1. Ingesta automática y chunking con embeddings.
2. OCR para imágenes (apuntes, pizarrón, capturas) usando Gemini Vision.
3. Búsqueda semántica enfocada por aula (classroom) vía funciones RPC en Supabase.
4. Chat contextual estilo NotebookLM que cita internamente los fragmentos relevantes sin exponer datos técnicos.
5. Personalización dinámica del estudiante mediante análisis de conversaciones (actualización incremental del user_context).
6. Herramientas MCP accesibles para agentes o integraciones externas + API HTTP opcional para pruebas rápidas.

✨ Características Clave

• 🔍 Búsqueda semántica de chunks por aula (search_similar_chunks).
• 🧩 Procesamiento y almacenamiento automatizado de documentos (store_document_chunks).
• 🖼️ OCR inteligente para imágenes con Gemini Vision (ver OCR_FUNCTIONALITY.md).
• 💬 Asistente contextual personalizado por aula (chat_with_classroom_assistant).
• 👤 Actualización automática del perfil del estudiante (analyze_and_update_user_context).
• 🧠 Generación de embeddings consistente vía Gemini (generate_embedding).
• 📦 Arquitectura MCP: cada herramienta lista para ser invocada por clientes compatibles.
• 🧪 Suite de tests (test_*.py) para validar ingestión, contexto y herramientas.

🏗️ Arquitectura (Alto Nivel)

flowchart LR
    A[Upload Documento
    (Supabase Storage)] --> B[Registro
    classroom_documents]
    B --> C[store_document_chunks()
    - OCR si imagen
    - PyPDF2 si PDF
    - Limpieza texto
    - Chunk + Embeddings]
    C --> D[(classroom_document_chunks)]
    D --> E[search_similar_chunks() RPC]
    E --> F[chat_with_classroom_assistant]
    F --> G[Gemini LLM]
    H[cubicle_messages] --> I[analyze_and_update_user_context]
    I --> J[(users.user_context)]
    G --> F

Componentes principales:

• Gemini: Generación de texto, embeddings y OCR.
• Supabase: Persistencia (usuarios, documentos, chunks, mensajes) y RPCs de búsqueda vectorial.
• FastMCP: Registro y exposición de herramientas y prompts.
• FastAPI (opcional): Capa HTTP para pruebas manuales.

📁 Estructura del Repositorio

🔐 Variables de Entorno

Crear .env en la raíz (sin comillas):

SUPABASE_URL=https://TU_PROYECTO.supabase.co
SUPABASE_SERVICE_ROLE_KEY=super-secreto
GEMINI_API_KEY=ya_lo_sabes
PORT=8000
NODE_ENV=development
GEMINI_MODEL=gemini-2.0-flash
GEMINI_EMBED_MODEL=gemini-embedding-001
EMBED_DIM=768
SIMILARITY_THRESHOLD=0.6
TOPK_DOCUMENTS=6

Nunca publiques SUPABASE_SERVICE_ROLE_KEY ni GEMINI_API_KEY. Usa gestores de secretos en producción.

🧩 Instalación (Local)

git clone 
cd estudIA-MCP
python -m venv .venv; .\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Para la API HTTP (si no estuviera ya incluida en requirements.txt):

pip install fastapi uvicorn[standard]

Crear archivo .env con las claves requeridas.

🚀 Ejecución

Modo MCP (herramientas para agentes)

python run_server.py

El objeto mcp expuesto en server.py permite también ejecutar:

fastmcp run server.py

Modo HTTP (pruebas REST)

python run_http_server.py

Endpoints clave:

🛠️ Herramientas MCP Destacadas

Revisa src/main.py para parámetros y respuesta detallada de cada herramienta.

🔎 Flujo de Ingesta y Búsqueda

1. Subes archivo a Supabase Storage y creas registro en classroom_documents.
2. Llamas store_document_chunks(classroom_document_id).
3. Se detecta tipo (imagen/PDF/texto) → OCR o extracción.
4. Limpieza, división en chunks y generación de embeddings.
5. Inserción en classroom_document_chunks.
6. Consulta con search_similar_chunks durante el chat.

🖼️ OCR (Gemini Vision)

• Soporta: JPG, JPEG, PNG, GIF, WEBP, BMP, HEIC/HEIF.
• Extrae texto estructurado (intenta mantener párrafos / tablas simples).
• Si PDF no tiene texto embebido, intenta fallback OCR.

Ver detalles y buenas prácticas en OCR_FUNCTIONALITY.md.

🧠 Personalización de Estudiantes

La herramienta analyze_and_update_user_context analiza toda la conversación (tabla cubicle_messages) y decide si incorpora nueva información relevante (nivel educativo, estilo de aprendizaje, intereses, objetivos, fortalezas, etc.).

Formato de respuesta y criterios: ver CONTEXT_UPDATE_TOOL.md.

🗄️ Esquema de Datos (Resumen)

🧪 Pruebas

Instalar pytest si no está:

pip install pytest
pytest -q

Tests relevantes:

• test_store_document_chunks.py — Ingesta y chunking.
• test_search_pdf.py / test_pdf_chunks_simple.py — Búsquedas y fragmentación.
• test_user_context_update.py — Actualización de contexto.
• test_ocr_functionality.py — Flujo OCR.

Puedes exportar TESTING=1 para omitir validaciones estrictas en config.py durante pruebas controladas.

🧯 Troubleshooting Rápido

📈 Roadmap Sugerido

• [ ] Normalizar nombres (remover referencias fiscales legadas).
• [ ] .env.example en el repositorio.
• [ ] Dockerfile + docker-compose para desarrollo rápido.
• [ ] CI (GitHub Actions) con lint + tests.
• [ ] Cache de embeddings para evitar recomputaciones.
• [ ] Batch ingest para múltiples documentos.
• [ ] Mejor soporte PDF escaneado multipágina.
• [ ] Métricas de uso (prometheus / logs estructurados).

🤝 Contribuir

1. Fork & branch descriptiva (feat/ocr-batch).
2. Añade tests para nueva lógica pública.
3. Ejecuta suite (pytest -q).
4. Haz PR incluyendo descripción clara y motivación.

Estilo: seguir convenciones existentes, mantener español técnico claro. Documenta cambios significativos en este README.

🛡️ Licencia

Si aún no hay licencia definida, se recomienda añadir una (MIT/Apache 2.0). Hasta entonces, el código se considera con derechos reservados del autor original.

📌 Resumen Rápido (TL;DR)

Sube documento → store_document_chunks → chunks + embeddings → search_similar_chunks → chat contextual y personalizable → contexto de estudiante se enriquece con analyze_and_update_user_context.

¿Necesitas añadir Docker / .env.example / scripts de utilidades? Pídelo y lo agrego enseguida.

README generado automáticamente analizando código y docs existentes (2025-11-09).