🎓 SISGA MCP Server

Un servidor MCP (Model Context Protocol) que permite a los docentes gestionar calificaciones, asistencia, observaciones y más funcionalidades académicas de forma natural y sencilla.

📋 Tabla de Contenidos

• Descripción General
• Instalación
• Configuración
• Desktop Extension (.dxt)
• Publicación
• Cómo Usar el Sistema
• Ejemplos de Uso Natural
• Casos de Uso Comunes
• Flujo de Trabajo Típico
• Consideraciones Importantes
• Troubleshooting y Preguntas Frecuentes

🎯 Descripción General

Este MCP permite a los docentes interactuar con el sistema SISGA de forma natural, sin necesidad de conocer códigos técnicos. Puedes:

• ✅ Iniciar sesión con tu usuario y contraseña de docente
• 📊 Calificar estudiantes usando nombres y escalas naturales
• 📅 Registrar asistencia mencionando estudiantes por nombre
• 📝 Hacer observaciones con notificaciones a padres
• 🔍 Consultar información de grupos y estudiantes
• 📋 Ver tu plan académico y grupos asignados

📦 Instalación

🚀 Para Usuarios Finales (Recomendado)

Opción 1: Uso Directo con npx (Sin instalación)

# Ejecutar directamente sin instalación
npx mcp-sisga-server

Opción 2: Instalación Global (Opcional)

# Instalar globalmente desde npm (opcional)
npm install -g mcp-sisga-server

# Verificar instalación
mcp-sisga-server --version

🛠️ Para Desarrolladores

Instalación Local para Desarrollo

# Clonar el repositorio
git clone https://github.com/tu-usuario/SISGA_AI.git
cd SISGA_AI/MCP

# Instalar dependencias
npm install

# Compilar el proyecto
npm run build

# Ejecutar en modo desarrollo
npm run dev

# Ejecutar en modo debug MAC
npx -y @modelcontextprotocol/inspector npx -y tsx ./server/main.ts

# Ejecutar en modo debug Windows
npx -y @modelcontextprotocol/inspector npx -y tsx C:\\Users\\hardv\\Documents\\Source\\SISGA_AI\\MCP\\server\\main.ts

⚙️ Configuración

🎯 Configuración para Claude Desktop

Para Usuarios Finales (desde npm)

Agrega la siguiente configuración a tu archivo de configuración de Claude:

{
  "mcpServers": {
    "sisga-server": {
      "command": "npx",
      "args": [
        "--yes",
        "--no-cache",
        "mcp-sisga-server@latest"
      ],
      "env": {}
    }
  }
}

Para Desarrolladores (desarrollo local)

Si estás desarrollando localmente, usa esta configuración:

{
  "mcpServers": {
    "sisga-server": {
      "command": "npx",
      "args": [
        "-y",
        "tsx",
        "C:\\Users\\hardv\\Documents\\Source\\SISGA_AI\\MCP\\server\\main.ts"
      ],
      "env": {}
    }
  }
}

Nota: Ajusta la ruta según tu ubicación del archivo.

🔧 Configuración para Otras Herramientas MCP

Para otras herramientas que soporten MCP, agrega esta configuración:

{
  "mcpServers": {
    "sisga-server": {
      "command": "npx",
      "args": [
        "--yes",
        "--no-cache",
        "mcp-sisga-server@latest"
      ],
      "env": {}
    }
  }
}

📍 Ubicación del Archivo de Configuración de Claude

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

🎯 Desktop Extension (.dxt)

📦 ¿Qué es una Desktop Extension?

Las Desktop Extensions (.dxt) son paquetes que permiten instalar servidores MCP en Claude Desktop con un solo clic, sin necesidad de configuración manual. Esto hace que la instalación sea mucho más sencilla para los usuarios finales.

🚀 Ventajas de usar Desktop Extension

• ✅ Instalación con un clic - No requiere configuración manual
• ✅ Sin dependencias externas - Todo está incluido en el paquete
• ✅ Actualización automática - Se actualiza automáticamente
• ✅ Sin rutas estáticas - Funciona en cualquier sistema
• ✅ Validación automática - Claude verifica la integridad del paquete

🛠️ Generar Desktop Extension (.dxt)

Paso 1: Instalar las herramientas DXT

# Instalar las herramientas DXT globalmente
npm install -g @anthropic-ai/dxt

# Verificar instalación
dxt --version

Paso 2: Preparar el proyecto

# Asegúrate de estar en el directorio MCP
cd SISGA_AI/MCP

# Compilar el proyecto TypeScript
npm run build

# Verificar que el archivo dist/main.js existe
ls dist/

Paso 3: Verificar el manifest.json

Asegúrate de que el archivo manifest.json esté configurado correctamente:

{
  "dxt_version": "0.1",
  "display_name": "SISGA ACADEMIC DOCENTES",
  "name": "sisga-mcp-extension",
  "version": "1.0.2",
  "description": "Servidor MCP para integración con el sistema SISGA Academic...",
  "author": {
    "name": "SISGA"
  },
  "icon": "icon.png",
  "server": {
    "type": "node",
    "entry_point": "dist/main.js",
    "mcp_config": {
      "command": "node",
      "args": ["${__dirname}/dist/main.js"],
      "env": {}
    }
  }
}

Paso 4: Empaquetar la extensión

# Generar el archivo .dxt
dxt pack

# Verificar que se generó el archivo
ls *.dxt

Salida esperada:

Validating manifest...
Manifest is valid!

📦  [email protected]
Archive Details
name: sisga-mcp-extension
version: 1.0.2
filename: sisga-mcp-extension-1.0.2.dxt
package size: 10.2MB
unpacked size: 35.3MB
shasum: 51688a54309faca009b3fbed245ac16b2b713156
total files: 1222
ignored (.dxtignore) files: 836

Output: C:\Users\hardv\Documents\Source\SISGA_AI\MCP\sisga-mcp-extension-1.0.2.dxt

📱 Instalar Desktop Extension en Claude

Método 1: Arrastrar y soltar

1. Abre Claude Desktop
2. Ve a Settings → Extensions
3. Arrastra el archivo .dxt a la ventana de Claude
4. Haz clic en "Install"

Método 2: Doble clic

1. Haz doble clic en el archivo .dxt
2. Se abrirá automáticamente en Claude Desktop
3. Haz clic en "Install"

🔄 Actualizar Desktop Extension

Para generar una nueva versión:

# 1. Actualizar la versión en manifest.json
# 2. Compilar el proyecto
npm run build

# 3. Empaquetar la nueva versión
dxt pack

# 4. El archivo .dxt se actualizará automáticamente

🎨 Agregar icono personalizado

1. Crea un archivo icon.png (64x64 píxeles recomendado)
2. Agrega "icon": "icon.png" al manifest.json
3. Ejecuta dxt pack nuevamente

🐛 Solución de problemas

Error: "Manifest is invalid"

# Verificar la sintaxis del manifest.json
dxt validate manifest.json

Error: "Entry point not found"

# Verificar que el archivo existe
ls dist/main.js

# Si no existe, compilar el proyecto
npm run build

Error: "Package too large"

# Crear un archivo .dxtignore para excluir archivos innecesarios
echo "node_modules/" > .dxtignore
echo "*.log" >> .dxtignore
echo "coverage/" >> .dxtignore

📤 Publicación en NPM

🚀 Publicar en npm (Para Desarrolladores)

Paso 1: Preparar el Proyecto

# Asegúrate de estar en el directorio MCP
cd MCP

# Verificar que todo compile correctamente
npm run build

# Ejecutar las pruebas (si las hay)
npm test

Paso 2: Iniciar Sesión en npm (Solo la Primera Vez)

# Iniciar sesión en npm
npm login

# Sigue las instrucciones y coloca tu:
# - Usuario de npm
# - Contraseña
# - Correo electrónico
# - Código 2FA (si está habilitado)

Paso 3: Primera Publicación

# Publicar en npm con acceso público
npm publish --access public

# Verificar que el paquete esté disponible
npm view mcp-sisga-server

🔄 Publicar Nuevas Versiones NPM

Método 1: Actualización Manual de Versión

BORRA LA CARPETA dist

cd MCP

# 1. Actualizar versión automáticamente
npm version patch    # Para correcciones de bugs (1.0.1 -> 1.0.2)
npm version minor    # Para nuevas características (1.0.1 -> 1.1.0)
npm version major    # Para cambios incompatibles (1.0.1 -> 2.0.0)

# 2. Hacer cambios en el código
# 3. Compilar el proyecto
npm run build


# 4. Publicar la nueva versión
npm publish

# 5. Verificar la publicación
npm view mcp-sisga-server

Método 2: Actualización Automática con npm version (Recomendado)

# 1. Hacer cambios en el código
# 2. Compilar el proyecto
npm run build

# 3. Actualizar versión automáticamente
npm version patch    # Para correcciones de bugs (1.0.1 -> 1.0.2)
npm version minor    # Para nuevas características (1.0.1 -> 1.1.0)
npm version major    # Para cambios incompatibles (1.0.1 -> 2.0.0)

# 4. Publicar la nueva versión
npm publish

# 5. Subir los cambios a Git (incluyendo el tag)
git push origin main
git push origin --tags

Método 3: Flujo Completo con Git

# 1. Hacer cambios en el código
# Editar archivos, agregar funcionalidades, corregir bugs

# 2. Commit de los cambios
git add .
git commit -m "feat: agregar nueva funcionalidad de reportes"

# 3. Compilar el proyecto
npm run build

# 4. Actualizar versión y crear tag
npm version patch  # o minor/major según corresponda

# 5. Publicar en npm
npm publish

# 6. Subir cambios a GitHub
git push origin main
git push origin --tags

📋 Tipos de Versiones (Semantic Versioning)

| Tipo | Cuándo Usar | Comando | Ejemplo | |------|-------------|---------|---------| | patch | Correcciones de bugs, pequeños ajustes | npm version patch | 1.0.1 → 1.0.2 | | minor | Nuevas funcionalidades, cambios compatibles | npm version minor | 1.0.1 → 1.1.0 | | major | Cambios incompatibles, refactorización | npm version major | 1.0.1 → 2.0.0 |

🔄 Publicación Automática con GitHub Actions

El proyecto incluye un workflow de GitHub Actions que publica automáticamente cuando se crea un tag:

# Crear un tag para activar la publicación automática
git tag v1.0.2
git push origin v1.0.2

Configuración requerida en GitHub:

1. Ve a tu repositorio en GitHub
2. Settings → Secrets and variables → Actions
3. Agregar secret: NPM_TOKEN con tu token de npm

Generar NPM Token:

# Generar token en npm
npm token create --read-only=false

📋 Verificar la Publicación

# Verificar que el paquete esté disponible
npm view mcp-sisga-server

# Ver todas las versiones publicadas
npm view mcp-sisga-server versions --json

# Probar la nueva versión
npx mcp-sisga-server@latest

# Verificar con el inspector MCP
npx -y @modelcontextprotocol/inspector npx -y mcp-sisga-server@latest

🚨 Solución de Problemas en Publicación

Error: "You cannot publish over the previously published versions"

# Verificar la versión actual
npm view mcp-sisga-server version

# Actualizar a una versión superior
npm version patch
npm publish

Error: "Package name too similar to existing packages"

# Cambiar el nombre en package.json si es necesario
{
  "name": "@tu-usuario/mcp-sisga-server"
}

# Publicar con scope
npm publish --access public

Error: "You must be logged in to publish packages"

# Verificar si estás logueado
npm whoami

# Si no estás logueado
npm login

📈 Mejores Prácticas para Publicación

1. ✅ Siempre compila antes de publicar

   npm run build

2. ✅ Usa semantic versioning

   • patch: bugs
   • minor: features
   • major: breaking changes

3. ✅ Actualiza el README con cambios importantes

4. ✅ Prueba localmente antes de publicar

   npx -y @modelcontextprotocol/inspector node dist/main.js

5. ✅ Usa tags descriptivos en Git

   git tag -a v1.0.2 -m "Agregar funcionalidad de reportes"

6. ✅ Mantén un CHANGELOG.md

   ## [1.0.2] - 2024-06-27
   ### Added
   - Nueva funcionalidad de reportes
   ### Fixed
   - Corrección en el login

🚀 Cómo Usar el Sistema

🔐 Paso 1: Iniciar Sesión

Siempre comienza iniciando sesión con tus credenciales de docente:

Inicia sesión con el usuario "tu_usuario" y contraseña "tu_contraseña"

📊 Paso 2: Calificar Estudiantes

Puedes calificar de forma natural mencionando estudiantes por nombre:

Califica con 8.5 a Mariana Ramírez en la evaluación "Salida al tablero" de Ética, Quinto grado, Periodo 1

Pon calificación "DB" (Desempeño Básico) a Esteban Hurtado y Ana Rincón en la evaluación "Exposición" de Ciencias Naturales, Grado 8B, Periodo 2

📅 Paso 3: Registrar Asistencia

Registra faltas, retardos o ausencias justificadas:

Pon inasistencia a Juan Martínez y Pablo Cadavid el día de hoy en Matemáticas

Registra retardo a María González en la clase de Historia del lunes pasado

Pon falta justificada a Carlos López en Ciencias Naturales con observación "Cita médica"

📝 Paso 4: Hacer Observaciones

Registra observaciones conductuales o académicas:

Pon una observación a Ana Rincón: "Felicitaciones, lo estás haciendo muy bien en el periodo 3". Notifica por email y SMS

Haz una observación a todo el grupo 8B: "Excelente trabajo en equipo en el proyecto de ciencias"

🎯 Ejemplos de Uso Natural

📚 Calificaciones Numéricas

# Calificación individual
Califica con 9.0 a Sofía Morales en la evaluación "Examen parcial" de Matemáticas, Grado 7A, Periodo 1

# Calificación masiva
Pon calificación 8.5 a todos los estudiantes del Grado 8B en la evaluación "Exposición" de Ciencias Naturales

# Calificación con observación
Califica con 7.8 a Diego Ramírez en "Trabajo en clase" de Historia, Periodo 2, con observación "Mejorar participación"

📈 Calificaciones Cualitativas

# Usando escalas naturales
Califica con "A" (Avanzado) a Camila Torres en "Participación" de Ética, Grado 6A, Periodo 1

# Calificación masiva cualitativa
Pon calificación "DB" (Desempeño Básico) a los estudiantes Juan Pérez, María López y Carlos García en "Trabajo en equipo" de Ciencias Naturales, Grado 7B

# Con observación
Califica con "B" (Básico) a Andrés Morales en "Comportamiento" de Matemáticas, Periodo 3, observación "Necesita mejorar disciplina"

📅 Gestión de Asistencia

# Faltas individuales
Pon falta a Laura Jiménez en la clase de Historia del día de hoy

# Faltas masivas
Registra inasistencia a Pedro Sánchez, Ana García y Luis Torres en Matemáticas para el lunes pasado

# Retardos
Pon retardo a Daniela Ruiz en Ciencias Naturales del miércoles

# Faltas justificadas
Registra falta justificada a Roberto Mendoza en Ética con observación "Cita médica familiar"

# Asistencia semanal
Pon falta a todo el grupo 8A en la clase de Historia del viernes pasado

📝 Observaciones Conductuales

# Observación positiva individual
Pon una observación a Valentina Herrera: "Excelente liderazgo en el proyecto de ciencias, felicitaciones". Notifica por email

# Observación masiva
Haz observación a los estudiantes del Grado 7B: "Muy buen comportamiento durante la salida pedagógica". Notifica por email y SMS

# Observación de mejora
Pon observación a Santiago López: "Ha mejorado notablemente su participación en clase, continúa así". Periodo 2

# Observación conductual
Registra observación a todo el grupo 6A: "Necesitan mejorar el respeto hacia los compañeros durante las clases"

🔄 Casos de Uso Comunes

📊 Evaluación Completa de Periodo

1. Inicia sesión con usuario "profesor_matematicas" y contraseña "mi_contraseña"
2. Califica con 9.0 a los estudiantes destacados del Grado 8A en "Examen parcial" de Matemáticas, Periodo 1
3. Pon calificación "A" a los mismos estudiantes en "Participación en clase"
4. Registra falta a los estudiantes que no asistieron a la evaluación
5. Haz observación positiva a los estudiantes con mejor rendimiento: "Excelente desempeño en el periodo"

📅 Gestión Semanal de Asistencia

1. Inicia sesión con usuario "profesor_ciencias" y contraseña "mi_contraseña"
2. Registra falta a María González y Carlos Ruiz en Ciencias Naturales del lunes
3. Pon retardo a Juan Pérez en la clase del martes
4. Registra falta justificada a Ana López del miércoles con observación "Cita médica"
5. Haz observación conductual a todo el grupo: "Mejorar puntualidad en las clases"

📝 Seguimiento de Estudiantes

1. Inicia sesión con usuario "profesor_etica" y contraseña "mi_contraseña"
2. Califica con "A" a los estudiantes del Grado 7B en "Valores y convivencia", Periodo 2
3. Pon observación positiva a Diego Ramírez: "Excelente ejemplo de compañerismo"
4. Registra observación de mejora a Laura Torres: "Ha mejorado su comportamiento, continúa así"
5. Notifica por email a los padres de los estudiantes destacados

🔄 Flujo de Trabajo Típico

1. Inicio de Sesión

Inicia sesión con usuario "tu_usuario" y contraseña "tu_contraseña"

2. Verificar Información

Muéstrame mi información de usuario
Muéstrame mi plan académico

3. Consultar Referencias

Muéstrame las escalas de calificación disponibles
Muéstrame los tipos de observación disponibles

4. Realizar Tareas

# Ejemplos de tareas naturales
Califica con 8.5 a Juan Pérez en Matemáticas
Pon falta a María López en Historia
Haz observación positiva a Ana García

5. Verificar Resultados

# Los mensajes de confirmación aparecen automáticamente

6. Cerrar Sesión

Cierra la sesión

⚠️ Consideraciones Importantes

🔐 Seguridad

• Credenciales: Usa tus credenciales reales de docente
• Sesiones: Cierra sesión al terminar de trabajar
• Privacidad: No compartas información de estudiantes

📅 Fechas

• Hoy: El sistema entiende "hoy", "ayer", "mañana"
• Fechas específicas: Usa formato natural como "15 de junio" o "2024-06-15"
• Periodos: Menciona el periodo (1, 2, 3, 4) cuando sea necesario

📊 Calificaciones

• Numéricas: Usa escalas de 0 a 10 (ejemplo: 8.5, 9.0)
• Cualitativas: Usa escalas como "A" (Avanzado), "B" (Básico), "DB" (Desempeño Básico)
• Observaciones: Incluye comentarios constructivos

👥 Estudiantes

• Nombres: Usa nombres completos de los estudiantes
• Grupos: Menciona el grado y grupo (ejemplo: "Grado 8A", "Quinto B")
• Asignaturas: Usa nombres naturales de las materias

📝 Observaciones

• Tipos: El sistema te mostrará los tipos disponibles
• Notificaciones: Puedes enviar por email, SMS o ambos
• Descripción: Sé específico y constructivo

🔄 Operaciones Masivas

• Grupos completos: Puedes calificar o registrar asistencia a todo un grupo
• Múltiples estudiantes: Menciona varios nombres en una sola instrucción
• Confirmación: El sistema te mostrará el resultado de cada operación

🔧 Troubleshooting y Preguntas Frecuentes

❓ Preguntas Frecuentes

¿Cómo sé si el servidor MCP está funcionando correctamente?

# Verificar que npx puede ejecutar el paquete
npx mcp-sisga-server --help

# Si instalaste globalmente
mcp-sisga-server --version

# Verificar que el comando esté disponible (solo si instalaste globalmente)
which mcp-sisga-server  # En Linux/macOS
where mcp-sisga-server  # En Windows

¿Qué hago si Claude no reconoce el servidor MCP?

1. Verifica la configuración:

   • Asegúrate de que el archivo de configuración esté en la ubicación correcta
   • Verifica que la sintaxis JSON sea válida
   • Reinicia Claude Desktop después de cambiar la configuración

2. Verifica que npx funcione:

   # Probar que npx puede ejecutar el paquete
   npx mcp-sisga-server --help
      
   # Si instalaste globalmente
   npm list -g mcp-sisga-server

¿Puedo usar el servidor sin instalarlo globalmente?

Sí, puedes usar npx para ejecutarlo directamente:

# Ejecutar sin instalación
npx mcp-sisga-server

Y configurar Claude así:

{
  "mcpServers": {
    "sisga-server": {
      "command": "npx",
      "args": [
        "--yes",
        "--no-cache",
        "mcp-sisga-server@latest"
      ],
      "env": {}
    }
  }
}

¿Cómo actualizo el servidor a una nueva versión?

# Con npx siempre obtiene la última versión automáticamente
npx mcp-sisga-server

# Si instalaste globalmente
npm update -g mcp-sisga-server

🐛 Problemas Comunes y Soluciones

Error: "Command not found: mcp-sisga-server"

Solución:

# Usar npx (recomendado)
npx mcp-sisga-server

# O reinstalar globalmente si prefieres
npm uninstall -g mcp-sisga-server
npm install -g mcp-sisga-server

Error: "Cannot find module 'mcp-sisga-server'"

Solución:

# Verificar que el paquete esté disponible en npm
npm view mcp-sisga-server

# Limpiar cache de npx
npx clear-npx-cache

# Intentar nuevamente
npx mcp-sisga-server

Error: "Permission denied" al instalar globalmente

Solución:

# En Windows (ejecutar PowerShell como administrador)
npm install -g mcp-sisga-server

# En Linux/macOS
sudo npm install -g mcp-sisga-server

# O cambiar el directorio de npm
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH

Claude no se conecta al servidor MCP

Solución:

1. Verifica que el servidor esté ejecutándose
2. Revisa los logs de Claude Desktop
3. Asegúrate de que la configuración sea correcta
4. Reinicia Claude Desktop

Error de autenticación con SISGA

Solución:

1. Verifica que tus credenciales sean correctas
2. Asegúrate de que tu cuenta tenga permisos de docente
3. Verifica que la API de SISGA esté disponible
4. Intenta iniciar sesión nuevamente

🔍 Logs y Debugging

Habilitar logs detallados

Para desarrollo local, puedes agregar más logs en main.ts:

// Agregar logs de debug
console.log('Debug:', { variable, otraVariable });

Verificar conectividad con SISGA

# Probar la API de SISGA directamente
curl -X GET "https://apisisga.azurewebsites.net/api/health"

Verificar configuración MCP

# Probar el servidor MCP manualmente
npx -y @modelcontextprotocol/inspector npx -y tsx ./server/main.ts

📱 Compatibilidad

Herramientas MCP Soportadas

• ✅ Claude Desktop
• ✅ Anthropic Claude Web (con configuración)
• ✅ Otras herramientas que soporten MCP

Sistemas Operativos

• ✅ Windows 10/11
• ✅ macOS 10.15+
• ✅ Linux (Ubuntu 18.04+, CentOS 7+)

Requisitos del Sistema

• Node.js >= 18.0.0
• npm >= 8.0.0
• Conexión a internet para la API de SISGA

📞 Soporte

🆘 Obtener Ayuda

1. Revisa esta documentación - La mayoría de problemas están cubiertos aquí
2. Verifica los logs - Usa las herramientas de debugging mencionadas
3. Consulta el repositorio - Busca issues similares en GitHub
4. Crea un nuevo issue - Si no encuentras solución

📧 Contacto

• Email: [email protected]
• Documentación: [Enlace a documentación completa]

Versión: 1.0.0
Última actualización: Junio 2025