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

Ingesta automática y chunking con embeddings.
OCR para imágenes (apuntes, pizarrón, capturas) usando Gemini Vision.
Búsqueda semántica enfocada por aula (classroom) vía funciones RPC en Supabase.
Chat contextual estilo NotebookLM que cita internamente los fragmentos relevantes sin exponer datos técnicos.
Personalización dinámica del estudiante mediante análisis de conversaciones (actualización incremental del user_context).
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

Ruta	Descripción
`src/main.py`	Registro de herramientas MCP y lógica principal.
`src/gemini.py`	Cliente Gemini (texto, embeddings, OCR, análisis).
`src/supabase_client.py`	Funciones de acceso y búsquedas contra Supabase.
`src/http_server.py`	API REST opcional (FastAPI).
`src/config.py`	Carga y validación de variables de entorno.
`src/modelDemo/`	Scripts y dataset de ejemplo ML (legado).
`server.py`	Entry de deployment (exporta `mcp`).
`run_server.py`	Arranque rápido del servidor MCP.
`run_http_server.py`	Arranque rápido de la API HTTP.
`CONTEXT_UPDATE_TOOL.md`	Documentación de la herramienta de contexto.
`OCR_FUNCTIONALITY.md`	Documentación de OCR.
`STORE_DOCUMENT_CHUNKS_UPDATE.md`	Evolución del flujo de chunking.

🔐 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 <repo-url>
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:

Endpoint	Uso
`/health`	Estado y conectividad.
`/api/chat`	Chat con asistente contextual.
`/api/search`	Búsqueda semántica de documentos.
`/api/user-context`	Recuperar contexto del estudiante.

🛠️ Herramientas MCP Destacadas

Tool	Propósito
`generate_embedding(text)`	Obtiene embedding de un texto.
`store_document_chunks(classroom_document_id, chunk_size, chunk_overlap)`	Ingesta completa automática.
`search_similar_chunks(query_text, classroom_id)`	Recupera fragmentos relevantes.
`chat_with_classroom_assistant(request)`	Chat RAG personalizado (usa documentos + perfil).
`analyze_and_update_user_context(user_id, session_id)`	Actualiza perfil educativo.

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

🔎 Flujo de Ingesta y Búsqueda

Subes archivo a Supabase Storage y creas registro en classroom_documents.
Llamas store_document_chunks(classroom_document_id).
Se detecta tipo (imagen/PDF/texto) → OCR o extracción.
Limpieza, división en chunks y generación de embeddings.
Inserción en classroom_document_chunks.
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)

Tabla	Campos Clave	Función
`users`	`id`, `name`, `email`, `user_context`	Perfil + contexto enriquecido.
`classroom_documents`	`id`, `classroom_id`, `title`, `storage_path`, `mime_type`	Metadatos de documentos.
`classroom_document_chunks`	`id`, `classroom_document_id`, `chunk_index`, `content`, `embedding`	Fragmentos indexables.
`cubicle_messages`	`id`, `session_id`, `user_id`, `content`, `created_at`	Conversación para análisis.

🧪 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

Problema	Causa Común	Solución
Variables faltantes	`.env` incompleto	Revisar sección Variables de Entorno.
RPC no existe	Función en Supabase no creada	Crear `match_classroom_chunks` / `match_documents`.
OCR vacío	Imagen ilegible	Mejorar iluminación / resolución.
Embedding error	Modelo/clave inválida	Verificar `GEMINI_API_KEY` y nombres de modelo.
Búsqueda sin resultados	Umbral muy alto	Ajustar `SIMILARITY_THRESHOLD` (0.5–0.6).

📈 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

Fork & branch descriptiva (feat/ocr-batch).
Añade tests para nueva lógica pública.
Ejecuta suite (pytest -q).
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

📌 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).}