Language Tutor

A personal language tutor where your AI assistant is the teacher. The app stores your words, schedules reviews and shows the exercises that need a screen; Claude, ChatGPT or Codex talks to it over MCP and does the teaching: it writes stories from your words, judges your translations, names every mistake and remembers your habits.

Status: early. It runs a real learner's daily practice, but it is a single-user app. Today it teaches English to Russian speakers; other languages are planned, not built.

Today it teaches English to Russian speakers. Other languages are planned.

How it works

• You collect words in any chat ("save these words") or paste a Google Translate export. Each word can carry a memory hook (a sound-alike, a known word or an image) and an example sentence.

• The assistant writes a story around your words. You translate it paragraph by paragraph, in both directions.

• Every mistake is named by category and by the rule behind it. A mistake that repeats becomes a habit the tutor works on, until you get it right often enough to retire it.

• Reviews use the FSRS scheduler (ts-fsrs): cards come back just before you would forget them.

• A translator (the Translate tab) that works like Google Translate but with an LLM: type in either of your two languages and the translation appears as you type, with other phrasings, a note on a trap, and the words worth learning, each with a memory hook. One tap saves the words (and, for a short text, the whole phrase) into your dictionary; each word comes back as a review card built from the sentence it was found in.

• The phone app (a PWA) does what a chat cannot, in five tabs: Today (what to do now; review cards start here), Translate, Practice (paragraph translation and dictation), Words (search, filter, delete) and Profile (progress, habits, translator settings).

• The tutoring method and its reasoning live in @docs/research; the assistant reads the agreed method from the server, so every assistant teaches the same way.

Related MCP server: mcp-vocabulary-trainer

Stack

Next.js 16 (App Router), React 19, Tailwind 4 + daisyUI 5, Drizzle ORM on libSQL (SQLite), @modelcontextprotocol/sdk (stateless Streamable HTTP), OAuth 2.1 for the assistant connectors, zod, Vitest.

Run it locally

pnpm install
cp .env.example .env.local     # set APP_PASSWORD, APP_SECRET, MCP_TOKEN (openssl rand -hex 32)
pnpm dev                       # http://localhost:3000, database file at data/english.db

Leave DATABASE_URL empty locally: a SQLite file is created and migrated for you.

Deploy to Vercel

1. Import the repository in Vercel (a paid plan; Hobby is for non-commercial use). vercel.json sets the build command and the region.

2. Add a Turso database from the Vercel Marketplace. It sets DATABASE_URL and DATABASE_AUTH_TOKEN; scope them to the Production environment so previews never touch your data.

3. Set APP_PASSWORD, APP_SECRET and MCP_TOKEN in the Production environment. Set APP_URL only for a custom domain.

4. Push to main: Vercel builds, runs pnpm db:migrate against the database, and deploys.

Self-host with Docker

cp .env.example .env, set APP_PASSWORD, APP_SECRET, MCP_TOKEN and APP_URL, then docker compose up -d. The SQLite file lives in the data volume; run one instance only. Back it up with sqlite3 /data/english.db ".backup <file>" inside the container.

Connect an assistant

Open Profile → Connect an assistant in the app. It has the steps for Claude (claude.ai and Claude Code), ChatGPT (custom MCP server, OAuth) and Codex, with copy buttons. Sign-in asks for APP_PASSWORD once.

Configuration

Development

pnpm check runs lint, type-check and the tests (a local libSQL file, no server needed). pnpm db:generate after changing src/db/schema.ts. The code map and invariants are in CLAUDE.md. See CONTRIBUTING.md.

Limits and security

• One user, one writer. One password, one SQLite file, one process that writes. Do not scale it horizontally.

• Sign-in is rate limited in memory (5 failed attempts per address and 40 in total per 15 minutes). On a single server that is the limit; on serverless each instance counts alone, so use a long password.

• Secrets are yours. Nothing secret ships in the repository; set APP_PASSWORD, APP_SECRET and MCP_TOKEN as long random values. Changing APP_SECRET signs every client out.

• No off-site backup yet. Back up the database file yourself (a Turso database has its own restore options).

• English first. The prompts, word rules and UI copy are English; the learner's language is Russian.

• Found a vulnerability? Open a private security advisory on GitHub rather than a public issue.

License

MIT