UJI Academic Server

Servidor HTTP del Model Context Protocol (MCP) que expone la información académica de la Universitat Jaume I (UJI). Permite consultar asignaturas, titulaciones, ubicaciones y calendarios oficiales desde clientes MCP compatibles y desde integraciones HTTP sencillas.

✨ Características clave

• 🎓 Acceso unificado a datos académicos (asignaturas, estudios, ubicaciones y horarios)
• 🌐 Soporte multiidioma cuando la API lo proporciona (catalán, español e inglés)
• ⚡ Caché en memoria para reducir llamadas repetidas a la API de la UJI
• 🧰 Ocho herramientas MCP listas para usar y compatibles con MCP Inspector
• 🛡️ Modelos Pydantic y manejo consistente de errores para clientes remotos

🏗️ Arquitectura

El servidor MCP UJI Academic actúa como intermediario entre clientes MCP compatibles y la API pública de la Universitat Jaume I, facilitando el acceso a datos académicos a través del protocolo JSON-RPC 2.0.

sequenceDiagram
    participant Cliente as Cliente MCP<br/>(Claude Desktop, VS Code, etc.)
    participant Servidor as Servidor MCP<br/>UJI Academic
    participant API as API UJI

    Cliente->>Servidor: Conectar a /mcp (HTTP)
    Servidor-->>Cliente: Confirmación de conexión

    Cliente->>Servidor: Llamada a herramienta<br/>(e.g., get_subjects)
    activate Servidor
    Servidor->>API: Consulta datos académicos<br/>(GET /api/subjects)
    API-->>Servidor: Respuesta JSON con datos
    Servidor-->>Cliente: Resultado de la herramienta
    deactivate Servidor

    Note over Cliente,Servidor: Comunicación vía JSON-RPC 2.0 sobre HTTP
    Note over Servidor,API: Comunicación HTTP con caché en memoria

🚀 Inicio rápido

1. Instala dependencias: git clone <repository-url> && cd MCP_UJI_academic && uv sync
2. Ejecuta el servidor: uv run start_server.py --host 127.0.0.1 --port 8084
3. Conecta un cliente MCP: Usa la URL http://127.0.0.1:8084/mcp en tu cliente MCP preferido (ver sección "🤖 Conectar clientes MCP").

Para Docker: docker compose up y conecta a http://localhost:8084/mcp.

🧱 Requisitos previos

• Python 3.12 o superior
• uv instalado como gestor de dependencias
• Acceso a internet para consultar la API pública de la UJI
• (Opcional) Docker y Docker Compose para ejecución contenerizada

🚀 Instalación y configuración

git clone <repository-url>
cd MCP_UJI_academic
uv sync

▶️ Ejecución del servidor

Nota: El servidor debe estar corriendo antes de conectar cualquier cliente MCP. Mantén la terminal abierta o ejecuta en segundo plano.

# Desarrollo local
uv run start_server.py --host 127.0.0.1 --port 8084

# Servidor accesible desde la red
uv run start_server.py --host 0.0.0.0 --port 8084

# Desarrollo con recarga automática
uv run start_server.py --host 127.0.0.1 --port 8084 --reload

start_server.py es un lanzador que arranca mcp_server.py con los parámetros indicados. Si prefieres usar directamente Python, ejecuta python start_server.py.

🐳 Ejecución con Docker

Nota: Asegúrate de que el contenedor esté corriendo antes de conectar clientes MCP. El servidor estará disponible en http://localhost:8084.

Construir y ejecutar la imagen manualmente

docker build -t mcp-uji-academic .
docker run --rm -p 8084:8084 mcp-uji-academic

La API quedará disponible en http://localhost:8084. Puedes detener el contenedor con Ctrl+C o usando docker stop si lo ejecutas en segundo plano.

Orquestación con Docker Compose

# Levantar el servicio
docker compose up

# Levantar en segundo plano
docker compose up -d

# Detener y limpiar
docker compose down

El archivo docker-compose.yml expone el puerto 8084. Ajusta el mapeo si necesitas servirlo en otro puerto host (por ejemplo - "9090:8084").

🌐 Endpoints HTTP principales

Método	Ruta	Descripción
GET	/	Información básica del servidor
GET	/health	Comprobación rápida de estado
GET	/tools	Lista de herramientas MCP y sus esquemas de entrada
POST	/mcp	Endpoint MCP JSON-RPC 2.0 para clientes compatibles

Servidor remoto de referencia

• URL base: http://<IP_SERVIDOR_REMOTO>:8084
• Endpoint MCP: http://<IP_SERVIDOR_REMOTO>:8084/mcp
• Health check: http://<IP_SERVIDOR_REMOTO>:8084/health

Sustituye la IP por la de tu despliegue cuando publiques el servidor en otro host.

🧰 Herramientas MCP disponibles

Herramienta	Datos que devuelve	Parámetros principales
get_subjects	Listado paginado de asignaturas	start, limit, full
search_subjects	Búsqueda por código o nombre de asignaturas	query, language
get_degrees	Catálogo completo de titulaciones	full
search_degrees	Búsqueda de titulaciones	query, language
get_locations	Ubicaciones (edificios, aulas, laboratorios)	full
search_locations	Búsqueda de ubicaciones	query
get_class_schedule	Horario lectivo en formato iCalendar	year, degree_id
get_exam_schedule	Calendario de exámenes en formato iCalendar	year, degree_id

Todas las herramientas devuelven JSON estructurado y, cuando procede, información en múltiples idiomas.

🤖 Conectar clientes MCP

Importante: El servidor MCP debe estar corriendo (localmente o en Docker) antes de conectar cualquier cliente. Verifica con curl http://127.0.0.1:8084/health o curl http://localhost:8084/health para Docker.

Recomendaciones generales

• El endpoint MCP habla JSON-RPC 2.0 sobre HTTP; cualquier cliente compatible puede usarlo.
• Asegúrate de que el puerto (8084 por defecto) esté accesible desde tu máquina o túnel SSH.
• Para entornos públicos, añade autenticación o proxies seguros según tus políticas.
• Si usas Docker localmente: el servidor estará disponible en http://localhost:8084/mcp. Asegúrate de que el contenedor esté corriendo antes de conectar clientes.

MCP Inspector (npx)

npx @modelcontextprotocol/inspector

1. Abre el navegador (suele abrir http://localhost:3000).
2. Selecciona Streamable HTTP como transporte.
3. Introduce la URL del endpoint (http://127.0.0.1:8084/mcp si usas Docker localmente, o http://<IP_SERVIDOR_REMOTO>:8084/mcp para el servidor remoto).
4. Pulsa Connect y prueba cualquiera de las ocho herramientas disponibles.

VS Code (extensión MCP)

Añade al settings.json del usuario o del workspace:

{
  "mcp.servers": {
    "mcp-uji-academic": {
      "transport": "http",
      "url": "http://127.0.0.1:8084/mcp"
    }
  }
}

Si usas un túnel SSH:

ssh -L 8084:localhost:8084 usuario@IP_SERVIDOR_REMOTO

Y cambia la URL a http://127.0.0.1:8084/mcp.

Claude Desktop

Claude Desktop no puede llamar a un servidor HTTP remoto por sí mismo: solo lanza comandos locales. Por eso necesitas que el servidor MCP esté disponible en tu máquina antes de arrancar Claude.

Añade a tu claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-uji-academic": {
      "command": "uv",
      "args": [
        "run",
        "start_server.py",
        "--host",
        "127.0.0.1",
        "--port",
        "8084"
      ],
      "cwd": "/ruta/completa/a/MCP_UJI_academic"
    }
  }
}

• Ajusta cwd a la ruta real del proyecto.
• El comando dentro de args debe ir en una sola línea; JSON no admite saltos manuales (\) dentro de strings.
• Reinicia Claude Desktop tras modificar el archivo para que recargue la configuración.

npx @modelcontextprotocol/inspector es una herramienta de testing. VS Code y Claude necesitan configuraciones JSON propias.

🧪 Pruebas y verificación

# Test de integración (arranca el servidor temporalmente y verifica endpoints)
# Asegúrate de que el puerto 8084 esté libre antes de ejecutar
uv run python integration_test.py

# Checks manuales rápidos
curl http://127.0.0.1:8084/health
curl -X POST http://127.0.0.1:8084/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "ping"}'

📁 Estructura del proyecto

MCP_UJI_academic/
├── api_client.py       # Cliente HTTP con caché y parseo iCalendar
├── integration_test.py # Prueba de arranque y endpoints HTTP
├── mcp_server.py       # FastAPI con endpoints HTTP y MCP JSON-RPC
├── models.py           # Modelos Pydantic para datos académicos
├── start_server.py     # Lanzador de conveniencia
├── pyproject.toml      # Configuración y dependencias
└── README.md           # Documentación (este archivo)

🛠️ Resolución de problemas

Problema	Cómo solucionarlo
Puerto 8084 ocupado	lsof -i :8084 para identificar el proceso. Mata el proceso o usa --port 8001 para cambiar el puerto.
Timeout o conexión rechazada	Verifica que el servidor esté corriendo con curl http://<host>:8084/health. Comprueba firewall o túnel SSH.
Dependencias inconsistentes con uv	Ejecuta uv sync --reinstall para reinstalar dependencias.
Errores de la API pública de la UJI	Revisa los logs del servidor; la API puede ser lenta o intermitente. Reintenta más tarde.
Docker: contenedor no responde	Asegúrate de que el puerto esté mapeado correctamente (-p 8084:8084). Usa docker logs <container_id> para ver logs.
Claude Desktop no conecta	Verifica que el comando en claude_desktop_config.json sea correcto y que cwd apunte a la ruta del proyecto. Reinicia Claude.

🌍 API externa usada

• Base URL: https://ujiapps.uji.es/lod-autorest/api/
• Datos disponibles: asignaturas, estudios, ubicaciones y calendarios en JSON/iCalendar

📄 Licencia y soporte

• Licencia: MIT
• ¿Dudas o incidencias? Abre un issue, revisa la tabla de solución de problemas o ejecuta el test de integración antes de reportar.

---

Proyecto creado para facilitar el acceso programático a la información académica de la UJI dentro del ecosistema MCP. ¡Aprovecha y automatiza tus flujos educativos!