Study Assistant

Un servidor local de Model Context Protocol (MCP) que convierte documentos de programas de estudio en una base de conocimiento de estudio buscable. El servidor lee documentos de files/ementas, extrae su texto y utiliza Genkit con Ollama Cloud para producir resúmenes y detalles estructurados.

Arquitectura

Este repositorio es un monorepo de pnpm. El paquete mcp contiene el servidor Express y MCP, mientras que files/ementas es el único directorio de documentos expuesto a las herramientas.

El servidor se vincula a 127.0.0.1 y expone:

• GET /health: salud del proceso sin secretos ni detalles del proveedor.

• /mcp: endpoint HTTP Streamable MCP sin estado.

• list_ementas: lista los archivos admitidos con metadatos y resúmenes en caché.

• get_ementa: devuelve el texto extraído y los detalles estructurados del programa de estudios.

Los formatos admitidos son PDF, DOCX, Markdown y texto plano. Los enlaces simbólicos, las rutas y las extensiones no admitidas se rechazan.

Related MCP server: Educational Tutor MCP Server

Requisitos

• Node.js 20 o superior.

• pnpm 10 (Corepack puede proporcionar la versión fijada).

• Una clave de API de Ollama Cloud.

Configuración

Instala las dependencias desde la raíz del repositorio:

corepack pnpm install

Copia mcp/.env.example a .env en la raíz del repositorio o a mcp/.env, y luego proporciona la clave de API:

OLLAMA_API_KEY=your-key

El modelo predeterminado es gpt-oss:120b. Los ajustes opcionales son:

OLLAMA_MODEL=gpt-oss:120b
OLLAMA_BASE_URL=https://ollama.com
OLLAMA_TIMEOUT_MS=60000
MCP_PORT=3000

Los archivos de entorno son ignorados por Git. Nunca confirmes una clave de API.

La aplicación resuelve ambas ubicaciones explícitamente, independientemente del directorio desde el que pnpm inicie el paquete. Las variables de entorno del sistema existentes tienen prioridad; cuando ambos archivos definen la misma variable, mcp/.env tiene prioridad sobre el .env raíz.

Coloca los archivos de programas de estudio directamente dentro de files/ementas y luego inicia el servidor de desarrollo:

corepack pnpm dev

El endpoint MCP estará disponible en http://127.0.0.1:3000/mcp.

Conectar Codex

Con el servidor en ejecución, registra su URL en el cliente local de Codex:

codex mcp add studyAssistant --url http://127.0.0.1:3000/mcp

Configuración equivalente de Codex:

[mcp_servers.studyAssistant]
url = "http://127.0.0.1:3000/mcp"

Este endpoint de localhost está destinado a un cliente local de Codex. No está expuesto a clientes remotos de ChatGPT.

Comandos

Ejecuta estos comandos desde la raíz del repositorio:

corepack pnpm dev       # Watch and run the TypeScript server
corepack pnpm build     # Build the production JavaScript
corepack pnpm start     # Run the compiled server
corepack pnpm typecheck # Check strict TypeScript types
corepack pnpm lint      # Run ESLint
corepack pnpm test      # Run the Vitest suite

dev y build nunca ejecutan la suite de pruebas. La compilación de producción también excluye src/__tests__, por lo que los fixtures y mocks de prueba no pueden ser cargados por el servidor ni emitidos en dist.

El análisis generado se almacena en .cache/ementas.json. Las entradas de caché se invalidan cuando cambia el tamaño o la hora de modificación de un documento. Un resultado en caché válido sigue siendo utilizable si Ollama Cloud no está disponible temporalmente.

Seguridad y comportamiento ante fallos

La clave de API se carga desde el entorno y se envía solo en el encabezado de autorización de Ollama. No se incluye en las respuestas de salud, las respuestas MCP ni los registros de la aplicación. Las solicitudes en la nube utilizan un tiempo de espera y reintentan fallos transitorios 429, 500 y 502. Un fallo en un archivo se aísla en list_ementas; get_ementa informa un error de herramienta MCP.