waseda-portal-mcp

Servidor MCP no oficial, local y de solo lectura que integra Waseda Moodle de la Universidad de Waseda, la información de clases suspendidas de MyWaseda, el Web Syllabus y el calendario académico oficial. No está afiliado a la Universidad de Waseda y no cuenta con su aprobación, garantía ni soporte.

El uso principal es que, desde el cliente MCP, se pregunte "muestra las clases y fechas límite de mañana" y se confirmen con fuentes: clases, suspensiones/cambios, fechas límite del día y tareas vencidas no entregadas.

Fuentes de datos compatibles

• Waseda Moodle: asignaturas oficiales, tipo de actividad, fechas de inicio y límite estructuradas, estado de entrega/completado

• MyWaseda suspensión de clases: suspensiones y cambios para las asignaturas en curso en la vista inicial después de iniciar sesión

• Web Syllabus: año, código de asignatura/clase, lugar de impartición, responsable, año recomendado, destinatarios y prerrequisitos publicados, día/período, aula, modalidad, resumen, plan, evaluación, descripción de exámenes

• Calendario académico oficial de la Universidad de Waseda: inicio y fin de clases, períodos de descanso, clases en festivos, suspensión de clases, períodos de exámenes

El logotipo de la universidad, capturas de pantalla, materiales, el texto completo de los sílabus obtenidos y los datos personales reales no se incluyen en el repositorio.

Requisitos y configuración

• Node.js 22 o superior

• npm

• Google Chrome instalado en el sistema

git clone https://github.com/TakeruF/waseda-portal-mcp.git
cd waseda-portal-mcp
npm install
npm run build
npm run auth

npm run auth (o waseda-portal-mcp auth tras la compilación) abre un perfil de Chrome dedicado. El usuario inicia sesión en Waseda Moodle y MyWaseda en el propio Chrome y, al final, abre "Clases → Relacionado con clases → Suspensión" en MyWaseda. Al llegar a la página de suspensiones, se confirma solo con la URL, se guarda el estado de autenticación y se cierra automáticamente el Chrome dedicado. La CLI no solicita nombre de usuario ni contraseña. No copia perfiles de Chrome existentes ni cookies de uso normal.

El perfil dedicado por defecto es ~/.waseda-portal-mcp/chrome-profile y el estado de autenticación que carga el servidor es ~/.waseda-portal-mcp/auth-state.json. Ambos están fuera del repositorio y el archivo de estado de autenticación es solo para el propietario (0600). La ubicación se puede cambiar con WASEDA_PORTAL_PROFILE_DIR y WASEDA_PORTAL_AUTH_STATE_PATH. No se puede ejecutar simultáneamente el Chrome que usa el mismo perfil dedicado y el servidor MCP.

Configuración del cliente MCP

Reemplace la ruta absoluta por su checkout real.

{
  "mcpServers": {
    "waseda-portal": {
      "command": "node",
      "args": ["/absolute/path/to/waseda-portal-mcp/dist/cli.js"]
    }
  }
}

Para deshabilitar la caché, agregue "--no-cache" a args. La salida estándar de stdio es exclusiva para el protocolo MCP; los mensajes operativos se envían a la salida de error estándar.

Herramientas

• get_day_brief: integra clases, cambios, fechas límite del día y tareas vencidas no entregadas para date (YYYY-MM-DD)

• list_courses: por defecto solo las asignaturas cuya categoría comienza con 正規科目/; includeNonRegular incluye también cursos de orientación, etc.

• list_deadlines: enumera las actividades con fecha límite dentro del rango ISO 8601 from·to. Por defecto excluye entregadas/completadas

• list_changes: enumera suspensiones y cambios dentro del rango de fechas especificado

• get_syllabus: devuelve detalles o candidatos ambiguos desde courseId o syllabusKey

• search_syllabi: busca en el Web Syllabus del año actual por nombre de asignatura o contenido, independientemente del estado de inscripción

El mode de search_syllabi es course_name si se conoce el nombre de la asignatura, o content si se busca por el contenido que se desea aprender. La búsqueda de contenido descompone el texto natural en un máximo de 3 palabras. El cliente MCP puede pasar hasta 3 términos relacionados cortos en relatedTerms para indicar el número de búsquedas y la intención de forma explícita.

{
  "query": "日本の貨幣の歴史を学びたい",
  "mode": "content",
  "relatedTerms": ["貨幣", "通貨", "経済史"],
  "maxResults": 3,
  "useAcademicProfile": true
}

Los resultados incluyen el sílabo completo, las palabras coincidentes de la búsqueda oficial, los campos que pudieron coincidir y la relevancia léxica. Si se ha configurado un perfil académico local, profileApplied será true y se adjuntará también una coincidencia orientativa de afiliación, año y prerrequisitos para cada candidato. La búsqueda de contenido no es una garantía de recomendación semántica de inscripción ni de elegibilidad.

Perfil académico local opcional

Solo se puede guardar opcionalmente, de forma predeterminada en ~/.waseda-portal-mcp/academic-profile.json, la información académica mínima que la persona declara explícitamente. No existe funcionalidad para obtener automáticamente de MyWaseda o Moodle el nombre, número de estudiante, afiliación, curso o historial de inscripción.

{
  "schemaVersion": 1,
  "affiliations": ["例示学部"],
  "academicLevel": "undergraduate",
  "year": 3,
  "completedPrerequisites": ["合成基礎科目"]
}

affiliations admite un máximo de 5 nombres oficiales de facultad o escuela de posgrado; academicLevel es undergraduate, masters, doctoral u other; year es de 1 a 6. completedPrerequisites incluye, seleccionados por la propia persona, únicamente los nombres de asignaturas o prerrequisitos que desea usar para la coincidencia, hasta un máximo de 30. Como corresponde al historial de inscripción, puede omitirlo si no es necesario.

Coloque el directorio padre en 0700 y el archivo en 0600, y manténgalo fuera del repositorio. Si el archivo no existe, se realiza la búsqueda habitual. Para usar otra ubicación, puede especificarla con WASEDA_PORTAL_ACADEMIC_PROFILE_PATH. No se leen archivos con permisos demasiado amplios ni archivos propiedad de otros usuarios.

Los valores del perfil no se copian a las respuestas MCP, registros, snapshots ni caché. Solo se emiten profileApplied y los motivos de juicio de consistent, conflict, review_required y unavailable, con los valores ocultos. En cada llamada, se puede desactivar con useAcademicProfile: false.

Las fechas y horas se mantienen en ISO 8601 y, si la página original no tiene zona horaria, se interpretan como Asia/Tokyo. Todos los resultados incluyen la URL de origen y la hora de verificación. En caso de conflicto, el orden es MyWaseda, información estructurada de Moodle, Web Syllabus y descripción libre.

Garantía de solo lectura

La obtención habitual solo realiza visualización de páginas y lectura del DOM. ReadOnlyGuard rechaza las URL conocidas de entrega de tareas, carga de archivos, respuesta a cuestionarios/encuestas, asistencia, cambio de completado, creación de eventos, publicaciones, mensajes, cambios de inscripción y las solicitudes no permitidas que no sean GET.

Solo el formulario de búsqueda oficial del Web Syllabus utiliza HTTP POST a pesar de ser una búsqueda. Por ello, solo se permite de forma restringida el POST de búsqueda en el que coincidan el host oficial, /syllabus/JAA101.php y el controlador de solo lectura JAA103SubCon. En el caso de la carga diferida de Moodle, solo se permiten los métodos conocidos de solo referencia para /lib/ajax/service.php. Las páginas de detalle se leen con GET. El flujo de autenticación ocurre en un proceso separado y el ingreso y envío de credenciales son operaciones realizadas por el propio usuario.

Calificaciones, notas, comentarios del profesorado y nombres de archivos entregados no existen en el modelo ni se incluyen en las respuestas normales. No se emite, guarda ni utiliza el token de calendario externo de Moodle.

Información personal y caché

El HTML autenticado se descarta tras el análisis en memoria y no se guarda de forma persistente. Las cookies y tokens de sesión están únicamente en el perfil dedicado y en el archivo de estado de autenticación, fuera del repositorio, y no aparecen en las respuestas MCP ni en los registros. El perfil académico opcional se lee una sola vez al inicio desde un archivo de solo propietario fuera del repositorio y no guarda los valores en las respuestas ni en la caché. Solo los datos mínimos normalizados se guardan en la memoria del proceso durante 5 minutos por defecto. El TTL se configura con WASEDA_PORTAL_CACHE_TTL_MS; se desactiva con --no-cache o WASEDA_PORTAL_CACHE=false.

Solo el mapeo confirmado courseId → syllabusKey se puede guardar en ~/.waseda-portal-mcp/cache/course-syllabus-map.json para reducir búsquedas repetidas. Esta tabla no incluye nombres de asignaturas, nombres de profesores, números de estudiantes, etc., y se actualiza atómicamente con directorio 0700 y archivo 0600. No se guardan candidatos ambiguos ni coincidencias nulas.

Todos los fixtures son datos artificiales. No pegue datos reales en issues, registros, fixtures ni salidas de pruebas. Consulte SECURITY.md para más detalles.

Errores

Se distinguen AUTH_REQUIRED, SESSION_EXPIRED, MAINTENANCE, SOURCE_UNAVAILABLE, PAGE_STRUCTURE_CHANGED, AMBIGUOUS_COURSE_MATCH, RATE_LIMITED y READ_ONLY_VIOLATION. Si desaparece un selector principal, no se trata una lista vacía como éxito; se devuelve PAGE_STRUCTURE_CHANGED. Solo se devuelve una lista vacía si se puede confirmar el contenedor legítimo de lista vacía.

Si no está autenticado, ejecute npm run auth. Si hay un cambio estructural, reproduzca la estructura DOM mínima sin información personal como fixture artificial y actualice el analizador correspondiente y la prueba del fixture. No agregue HTML sin autenticar a issues ni commits.

Desarrollo y verificación

npm test             # 外部アクセスなしの人工fixtureテスト
npm run typecheck
npm run lint
npm run format:check
npm run build
npm run test:live:auth-state     # 新規一時プロファイルでAUTH_REQUIREDを確認
npm run test:live:authenticated  # 認証必須。AUTH_REQUIRED/SESSION_EXPIREDは失敗
npm run test:live:catalog        # 公開シラバスの内容検索と科目名検索
npm run test:e2e:authenticated   # ビルド後、MCPクライアントからstdio E2E
npm run test:e2e:catalog         # search_syllabiのstdio E2E

test:live es un alias de test:live:authenticated. La verificación en vivo con autenticación está limitada a 1 ejecución simultánea, 1 segundo de intervalo entre accesos, 1 asignatura oficial, máximo 3 candidatos de sílabo y máximo 1 detalle de tarea. Si no está autenticada, falla y no se considera exitosa. El éxito de fixture, el éxito en vivo autenticado y el éxito E2E del cliente MCP se tratan como evidencias separadas.

Limitaciones conocidas

• Los cambios de DOM en Moodle, MyWaseda y Web Syllabus pueden requerir actualizaciones del analizador.

• La búsqueda de contenido es una búsqueda léxica que utiliza la búsqueda de palabras clave de todos los campos del Web Syllabus oficial. Los sinónimos o intereses abstractos se complementan con relatedTerms, limitando a un máximo de 3 búsquedas y 5 detalles.

• El juicio del perfil académico es orientativo. El año recomendado, que aparece como campo independiente en el Web Syllabus, se compara estructuralmente, pero el lugar de impartición no se considera una restricción de afiliación. Si los destinatarios, prerrequisitos, cupo o época de inscripción aparecen en descripción libre o en el reglamento de facultad, no se afirma automáticamente que se pueda cursar; se requiere confirmación de la información oficial.

• MyWaseda solo muestra la vista inicial para asignaturas cursadas; no se implementa la operación POST de la vista completa de facultad.

• Los períodos de clase se generan a partir del día/período confirmado del sílabo y del semestre/días festivos. No se afirman descripciones libres de cursos intensivos, clases complementarias o sesiones individuales.

• La coincidencia entre Moodle y el sílabo se basa en año, lugar de impartición, nombre de asignatura normalizado, clase, profesorado y, si está disponible, día/período. Si el nombre de Moodle difiere del nombre del sílabo, se obtienen candidatos hasta la cantidad máxima mediante coincidencia parcial del profesorado. Si la evidencia es débil o la diferencia entre los candidatos principales es pequeña, se devuelven solo candidatos ambiguos y no se confirman aula ni información de examen.

• Quedan excluidos: notificaciones residentes, escritura, obtención de calificaciones, descarga masiva de materiales, tokens de calendario, extensiones de Chrome, autenticación en la nube, MCP remoto y múltiples universidades.

Adaptadores para otras universidades

Lo que se comparte no es el método de obtención, sino los resultados que necesita el usuario. Primero implemente UniversityAdapter dentro del mismo paquete; los selectores, identificadores y reglas de coincidencia específicos de la universidad se colocan bajo el adaptador. La información específica se coloca en extensions. No se divide en otro paquete hasta que se confirme el límite real con la implementación de una segunda universidad. Consulte docs/architecture.md para más detalles.

Licencia

MIT