Study Assistant

A local Model Context Protocol (MCP) server that turns syllabus documents into a searchable study knowledge base. The server reads documents from files/ementas, extracts their text, and uses Genkit with Ollama Cloud to produce summaries and structured details.

Architecture

This repository is a pnpm monorepo. The mcp package contains the Express and MCP server, while files/ementas is the only document directory exposed to the tools.

The server binds to 127.0.0.1 and exposes:

• GET /health: process health without secrets or provider details.

• /mcp: stateless MCP Streamable HTTP endpoint.

• list_ementas: lists supported files with metadata and cached summaries.

• get_ementa: returns extracted text and structured syllabus details.

Supported formats are PDF, DOCX, Markdown, and plain text. Symbolic links, paths, and unsupported extensions are rejected.

Related MCP server: Educational Tutor MCP Server

Requirements

• Node.js 20 or newer.

• pnpm 10 (Corepack can provide the pinned version).

• An Ollama Cloud API key.

Setup

Install dependencies from the repository root:

corepack pnpm install

Copy mcp/.env.example to either .env in the repository root or mcp/.env, then provide the API key:

OLLAMA_API_KEY=your-key

The default model is gpt-oss:120b. Optional settings are:

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

Environment files are ignored by Git. Never commit an API key.

The application resolves both locations explicitly, regardless of the directory from which pnpm starts the package. Existing system environment variables take precedence; when both files define the same variable, mcp/.env takes precedence over the root .env.

Place syllabus files directly inside files/ementas, then start the development server:

corepack pnpm dev

The MCP endpoint will be available at http://127.0.0.1:3000/mcp.

Connect Codex

With the server running, register its URL in the local Codex client:

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

Equivalent Codex configuration:

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

This localhost endpoint is intended for a local Codex client. It is not exposed to remote ChatGPT clients.

Commands

Run these commands from the repository root:

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 and build never run the test suite. Production compilation also excludes src/__tests__, so test fixtures and mocks cannot be loaded by the server or emitted into dist.

Generated analysis is stored in .cache/ementas.json. Cache entries are invalidated when a document's size or modification time changes. A valid cached result remains usable if Ollama Cloud is temporarily unavailable.

Security and failure behavior

The API key is loaded from the environment and sent only in the Ollama authorization header. It is not included in health responses, MCP responses, or application logs. Cloud requests use a timeout and retry transient 429, 500, and 502 failures. A failure in one file is isolated in list_ementas; get_ementa reports an MCP tool error.