fich-mcp

   ██████╗       ███████╗ ██╗  ██████╗ ██╗  ██╗
 ██╔════██╗      ██╔════╝ ██║ ██╔════╝ ██║  ██║
 █████████║█████╗█████╗   ██║ ██║      ███████║
 ██╔══════╝╚════╝██╔══╝   ██║ ██║      ██╔══██║
 ╚███████╗       ██║      ██║ ╚██████╗ ██║  ██║
  ╚══════╝       ╚═╝      ╚═╝  ╚═════╝ ╚═╝  ╚═╝

e-FICH · Plataforma educativa · MCP

Compañero local y de solo lectura para el e-FICH (Moodle de la FICH-UNL), expuesto como servidor MCP para que Claude, ChatGPT/Codex o cualquier cliente MCP puedan consultar tus cursos, anuncios, fechas y apuntes.

⚠️ Seguridad primero

El e-FICH corre sobre HTTP, no HTTPS. Cualquiera con acceso a la red puede leer o modificar tus credenciales y tu token de sesión en tránsito. Este proyecto no puede hacer que HTTP sea seguro; solo puede minimizar la exposición. Corré fich-mcp init únicamente desde una red de confianza, después de leer y aceptar explícitamente esa advertencia.

• Las credenciales se ingresan solo en el prompt de terminal que abre fich-mcp init: nunca las pegues en un chat, en un argumento de herramienta MCP, ni las dejes en el historial de la shell o en un archivo de configuración.

• El servidor es de solo lectura contra Moodle. El token se guarda en un archivo de configuración local con permisos restringidos al usuario, y cada cuenta tiene su propio cache aislado.

• El texto, HTML, PDFs e imágenes que se recuperan de tus cursos son material no confiable: tu cliente MCP o proveedor de modelo puede procesarlo, así que evitá pedir material sensible si eso no es aceptable para el proveedor que usás.

Related MCP server: dutic-mcp

Qué hace

• Mantiene un cache local por cuenta de las materias que elijas, con seguimiento de cambios.

• Indexa PDFs (texto nativo y, si están Poppler/Tesseract, OCR en español e inglés) para buscar dentro de los apuntes.

• Expone todo por MCP para que tu asistente conteste "¿qué hay para la próxima clase?" sin que vos tengas que entrar al aula virtual.

Capturas

En acción

Tres consultas reales resueltas por MCP, sin entrar al aula virtual: qué preparar para el próximo laboratorio de Física, novedades del parcial de Bases de Datos, y carga automática de fechas de examen en Google Calendar.

Requisitos

Los dos últimos son opcionales: sin ellos, fich-mcp sigue funcionando con el texto nativo de los PDFs, pero no puede leer páginas escaneadas como imagen. Verificalos en cualquier momento con fich-mcp doctor.

Instalación

# Dependencias del sistema (Debian/Ubuntu; ajustá al gestor de paquetes de tu distro)
sudo apt update
sudo apt install -y python3.12 python3.12-venv poppler-utils tesseract-ocr \
    tesseract-ocr-spa tesseract-ocr-eng

git clone https://github.com/Equisdo/fich-mcp.git
cd fich-mcp
python3.12 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

# Poné el ejecutable del venv en el PATH (una sola vez; ~/.local/bin debe estar en tu PATH)
ln -sf "$(pwd)/.venv/bin/fich-mcp" ~/.local/bin/fich-mcp

fich-mcp doctor

# Dependencias del sistema vía Homebrew
brew install python@3.12 poppler tesseract tesseract-lang

git clone https://github.com/Equisdo/fich-mcp.git
cd fich-mcp
python3.12 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

# Poné el ejecutable del venv en el PATH (una sola vez; ~/.local/bin debe estar en tu PATH)
ln -sf "$(pwd)/.venv/bin/fich-mcp" ~/.local/bin/fich-mcp

fich-mcp doctor

El menú guiado (fich-mcp tui) es un script de bash, así que la vía recomendada es WSL2 — ahí seguís exactamente los pasos de Linux de arriba.

# Instalar WSL2 (una sola vez, PowerShell como administrador)
wsl --install -d Ubuntu

Después de reiniciar, abrí la terminal de Ubuntu y seguí la sección 🐧 Linux.

Sin WSL2, el paquete y el CLI (init, doctor, courses, sync, serve, configure) también corren en PowerShell nativo — lo único que no tenés es el menú guiado:

git clone https://github.com/Equisdo/fich-mcp.git
cd fich-mcp
py -3.12 -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .

fich-mcp doctor

Para OCR en Windows nativo instalá Poppler y Tesseract con winget o Chocolatey y confirmá que queden en el PATH con fich-mcp doctor.

gum — la cara linda del menú

scripts/fich-menu.sh usa gum para los menúes, spinners y confirmaciones con color. Si no está instalado, el menú cae solo a una versión en bash plano — funciona igual, sin la estética. Instalarlo es opcional pero recomendado:

Debian/Ubuntu:

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | \
    sudo tee /etc/apt/sources.list.d/charm.list
sudo apt update && sudo apt install gum

Fedora/RHEL:

echo '[charm]
name=Charm
baseurl=https://repo.charm.sh/yum/
enabled=1
gpgcheck=1
gpgkey=https://repo.charm.sh/yum/gpg.key' | sudo tee /etc/yum.repos.d/charm.repo
sudo rpm --import https://repo.charm.sh/yum/gpg.key
sudo yum install gum

Para forzar el menú plano aunque gum esté instalado (útil en una terminal sin colores):

FICH_MENU_NO_GUM=1 fich-mcp tui

Primer uso

fich-mcp init                 # login solo por terminal; pide aceptar el riesgo de HTTP
fich-mcp doctor               # diagnóstico de dependencias locales y cuenta cacheada
fich-mcp courses --select     # elegir qué materias sincronizar
fich-mcp sync                 # traer metadata e indexar PDFs de forma resumible
fich-mcp sync --force-ocr     # reintentar páginas de PDF con OCR
fich-mcp serve                # levantar el servidor MCP por stdio
fich-mcp tui                  # abrir el menú guiado

Menú guiado

Un único punto de entrada interactivo para sesión, selección de materias, sincronización, registro de clientes MCP y diagnóstico:

fich-mcp tui
# o, corriendo desde el repo sin instalar:
bash scripts/fich-menu.sh

El menú nunca lee tu usuario ni tu contraseña: eso es responsabilidad exclusiva de init, que es quien muestra la advertencia de HTTP, pide el consentimiento y pregunta la contraseña.

Conectar un cliente MCP

Todos los clientes soportados hablan con fich-mcp de la misma forma: como un subproceso local por stdio, lanzado con fich-mcp serve. No hay puerto ni listener de red, y no hay ningún token que tipear en la configuración del cliente — las credenciales de FICH quedan en el cache aislado por cuenta, nunca en un archivo de config de cliente.

fich-mcp configure claude           # Claude Code (alcance de usuario, vía el CLI `claude`)
fich-mcp configure codex            # ChatGPT desktop + Codex CLI + extensión de Codex para IDE
                                     #   (comparten ~/.codex/config.toml)
fich-mcp configure claude-desktop   # Claude Desktop (mergea claude_desktop_config.json)
fich-mcp configure all              # los tres de una; que falle uno no bloquea a los demás

Cada uno es idempotente y no pisa nada ajeno: si volvés a correrlo imprime already_configured cuando la entrada ya apunta a este ejecutable, y se niega (*_configuration_conflict) en vez de sobrescribir una entrada fich que apunte a otra cosa. Reiniciá el cliente después para que tome el servidor nuevo.

claude-desktop detecta solo la ubicación de claude_desktop_config.json según tu sistema operativo:

Para una instalación no estándar (Flatpak, Claude portable, etc.) podés forzar la ruta con fich-mcp configure claude-desktop --config-path /ruta/al/archivo.json.

Solo Claude Code y Codex tienen CLI propia para inspeccionar servidores ya registrados antes de escribir (claude mcp get, codex mcp list --json); Claude Desktop no tiene una, así que configure claude-desktop lee y mergea el JSON directamente y deja una copia .bak al lado antes de escribir.

Para cualquier otro cliente MCP, o para ver los valores exactos antes de correr el registro automático, el menú guiado (Conectar un cliente MCP → Otro cliente) imprime tanto la forma JSON (mcpServers) como la TOML (mcp_servers) con la ruta real del ejecutable ya completada.

Concurrencia: varios clientes pueden leer al mismo tiempo, pero sync toma un lock exclusivo (writer.lock) durante todo el lote — un segundo cliente que intente sincronizar en simultáneo recibe sync_busy en vez de un cache corrupto. Es el comportamiento esperado, no un bug.

Privacidad y límites del OCR

El cache vive en las ubicaciones XDG estándar de config/cache de cada sistema, con permisos privados. Es local a la cuenta con la que hiciste init. Se prefiere siempre el texto nativo del PDF; el texto escaneado en español o inglés puede usar OCR cuando Poppler y Tesseract están disponibles. Manuscritos, ecuaciones, escaneos de baja calidad y diseños complejos son best effort y pueden tener huecos. read_document devuelve una cita de página con texto (o una imagen cuando está disponible), nunca una ruta arbitraria del sistema de archivos.

Problemas comunes

Checklist para usar contra el e-FICH real

1. Usá una cuenta de prueba si FICH ofrece una; si no, tené autorización del dueño de la cuenta.

2. Confirmá que estás en una red de confianza y aceptá el riesgo de HTTP en la terminal.

3. Corré fich-mcp init, después fich-mcp doctor y verificá soporte OCR spa/eng si lo necesitás.

4. Seleccioná solo las materias que estás autorizado a ver con fich-mcp courses --select.

5. Corré un fich-mcp sync acotado e inspeccioná errores, frescura y cobertura antes de conectar un cliente MCP.

6. Levantá fich-mcp serve en local, configurá tu cliente a propósito y nunca expongas el endpoint stdio a una red.

Contribuir

Ver CONTRIBUTING.md.

Licencia

MIT.