Study Assistant

Ein lokaler Model Context Protocol (MCP)-Server, der Syllabus-Dokumente in eine durchsuchbare Studien-Wissensdatenbank verwandelt. Der Server liest Dokumente aus files/ementas, extrahiert deren Text und verwendet Genkit mit Ollama Cloud, um Zusammenfassungen und strukturierte Details zu erstellen.

Architektur

Dieses Repository ist ein pnpm-Monorepo. Das Paket mcp enthält den Express- und MCP-Server, während files/ementas das einzige Dokumentverzeichnis ist, das den Tools zugänglich ist.

Der Server bindet an 127.0.0.1 und stellt Folgendes bereit:

• GET /health: Prozesszustand ohne Geheimnisse oder Providerdetails.

• /mcp: zustandsloser MCP-Streamable-HTTP-Endpunkt.

• list_ementas: listet unterstützte Dateien mit Metadaten und zwischengespeicherten Zusammenfassungen auf.

• get_ementa: gibt extrahierten Text und strukturierte Syllabus-Details zurück.

Unterstützte Formate sind PDF, DOCX, Markdown und reiner Text. Symbolische Links, Pfade und nicht unterstützte Erweiterungen werden abgelehnt.

Related MCP server: Educational Tutor MCP Server

Voraussetzungen

• Node.js 20 oder neuer.

• pnpm 10 (Corepack kann die festgelegte Version bereitstellen).

• Ein Ollama-Cloud-API-Schlüssel.

Einrichtung

Installieren Sie die Abhängigkeiten vom Repository-Stammverzeichnis aus:

corepack pnpm install

Kopieren Sie mcp/.env.example entweder in .env im Repository-Stammverzeichnis oder in mcp/.env und geben Sie dann den API-Schlüssel an:

OLLAMA_API_KEY=your-key

Das Standardmodell ist gpt-oss:120b. Optionale Einstellungen sind:

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

Umgebungsdateien werden von Git ignoriert. Committen Sie niemals einen API-Schlüssel.

Die Anwendung löst beide Speicherorte explizit auf, unabhängig vom Verzeichnis, aus dem pnpm das Paket startet. Vorhandene Systemumgebungsvariablen haben Vorrang; wenn beide Dateien dieselbe Variable definieren, hat mcp/.env Vorrang vor der .env im Stammverzeichnis.

Legen Sie Syllabus-Dateien direkt in files/ementas ab und starten Sie dann den Entwicklungsserver:

corepack pnpm dev

Der MCP-Endpunkt ist unter http://127.0.0.1:3000/mcp verfügbar.

Codex verbinden

Registrieren Sie bei laufendem Server dessen URL im lokalen Codex-Client:

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

Entsprechende Codex-Konfiguration:

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

Dieser Localhost-Endpunkt ist für einen lokalen Codex-Client vorgesehen. Er wird nicht für entfernte ChatGPT-Clients bereitgestellt.

Befehle

Führen Sie diese Befehle vom Repository-Stammverzeichnis aus:

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 und build führen niemals die Testsuite aus. Die Produktionskompilierung schließt außerdem src/__tests__ aus, sodass Test-Fixtures und Mocks weder vom Server geladen noch in dist ausgegeben werden können.

Generierte Analysen werden in .cache/ementas.json gespeichert. Cache-Einträge werden ungültig, wenn sich die Größe oder der Änderungszeitpunkt eines Dokuments ändert. Ein gültiges zwischengespeichertes Ergebnis bleibt verwendbar, wenn Ollama Cloud vorübergehend nicht verfügbar ist.

Sicherheit und Fehlerverhalten

Der API-Schlüssel wird aus der Umgebung geladen und nur im Ollama-Autorisierungsheader gesendet. Er ist nicht in Health-Antworten, MCP-Antworten oder Anwendungsprotokollen enthalten. Cloud-Anfragen verwenden ein Timeout und wiederholen vorübergehende 429-, 500- und 502-Fehler. Ein Fehler in einer Datei wird in list_ementas isoliert; get_ementa meldet einen MCP-Tool-Fehler.