Sprachen — Multilingual Vocabulary Trainer with MCP Agent

A local, single-user vocabulary trainer with Leitner spaced repetition, domain/topic organization, and a ChatGPT MCP agent for lessons — plus optional OpenAI assistance in the app.

Project page

More background and write-up:

• Deutsch

• English

Related MCP server: FlashLearn

Runs locally

This project is meant to run on your own machine (or local Docker). It is not a hosted SaaS, and there is no cloud/CDK deploy in this repo.

• Single-user, no login / no auth

• Data stays in a local SQLite file under data/

• Do not expose the app to the public internet without adding your own access control

Features

• Leitner 6-box spaced repetition

• Multiple languages (UI + vocabulary): German, English, Spanish, French, Portuguese, Swiss German

• Domains/topics for organizing entries

• Fuzzy answer matching (typo-tolerant)

• Conjugation practice

• Grammar reference (cheat sheets; create/refine via MCP chat)

• Worksheets / grammar tests (create via MCP, fill in the app, results for later analysis)

• Optional OpenAI-powered translation suggestions

• ChatGPT MCP at /mcp (persistence + review + grammar + worksheets; AI stays in ChatGPT)

Quick start

Prerequisites

• Node.js 18+ and npm

• An OpenAI API key if you want AI features (optional for core review)

Initialize

git clone <this-repo-url>
cd sprachen

npm install
cp .env.example .env

Edit .env and set at least:

DATABASE_URL="file:../data/sprachen.db"
OPENROUTER_API_KEY=your_openrouter_api_key_here
NEXT_PUBLIC_NATIVE_LANG=de
# Optional — train only some targets (omit = all except native):
# NEXT_PUBLIC_TARGET_LANGS=en,es,fr

NEXT_PUBLIC_NATIVE_LANG is your mother tongue / source language (de | en | es | fr | pt | gsw). Set it once at install time.

NEXT_PUBLIC_TARGET_LANGS limits which languages you train (comma-separated). Example: en,es,fr for three languages only. Leave empty for all targets except your native language. Restart the app after changing it.

Create or upgrade the SQLite database (applies Prisma migrations; backs up an existing DB to data/backups/ first):

npm run db:migrate

Start the app:

npm run dev

Open http://localhost:4810.

npm run dev starts Next.js on port 4810 (MCP at /mcp) and the optional OpenAI MCP tunnel (health 4811). Web only: npm run dev:web.

Daily on iPhone (offline, no cloud)

Native iOS (download + listen, lock-screen audio): open ios/Sprachen.xcodeproj on this Mac, sign with your Apple ID, and install to the iPhone over USB. Details: docs/ios.md.

The Mac creates the Daily pack and TTS. The iPhone downloads over home Wi-Fi (http://<mac-ip>:4810) and then plays from local files with the Mac off.

Environment

Copy from .env.example:

Never commit .env or .env.production — only .env.example is tracked.

Docker (optional, local)

No separate database container. SQLite lives in ./data:

export OPENROUTER_API_KEY=your_openrouter_api_key_here
npm run docker:up

App: http://localhost:4810.

ChatGPT MCP

Persistence MCP at /mcp (domains, entries, conjugations, review/Leitner, grammar, worksheets, stats). Details for tunnel-client and ChatGPT Developer Mode: SETUP.md.

npm run dev          # app + tunnel (development)
npm run start        # app + tunnel (after npm run build)
npm run start:web    # production web only
npm run mcp:tunnel   # tunnel only

Grammar via chat

Grammar chapters live in the DB and are shown under Grammatik in the app. Content is created and refined in chat (ChatGPT/Claude with MCP):

1. New — learn a topic → AI asks whether to save → create_grammar_topic (RULE + EXAMPLES + NOTE)

2. Resume — “I want to learn possessives” → search_grammar_topics / get_grammar_topic → discuss from your saved chapter

3. Personalize — add your own mnemonic → upsert_grammar_blocks (after confirmation)

Worksheets via chat

Worksheets live in the DB and are shown under Arbeitsblätter in the app. The AI creates them from your grammar/vocabulary; you fill them in the app.

1. New — ask the AI to load your grammar/vocab/stats, then save a worksheet → create_worksheet (8 question types: multiple choice, cloze, free text, error correction, sentence reorder, matching, true/false, conjugation grid)

2. List / inspect — list_worksheets / get_worksheet to resume or tweak an open sheet (update_worksheet until completed)

3. Analyse — after you finish in the app, get_worksheet_results shows answers, auto-grade, manual overrides, and weak tags/topics

Voice Chat workaround

ChatGPT Voice Chat cannot call MCP tools directly. Use text MCP first, then voice, then sync back:

1. Load context in text chat — ask ChatGPT (with the MCP plugin enabled) to fetch the vocabulary / due cards / lesson context you need via MCP.

2. Start Voice Chat — continue in the same conversation so that context is already in the thread.

3. Practice by voice — train as usual; Voice Chat only talks, it does not write to the database.

4. Sync after voice — switch back to text and tell ChatGPT something like: „Okay, aktualisiere die Einträge basierend auf der Lehrer-Erfahrung.“ so it updates progress / entries through MCP.

Without that last step, the spoken lesson stays only in the chat history.

Leitner boxes

Cards move through 6 boxes with increasing intervals:

Correct → one box up. Wrong → back to box 1. Due cards have nextReviewAt in the past.

Tech stack

Next.js 15 · TypeScript · tRPC · SQLite + Prisma · Tailwind / shadcn/ui · OpenAI (optional) · Vitest

Development

npm run lint
npm run test
npm run build
npm run db:migrate      # backup + apply migrations (default on every machine)
npm run db:migrate:dev  # create new migrations locally
npm run db:backup       # copy DB to data/backups/
npm run update          # git pull --rebase, install, migrate, build (PM2 restart via pm_id / PM2_PROCESS)
npm run db:push         # optional schema sync shortcut
npm run db:studio

License

MIT — see LICENSE.