数学辅导AI

Tutor de Matemáticas — MCP (Model Context Protocol)

Trabajo Práctico Final — "Desarrollando una Solución de IA Aplicada"

Materia: S.A.C. Modelos y Aplicaciones de la Inteligencia Artificial

1. Tutor de Matemáticas (MCP) — Agente tutor basado en IA para alumnos de secundaria, especializado en álgebra y resolución de ecuaciones.

2. Descripción del problema

Los estudiantes de nivel secundario necesitan apoyo personalizado para comprender álgebra y resolver ecuaciones lineales y cuadráticas. Este proyecto entrega un tutor virtual que explica los pasos, resuelve problemas cuando el usuario lo solicita y propone ejercicios para practicar usando una pizarra visual.

Público objetivo: estudiantes de secundaria y docentes que quieran un asistente para prácticas y explicaciones de álgebra.

3. Demo (GIF)

4. Stack tecnológico

• Python 3.10+
• FastAPI — backend y endpoints REST
• Uvicorn — servidor ASGI
• Beanie + Motor — ODM/driver para MongoDB (async)
• Pydantic — validación de modelos
• React + Vite — frontend (client)
• Gemini SDK / Google Generative AI (google.generativeai) — integración con el modelo generativo
• PIL (Pillow) — manipulación y decodificación de imágenes
• passlib, jose, OAuth2 — autenticación y hashing de contraseñas
• Otros: python-dotenv, uvicorn, motor, beanie, pydantic, pytest (opcional)

5. Requisitos previos

• Node.js (v16+) y npm
• Python 3.10 o superior
• MongoDB (local o URL Atlas)
• Variables de entorno en un archivo .env:
  • MONGO_URI — cadena de conexión a MongoDB
  • SECRET_KEY — clave para JWT
  • GEMINI_API_KEY — API key para Gemini SDK

6. Instalación (clonar e instalar)

# Clonar
git clone https://github.com/ArianneAlonso/tutor-math-mcp.git
cd <repo>

Frontend (client)

cd client
npm install
npm run dev
# El frontend correrá en http://localhost:5173 por defecto (Vite)

Backend (server)

cd server
# Crear entorno virtual
python -m venv env
# Windows (PowerShell)
.\env\Scripts\Activate.ps1
# Windows (cmd.exe)
.\env\Scripts\activate
# macOS / Linux
source env/bin/activate

# Instalar dependencias
pip install -r requirements.txt

# Correr server (desarrollo)
uvicorn main:app --reload --host 0.0.0.0 --port 3000

7. Uso / Ejecución

1. Levantar MongoDB (local o configurar MONGO_URI).
2. Levantar frontend y backend según instrucciones anteriores.
3. Abrir la app en el navegador (frontend).
4. Registrar un usuario (endpoint /register) o usar la UI.
5. Iniciar sesión para obtener token (endpoint /token).
6. Crear o seleccionar una conversación y usar:
   • Chat: /chat — envía mensajes al agente tutor.
   • Pizarra: /calculate — enviar imagen base64 de la pizarra para análisis y cálculo.
   • MCP JSON-RPC: /mcp — para listar herramientas, inicializar protocolo y llamarlas.

8. Endpoints importantes

• POST /register — registrar usuario
• POST /token — login (OAuth2 Password)
• GET /users/me — info del usuario actual
• POST /conversations/new — crear conversación
• DELETE /conversations/{conversation_id} — eliminar conversación
• GET /conversations — listar conversaciones del usuario
• POST /chat — enviar mensaje al tutor (requiere token)
• POST /calculate — analizar pizarra (imagen base64)
• POST /mcp — handler MCP (initialize, tools/list, tools/call)

9. Documentación de las herramientas (Tools)

Todas las herramientas están documentadas y expuestas para el protocolo MCP. Si se utiliza salida estructurada (objetos JSON), también están documentadas.

1) resolver_ecuacion_lineal(m: float, b: float)

• Descripción: Resuelve ecuaciones de la forma m x + b = 0.
• Argumentos:
  • m (number) — coeficiente de x (no puede ser 0).
  • b (number) — término independiente.
• Salida (JSON): SolucionLineal con campos:
  • tipo: "lineal"
  • ecuacion_original: string
  • solucion: float
  • pasos: lista de strings (paso a paso)
  • verificacion: string
• Errores posibles:
  • ValueError si m == 0 (devuelve error de validación con código -32602 en MCP).

2) resolver_ecuacion_cuadratica(a: float, b: float, c: float)

• Descripción: Resuelve a x² + b x + c = 0.
• Argumentos:
  • a (number) — coeficiente cuadrático (no puede ser 0)
  • b (number)
  • c (number)
• Salida (JSON): SolucionCuadratica con campos:
  • tipo: "cuadratica"
  • ecuacion_original, a, b, c, discriminante, soluciones, tipo_solucion, pasos
• Errores posibles:
  • ValueError si a == 0.

3) realizar_operacion(expresion: str)

• Descripción: Evalúa expresiones aritméticas/algebraicas simples, soportando ^ como potencia y funciones sqrt, sin, cos, etc.
• Argumentos:
  • expresion (string) — la expresión a evaluar.
• Salida (JSON): ResultadoOperacion con campos:
  • expresion_original, resultado (float), pasos (explicación paso a paso).
• Seguridad y validación: la función filtra caracteres mediante regex y usa un namespace_seguro con funciones permitidas. Si la expresión contiene caracteres no permitidos, lanza ValueError.

10. Manejo de errores

El servidor captura excepciones y las transforma en respuestas JSON-RPC o HTTP con códigos apropiados.

• En /mcp:
  • Herramienta no encontrada → error JSON-RPC con code: -32602.
  • Error de validación (ej: a == 0) → devuelve code: -32602 y mensaje claro.
  • Error interno → devuelve code: -32603 con mensaje del servidor.
• En endpoints REST:
  • Excepciones convertidas a HTTPException con status_code y detail legible.

En el flujo con Gemini, si la herramienta devuelve un error, el agente lo muestra al usuario y puede sugerir reintentar con otros argumentos.

11. Restricciones de dominio y reglas del agente

El agente sigue estrictamente las reglas solicitadas por el enunciado:

• Sólo matemáticas de nivel secundaria. Si el usuario pregunta por algo fuera de ese dominio, el agente responde con un mensaje que explica que no puede ayudar en ese tema y ofrece ejemplos de lo que sí puede hacer.
• Uso obligatorio de herramientas: cuando el usuario pide resolver una ecuación o realizar un cálculo, el agente debe invocar la herramienta adecuada.
• Botón de limpieza: la interfaz incluye un botón para limpiar el chat e iniciar una nueva conversación (implementado en el frontend). El endpoint DELETE /conversations/{id} permite borrar una conversación en el backend.

12. Cumplimiento con MCP (Model Context Protocol)

• POST /mcp implementa los métodos mínimos requeridos:
  • initialize — devuelve protocolVersion, capabilities y serverInfo.
  • tools/list — lista las herramientas disponibles (metadata).
  • tools/call — permite ejecutar una herramienta con arguments y devuelve la respuesta estructurada o un error JSON-RPC.

13. Generar requirements.txt

Esto es por si usas el repo y necesitas instalar otras dependencias, y actualizar tu txt:

Desde el entorno virtual activado:

pip freeze > requirements.txt