langcoach 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oktay Bilge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,93 @@
-# Temporary Holding Version
+# LangCoach
+
+**English** | [Türkçe](https://github.com/oktaybilge1/langcoach/blob/main/README.tr.md)
+
+[![CI](https://github.com/oktaybilge1/langcoach/actions/workflows/ci.yml/badge.svg)](https://github.com/oktaybilge1/langcoach/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/langcoach)](https://www.npmjs.com/package/langcoach)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/oktaybilge1/langcoach/blob/main/LICENSE)
+
+**Your language coach inside Claude Code: weekly plan, daily tasks, spaced-repetition reviews, streak and XP, for any language pair.**
+
+<!-- TODO: hero GIF of a real session goes here: docs/media/demo.gif (not recorded yet) -->
+
+AI language lessons are great, but most forget you the moment the chat ends. LangCoach is an MCP server that gives Claude a memory for your learning: Claude writes the lessons in your target language, LangCoach stores your plan, reviews and progress on your machine.
+
+- No API key, no account, no server.
+- Works with any native + target language.
+- Your data stays on your machine.
+
+## Install
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Requires [Node.js](https://nodejs.org) 20+ and [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (signed in).
+
+macOS / Linux / WSL:
+
+```bash
+claude mcp add --scope user langcoach -- npx -y langcoach
+```
+
+Windows (native PowerShell/CMD, not WSL):
+
+```bash
+claude mcp add --scope user langcoach -- cmd /c npx -y langcoach
+```
+
+**No API key needed.** Your own Claude subscription writes the lessons.
+
+Or paste this repo link into Claude Code and say: *Install LangCoach for me*
+
+Details, verification, update, uninstall and troubleshooting: [docs/INSTALL.md](https://github.com/oktaybilge1/langcoach/blob/main/docs/INSTALL.md). The `langcoach` package is not on npm yet; until it is published, see "Run from source" in that guide.
+
+## Use it
+
+In Claude Code, run the `tutor` prompt. MCP prompts show up as a slash command, like `/mcp__langcoach__tutor`. Or just ask Claude:
+
+> Let's start my language lesson with langcoach
+
+The first time, Claude interviews you (native language, target language, CEFR level, goal, minutes per day, days per week) and saves your profile. After that it builds this week's plan, tells you what is on for today, teaches the lesson, quizzes you on due cards and records everything.
+
+## Features
+
+- **Personal profile:** native language, target language, level (A1-C2), goal, daily minutes and study days per week.
+- **Weekly plan:** study days spread across the ISO week, sized to your daily minutes, with a theme picked from your goal.
+- **Daily tasks:** Tiny Lesson-style situational lessons, Slang Hang-style informal lessons, reviews, and a quiz on the last study day.
+- **Spaced repetition:** every lesson item becomes a review card scheduled with [FSRS](https://github.com/open-spaced-repetition/ts-fsrs); duplicates are skipped.
+- **Progress:** streak, total XP and weekly goal, always read from stored data, never invented.
+- **Safe data:** atomic writes, a backup before every import, and corrupt files are preserved instead of overwritten.
+- **No network calls:** LangCoach makes no network calls; your data stays on your machine.
+
+### Tools
+
+Claude uses these tools for you: `set_profile`, `get_weekly_plan`, `get_today`, `save_lesson`, `complete_task`, `get_due_reviews`, `submit_review`, `get_progress`, `export_data`, `import_data`.
+
+## Your data
+
+Everything lives in one JSON file: `~/.langcoach/data.json`. Set the `LANGCOACH_HOME` environment variable to use a different folder.
+
+- **Export / import:** ask Claude to run `export_data` for a backup or to move to another machine, and `import_data` to restore it.
+- Writes are atomic, so a crash cannot leave a half-written file.
+- Parallel tool calls and several Claude Code sessions take turns through a short-lived `data.json.lock` file, so no update is lost.
+- If the data file is corrupt, it is preserved as `data.corrupt-<timestamp>.json` and you get a clear error.
+- Before an import replaces your data, the current file is saved as `data.backup-<timestamp>.json`.
+
+## Roadmap
+
+Planned, not built yet:
+
+- [ ] Web app (PWA) that runs in the browser with your own Gemini API key, plus a live demo on GitHub Pages
+- [ ] Word Cam-style camera vocabulary (web app)
+- [ ] More UI languages via community PRs
+
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](https://github.com/oktaybilge1/langcoach/blob/main/CONTRIBUTING.md).
+
+## Credits and disclaimer
+
+LangCoach is inspired by Google Labs' [Little Language Lessons](https://labs.google/lll/en) (Tiny Lesson, Slang Hang, Word Cam) and adds what one-off exercises lack: a weekly plan and progress tracking.
+
+LangCoach is an independent project and is not affiliated with, endorsed by, or sponsored by Google.
+
+## License
+
+[MIT](https://github.com/oktaybilge1/langcoach/blob/main/LICENSE) (c) 2026 Oktay Bilge

package/dist/index.js

@@ -0,0 +1,869 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// ../core/src/types.ts
+function emptyState() {
+  return { version: 1, profile: null, plans: {}, lessons: [], cards: [], log: [] };
+}
+
+// ../core/src/dates.ts
+var pad = (n, w = 2) => String(n).padStart(w, "0");
+function toLocalDate(d) {
+  return `${pad(d.getFullYear(), 4)}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+function isoWeek(d) {
+  const t = new Date(Date.UTC(d.getFullYear(), d.getMonth(), d.getDate()));
+  const dayNum = t.getUTCDay() || 7;
+  t.setUTCDate(t.getUTCDate() + 4 - dayNum);
+  const year = t.getUTCFullYear();
+  const yearStart = Date.UTC(year, 0, 1);
+  const week = Math.ceil(((t.getTime() - yearStart) / 864e5 + 1) / 7);
+  return `${pad(year, 4)}-W${pad(week)}`;
+}
+function weekDates(week) {
+  const m = /^(\d{4})-W(\d{2})$/.exec(week);
+  if (!m) throw new Error(`Invalid ISO week: ${week}`);
+  const year = Number(m[1]);
+  const w = Number(m[2]);
+  const jan4 = new Date(Date.UTC(year, 0, 4));
+  const jan4Day = jan4.getUTCDay() || 7;
+  const mondayMs = jan4.getTime() - (jan4Day - 1) * 864e5 + (w - 1) * 7 * 864e5;
+  return Array.from({ length: 7 }, (_, i) => {
+    const x = new Date(mondayMs + i * 864e5);
+    return `${pad(x.getUTCFullYear(), 4)}-${pad(x.getUTCMonth() + 1)}-${pad(x.getUTCDate())}`;
+  });
+}
+
+// ../core/src/errors.ts
+var InvalidDataError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InvalidDataError";
+  }
+};
+var NoProfileError = class extends Error {
+  constructor() {
+    super("No learner profile yet. Call set_profile first.");
+    this.name = "NoProfileError";
+  }
+};
+var ThemeRequiredError = class extends Error {
+  constructor() {
+    super("A theme is needed to create this week's plan. Provide a theme and try again.");
+    this.name = "ThemeRequiredError";
+  }
+};
+var NotFoundError = class extends Error {
+  constructor(what, id) {
+    super(`${what} not found: ${id}`);
+    this.name = "NotFoundError";
+  }
+};
+var CorruptDataError = class extends Error {
+  preservedAt;
+  constructor(message, preservedAt) {
+    super(message);
+    this.name = "CorruptDataError";
+    this.preservedAt = preservedAt;
+  }
+};
+
+// ../core/src/schema.ts
+import { z } from "zod";
+var cefr = z.enum(["A1", "A2", "B1", "B2", "C1", "C2"]);
+var taskType = z.enum(["tiny_lesson", "slang_hang", "review", "quiz"]);
+var obj = z.looseObject;
+var profile = obj({
+  nativeLanguage: z.string(),
+  targetLanguage: z.string(),
+  level: cefr,
+  goal: z.string(),
+  minutesPerDay: z.number().int().min(5).max(180),
+  daysPerWeek: z.number().int().min(1).max(7),
+  createdAt: z.string()
+});
+var lessonItem = obj({
+  term: z.string(),
+  translation: z.string(),
+  example: z.string(),
+  note: z.string().optional()
+});
+var lesson = obj({
+  id: z.string(),
+  kind: z.enum(["tiny_lesson", "slang_hang"]),
+  situation: z.string(),
+  items: z.array(lessonItem),
+  createdAt: z.string()
+});
+var srs = obj({
+  due: z.iso.datetime({ offset: true }),
+  state: z.number(),
+  reps: z.number(),
+  lapses: z.number()
+});
+var reviewCard = obj({
+  id: z.string(),
+  lessonId: z.string(),
+  term: z.string(),
+  translation: z.string(),
+  example: z.string(),
+  srs
+});
+var planTask = obj({
+  id: z.string(),
+  date: z.string(),
+  type: taskType,
+  minutes: z.number().int().min(1),
+  status: z.enum(["todo", "done"]),
+  completedAt: z.string().optional(),
+  lessonId: z.string().optional()
+});
+var weekPlan = obj({ week: z.string(), theme: z.string(), tasks: z.array(planTask) });
+var logEntry = obj({
+  at: z.string(),
+  date: z.string(),
+  taskId: z.string(),
+  type: taskType,
+  xp: z.number().min(0)
+});
+var stateSchema = obj({
+  version: z.literal(1),
+  profile: profile.nullable(),
+  plans: z.record(z.string(), weekPlan),
+  lessons: z.array(lesson),
+  cards: z.array(reviewCard),
+  log: z.array(logEntry)
+});
+function parseState(raw) {
+  const result = stateSchema.safeParse(raw);
+  if (!result.success) {
+    const detail = result.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ");
+    throw new InvalidDataError(`Invalid LangCoach data: ${detail}`);
+  }
+  return result.data;
+}
+
+// ../core/src/store.ts
+import { randomBytes } from "crypto";
+import { copyFile, mkdir, open, readFile, readdir, rename, stat, unlink } from "fs/promises";
+import { homedir } from "os";
+import { basename, dirname, join, resolve } from "path";
+var stamp = () => `${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}-${randomBytes(3).toString("hex")}`;
+var code = (e) => e?.code;
+var isNotFound = (e) => code(e) === "ENOENT";
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+var Mutex = class {
+  tail = Promise.resolve();
+  run(task) {
+    const next = this.tail.then(task, task);
+    this.tail = next.catch(() => void 0);
+    return next;
+  }
+};
+var fileMutexes = /* @__PURE__ */ new Map();
+function mutexFor(path) {
+  const key = process.platform === "win32" || process.platform === "darwin" ? path.toLowerCase() : path;
+  let m = fileMutexes.get(key);
+  if (!m) {
+    m = new Mutex();
+    fileMutexes.set(key, m);
+  }
+  return m;
+}
+var JsonFileStore = class {
+  filePath;
+  lockPath;
+  lockTimeoutMs;
+  staleLockMs;
+  constructor(filePath, opts = {}) {
+    this.filePath = resolve(filePath);
+    this.lockPath = `${this.filePath}.lock`;
+    this.lockTimeoutMs = opts.lockTimeoutMs ?? 5e3;
+    this.staleLockMs = opts.staleLockMs ?? 1e4;
+  }
+  async load() {
+    let bytes;
+    try {
+      bytes = await readFile(this.filePath);
+    } catch (e) {
+      if (isNotFound(e)) return emptyState();
+      throw e;
+    }
+    let raw;
+    try {
+      raw = JSON.parse(bytes.toString("utf8"));
+    } catch {
+      const preservedAt = await this.preserveCorrupt(bytes);
+      throw new CorruptDataError(
+        `Data file is not valid JSON. Original preserved at ${preservedAt}. Restore with import_data from a data.backup-*.json, or move data.json aside to start fresh.`,
+        preservedAt
+      );
+    }
+    return parseState(raw);
+  }
+  async save(s) {
+    const dir = dirname(this.filePath);
+    await mkdir(dir, { recursive: true });
+    const tmp = join(dir, `${basename(this.filePath)}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);
+    try {
+      const fh = await open(tmp, "wx");
+      try {
+        await fh.writeFile(JSON.stringify(s, null, 2), "utf8");
+        await fh.sync();
+      } finally {
+        await fh.close();
+      }
+      await renameWithRetry(tmp, this.filePath);
+    } catch (e) {
+      await unlink(tmp).catch(() => void 0);
+      throw e;
+    }
+  }
+  async backup() {
+    const dest = join(dirname(this.filePath), `data.backup-${stamp()}.json`);
+    try {
+      await copyFile(this.filePath, dest);
+    } catch (e) {
+      if (isNotFound(e)) return null;
+      throw e;
+    }
+    return dest;
+  }
+  transaction(fn) {
+    return mutexFor(this.filePath).run(async () => {
+      const token = await this.acquireLock();
+      try {
+        const out = await fn(await this.load());
+        if (out.state !== void 0) await this.save(out.state);
+        return out.result;
+      } finally {
+        await this.releaseLock(token);
+      }
+    });
+  }
+  replace(next) {
+    return mutexFor(this.filePath).run(async () => {
+      const token = await this.acquireLock();
+      try {
+        const backupPath = await this.backup();
+        await this.save(next);
+        return backupPath;
+      } finally {
+        await this.releaseLock(token);
+      }
+    });
+  }
+  /** Copy corrupt bytes aside once: reuse an existing data.corrupt-*.json with identical bytes. */
+  async preserveCorrupt(bytes) {
+    const dir = dirname(this.filePath);
+    const names = await readdir(dir).catch(() => []);
+    for (const name of names) {
+      if (!/^data\.corrupt-.*\.json$/.test(name)) continue;
+      const p = join(dir, name);
+      const other = await readFile(p).catch(() => null);
+      if (other && other.equals(bytes)) return p;
+    }
+    const preservedAt = join(dir, `data.corrupt-${stamp()}.json`);
+    await copyFile(this.filePath, preservedAt);
+    return preservedAt;
+  }
+  async acquireLock() {
+    const dir = dirname(this.filePath);
+    await mkdir(dir, { recursive: true });
+    const token = randomBytes(8).toString("hex");
+    const deadline = Date.now() + this.lockTimeoutMs;
+    let delay = 20;
+    for (; ; ) {
+      let openCode;
+      try {
+        const fh = await open(this.lockPath, "wx");
+        try {
+          await fh.writeFile(JSON.stringify({ pid: process.pid, at: Date.now(), token }), "utf8");
+        } catch (e) {
+          await fh.close().catch(() => void 0);
+          await unlink(this.lockPath).catch(() => void 0);
+          throw e;
+        }
+        await fh.close();
+        return token;
+      } catch (e) {
+        openCode = code(e);
+        if (openCode !== "EEXIST" && openCode !== "EPERM" && openCode !== "EACCES") throw e;
+      }
+      const lock = await this.inspectLock();
+      if (lock === "removed" || lock === "missing" && openCode === "EEXIST") continue;
+      if (Date.now() >= deadline) {
+        if (lock === "missing") {
+          throw new Error(
+            `LangCoach cannot create files in its data folder (${dir}): the folder is not writable. Check its permissions or set LANGCOACH_HOME to a writable folder.`
+          );
+        }
+        if (lock === "stuck") {
+          throw new Error(
+            `LangCoach could not remove an old lock file: ${this.lockPath}. Make sure no other LangCoach is running, delete that file and try again.`
+          );
+        }
+        throw new Error("LangCoach data file is busy, try again.");
+      }
+      await sleep(Math.min(delay, Math.max(1, deadline - Date.now())));
+      delay = Math.min(delay * 2, 200);
+    }
+  }
+  /**
+   * Look at the existing lock file: 'missing' (no lock file), 'held' (fresh, or unreadable),
+   * 'removed' (it was stale and we deleted it) or 'stuck' (stale but could not be deleted).
+   */
+  async inspectLock() {
+    let mtime;
+    try {
+      mtime = (await stat(this.lockPath)).mtimeMs;
+    } catch (e) {
+      return isNotFound(e) ? "missing" : "held";
+    }
+    let at = mtime;
+    try {
+      const parsed = JSON.parse(await readFile(this.lockPath, "utf8"));
+      if (typeof parsed.at === "number") at = Math.max(parsed.at, mtime);
+    } catch {
+    }
+    if (Date.now() - at <= this.staleLockMs) return "held";
+    try {
+      await unlink(this.lockPath);
+      return "removed";
+    } catch (e) {
+      return isNotFound(e) ? "removed" : "stuck";
+    }
+  }
+  async releaseLock(token) {
+    try {
+      const parsed = JSON.parse(await readFile(this.lockPath, "utf8"));
+      if (parsed.token !== token) return;
+    } catch (e) {
+      if (isNotFound(e)) return;
+    }
+    await unlink(this.lockPath).catch(() => void 0);
+  }
+};
+async function renameWithRetry(from, to) {
+  const deadline = Date.now() + 1e3;
+  let delay = 10;
+  for (; ; ) {
+    try {
+      await rename(from, to);
+      return;
+    } catch (e) {
+      const c = code(e);
+      if (c !== "EPERM" && c !== "EACCES" && c !== "EBUSY" || Date.now() >= deadline) throw e;
+      await sleep(delay);
+      delay = Math.min(delay * 2, 100);
+    }
+  }
+}
+function defaultDataPath(env = process.env) {
+  const home = env.LANGCOACH_HOME;
+  return home ? join(home, "data.json") : join(homedir(), ".langcoach", "data.json");
+}
+
+// ../core/src/srs.ts
+import { createEmptyCard, fsrs } from "ts-fsrs";
+var scheduler = fsrs();
+function toCard(s) {
+  return {
+    ...s,
+    due: new Date(s.due),
+    last_review: s.last_review === void 0 ? void 0 : new Date(s.last_review)
+  };
+}
+function fromCard(c) {
+  const { due, last_review, ...rest } = c;
+  const out = { ...rest, due: due.toISOString() };
+  if (last_review) out.last_review = last_review.toISOString();
+  return out;
+}
+function newSrs(now) {
+  return fromCard(createEmptyCard(now));
+}
+function reviewSrs(s, rating, now) {
+  if (!Number.isInteger(rating) || rating < 1 || rating > 4) {
+    throw new Error(`Invalid rating ${String(rating)}: must be an integer from 1 (Again) to 4 (Easy)`);
+  }
+  return fromCard(scheduler.next(toCard(s), now, rating).card);
+}
+function isDue(s, now) {
+  return new Date(s.due).getTime() <= now.getTime();
+}
+
+// ../core/src/planner.ts
+function buildWeekPlan(profile2, week, theme, newId, fromDate) {
+  const m = profile2.minutesPerDay;
+  const allDays = weekDates(week);
+  const start = fromDate === void 0 ? 0 : Math.max(0, allDays.indexOf(fromDate));
+  const days = allDays.slice(start);
+  const r = days.length;
+  const n = Math.min(profile2.daysPerWeek, r);
+  const tasks = [];
+  for (let k = 0; k < n; k++) {
+    const date = days[Math.floor(k * r / n)];
+    const main2 = k === n - 1 && n >= 2 ? "quiz" : k % 2 === 0 ? "tiny_lesson" : "slang_hang";
+    let mainMinutes = m;
+    if (k > 0) {
+      const reviewMinutes = Math.max(5, Math.round(m * 0.3));
+      mainMinutes = Math.max(5, m - reviewMinutes);
+      tasks.push({ id: newId(), date, type: "review", minutes: reviewMinutes, status: "todo" });
+    }
+    tasks.push({ id: newId(), date, type: main2, minutes: mainMinutes, status: "todo" });
+  }
+  return { week, theme, tasks };
+}
+
+// ../core/src/progress.ts
+var BASE_XP = {
+  tiny_lesson: 20,
+  slang_hang: 20,
+  quiz: 30,
+  review: 10
+};
+function xpFor(type, cardsReviewed = 0) {
+  return BASE_XP[type] + (type === "review" ? cardsReviewed : 0);
+}
+function prevDay(date) {
+  const [y, m, d] = date.split("-").map(Number);
+  const t = new Date(Date.UTC(y, m - 1, d - 1));
+  const p = (n, w = 2) => String(n).padStart(w, "0");
+  return `${p(t.getUTCFullYear(), 4)}-${p(t.getUTCMonth() + 1)}-${p(t.getUTCDate())}`;
+}
+function streak(log, today) {
+  const days = new Set(log.map((e) => e.date));
+  let cursor = days.has(today) ? today : prevDay(today);
+  let count = 0;
+  while (days.has(cursor)) {
+    count++;
+    cursor = prevDay(cursor);
+  }
+  return count;
+}
+function weeklyGoal(plan) {
+  if (!plan) return { done: 0, planned: 0 };
+  const byDate = /* @__PURE__ */ new Map();
+  for (const t of plan.tasks) {
+    byDate.set(t.date, (byDate.get(t.date) ?? true) && t.status === "done");
+  }
+  return { done: [...byDate.values()].filter(Boolean).length, planned: byDate.size };
+}
+
+// ../core/src/coach.ts
+import { randomUUID } from "crypto";
+var LEVELS = ["A1", "A2", "B1", "B2", "C1", "C2"];
+var KINDS = ["tiny_lesson", "slang_hang"];
+var blank = (v) => typeof v !== "string" || v.trim() === "";
+var dupKey = (term) => term.trim().toLocaleLowerCase();
+function requireProfile(s) {
+  if (!s.profile) throw new NoProfileError();
+  return s.profile;
+}
+function intIn(v, min, max) {
+  return typeof v === "number" && Number.isInteger(v) && v >= min && v <= max;
+}
+var Coach = class {
+  constructor(store, clock = () => /* @__PURE__ */ new Date(), newId = () => randomUUID()) {
+    this.store = store;
+    this.clock = clock;
+    this.newId = newId;
+  }
+  store;
+  clock;
+  newId;
+  async setProfile(input) {
+    if (blank(input.nativeLanguage)) throw new InvalidDataError("nativeLanguage must be a non-empty string");
+    if (blank(input.targetLanguage)) throw new InvalidDataError("targetLanguage must be a non-empty string");
+    if (!LEVELS.includes(input.level)) {
+      throw new InvalidDataError(`level must be one of ${LEVELS.join(", ")}`);
+    }
+    if (typeof input.goal !== "string") throw new InvalidDataError("goal must be a string");
+    if (!intIn(input.minutesPerDay, 5, 180)) {
+      throw new InvalidDataError("minutesPerDay must be an integer from 5 to 180");
+    }
+    if (!intIn(input.daysPerWeek, 1, 7)) {
+      throw new InvalidDataError("daysPerWeek must be an integer from 1 to 7");
+    }
+    return this.store.transaction((s) => {
+      const profile2 = {
+        nativeLanguage: input.nativeLanguage,
+        targetLanguage: input.targetLanguage,
+        level: input.level,
+        goal: input.goal,
+        minutesPerDay: input.minutesPerDay,
+        daysPerWeek: input.daysPerWeek,
+        createdAt: s.profile?.createdAt ?? this.clock().toISOString()
+      };
+      s.profile = profile2;
+      return { state: s, result: profile2 };
+    });
+  }
+  async weekPlan(theme) {
+    if (theme !== void 0 && typeof theme !== "string") throw new InvalidDataError("theme must be a string");
+    return this.store.transaction((s) => {
+      const profile2 = requireProfile(s);
+      const now = this.clock();
+      const week = isoWeek(now);
+      const existing = s.plans[week];
+      if (existing) return { result: existing };
+      if (theme === void 0 || theme.trim() === "") throw new ThemeRequiredError();
+      const plan = buildWeekPlan(profile2, week, theme, this.newId, toLocalDate(now));
+      s.plans[week] = plan;
+      return { state: s, result: plan };
+    });
+  }
+  async today() {
+    const s = await this.store.load();
+    requireProfile(s);
+    const now = this.clock();
+    const date = toLocalDate(now);
+    const plan = s.plans[isoWeek(now)];
+    if (!plan) return { date, tasks: [], planExists: false };
+    return { date, tasks: plan.tasks.filter((t) => t.date === date), planExists: true };
+  }
+  async saveLesson(input) {
+    if (!KINDS.includes(input.kind)) throw new InvalidDataError(`kind must be one of ${KINDS.join(", ")}`);
+    if (blank(input.situation)) throw new InvalidDataError("situation must be a non-empty string");
+    if (!Array.isArray(input.items) || input.items.length < 1 || input.items.length > 50) {
+      throw new InvalidDataError("items must contain between 1 and 50 entries");
+    }
+    input.items.forEach((it, i) => {
+      if (!it || blank(it.term)) throw new InvalidDataError(`items[${i}].term must be a non-empty string`);
+      if (blank(it.translation)) throw new InvalidDataError(`items[${i}].translation must be a non-empty string`);
+      if (typeof it.example !== "string") throw new InvalidDataError(`items[${i}].example must be a string`);
+      if (it.note !== void 0 && typeof it.note !== "string") {
+        throw new InvalidDataError(`items[${i}].note must be a string`);
+      }
+    });
+    return this.store.transaction((s) => {
+      requireProfile(s);
+      const now = this.clock();
+      const lesson2 = {
+        id: this.newId(),
+        kind: input.kind,
+        situation: input.situation,
+        items: input.items.map((it) => {
+          const item = { term: it.term, translation: it.translation, example: it.example };
+          if (it.note !== void 0) item.note = it.note;
+          return item;
+        }),
+        createdAt: now.toISOString()
+      };
+      const seen = new Set(s.cards.map((c) => dupKey(c.term)));
+      const duplicates = [];
+      let newCards = 0;
+      for (const it of lesson2.items) {
+        const key = dupKey(it.term);
+        if (seen.has(key)) {
+          duplicates.push(it.term);
+          continue;
+        }
+        seen.add(key);
+        s.cards.push({
+          id: this.newId(),
+          lessonId: lesson2.id,
+          term: it.term,
+          translation: it.translation,
+          example: it.example,
+          srs: newSrs(now)
+        });
+        newCards++;
+      }
+      s.lessons.push(lesson2);
+      return { state: s, result: { lesson: lesson2, newCards, duplicates } };
+    });
+  }
+  async completeTask(taskId, opts = {}) {
+    const cardsReviewed = opts.cardsReviewed;
+    if (cardsReviewed !== void 0 && !intIn(cardsReviewed, 0, Number.MAX_SAFE_INTEGER)) {
+      throw new InvalidDataError("cardsReviewed must be an integer >= 0");
+    }
+    if (opts.lessonId !== void 0 && typeof opts.lessonId !== "string") {
+      throw new InvalidDataError("lessonId must be a string");
+    }
+    return this.store.transaction((s) => {
+      requireProfile(s);
+      let task;
+      for (const plan of Object.values(s.plans)) {
+        task = plan.tasks.find((t) => t.id === taskId);
+        if (task) break;
+      }
+      if (!task) throw new NotFoundError("Task", taskId);
+      if (task.status === "done") return { result: { task, xpAwarded: 0, alreadyDone: true } };
+      const now = this.clock();
+      const xp = xpFor(task.type, cardsReviewed);
+      task.status = "done";
+      task.completedAt = now.toISOString();
+      if (opts.lessonId !== void 0) task.lessonId = opts.lessonId;
+      s.log.push({ at: now.toISOString(), date: toLocalDate(now), taskId, type: task.type, xp });
+      return { state: s, result: { task, xpAwarded: xp, alreadyDone: false } };
+    });
+  }
+  async dueReviews(limit = 20) {
+    if (!intIn(limit, 1, Number.MAX_SAFE_INTEGER)) throw new InvalidDataError("limit must be a positive integer");
+    const s = await this.store.load();
+    requireProfile(s);
+    const now = this.clock();
+    return s.cards.filter((c) => isDue(c.srs, now)).sort((a, b) => new Date(a.srs.due).getTime() - new Date(b.srs.due).getTime()).slice(0, limit);
+  }
+  async submitReview(cardId, rating) {
+    return this.store.transaction((s) => {
+      requireProfile(s);
+      const card = s.cards.find((c) => c.id === cardId);
+      if (!card) throw new NotFoundError("Card", cardId);
+      card.srs = reviewSrs(card.srs, rating, this.clock());
+      return { state: s, result: card };
+    });
+  }
+  async progress() {
+    const s = await this.store.load();
+    const now = this.clock();
+    return {
+      profile: s.profile,
+      streak: streak(s.log, toLocalDate(now)),
+      totalXp: s.log.reduce((sum, e) => sum + e.xp, 0),
+      weekly: weeklyGoal(s.plans[isoWeek(now)]),
+      dueCount: s.cards.filter((c) => isDue(c.srs, now)).length
+    };
+  }
+  async exportData() {
+    return this.store.load();
+  }
+  async importData(raw) {
+    const parsed = parseState(raw);
+    await this.store.replace(parsed);
+    return { lessons: parsed.lessons.length, cards: parsed.cards.length };
+  }
+};
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z as z2 } from "zod";
+
+// package.json
+var package_default = {
+  name: "langcoach",
+  version: "0.1.0",
+  description: "Language-learning coach MCP server for Claude Code: Claude writes the lessons, LangCoach keeps your weekly plan, streak, XP and spaced-repetition (FSRS) reviews on your machine.",
+  keywords: [
+    "language-learning",
+    "spaced-repetition",
+    "fsrs",
+    "mcp",
+    "mcp-server",
+    "claude",
+    "claude-code",
+    "tutor",
+    "flashcards",
+    "vocabulary"
+  ],
+  homepage: "https://github.com/oktaybilge1/langcoach#readme",
+  bugs: {
+    url: "https://github.com/oktaybilge1/langcoach/issues"
+  },
+  repository: {
+    type: "git",
+    url: "git+https://github.com/oktaybilge1/langcoach.git",
+    directory: "packages/mcp"
+  },
+  license: "MIT",
+  type: "module",
+  bin: {
+    langcoach: "dist/index.js"
+  },
+  files: [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  engines: {
+    node: ">=20"
+  },
+  scripts: {
+    build: "tsup",
+    prepack: "npm run build && node scripts/copy-docs.mjs"
+  },
+  dependencies: {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "ts-fsrs": "^5.4.2",
+    zod: "^4.6.7"
+  },
+  devDependencies: {
+    "@langcoach/core": "*",
+    tsup: "^9.0.0"
+  }
+};
+
+// src/prompt.ts
+var TUTOR_PROMPT = `You are LangCoach, a friendly language tutor. You write the lessons yourself; the langcoach tools only store the learner's state.
+
+Start every session by calling get_progress and get_today.
+
+- No profile yet: interview the learner (native language, target language, CEFR level, goal, minutes per day, days per week), then call set_profile.
+- Profile but no plan for this week: propose a theme based on the learner's goal and call get_weekly_plan with it.
+- For each task, write the lesson in the target language with translations in the learner's native language. Save it with save_lesson BEFORE you teach it, so its items become review cards.
+- For review tasks, call get_due_reviews and quiz the cards one at a time. Record each answer right away with submit_review (1 again, 2 hard, 3 good, 4 easy).
+- Call complete_task only after the learner has actually finished the task. Pass the lessonId or cardsReviewed when relevant.
+- Never invent progress, streaks or XP. Report only what the tools return.
+- Keep it encouraging and short: small chunks, one question at a time.
+`;
+
+// src/server.ts
+var ok = (value) => ({
+  content: [{ type: "text", text: JSON.stringify(value, null, 2) }]
+});
+var fail = (err) => ({
+  isError: true,
+  content: [{ type: "text", text: err instanceof Error ? err.message : String(err) }]
+});
+async function run(fn) {
+  try {
+    return ok(await fn());
+  } catch (err) {
+    return fail(err);
+  }
+}
+var nonEmpty = z2.string().trim().min(1);
+function createServer(coach) {
+  const server = new McpServer({ name: "langcoach", version: package_default.version });
+  server.registerTool(
+    "set_profile",
+    {
+      description: "Save or update the learner profile. Call this once at the very start (after interviewing the learner), or when their level, goal or schedule changes. Required before the other tools, except export_data, import_data and get_progress, which work without a profile. A changed schedule (minutes per day, days per week) applies from next week's plan; this week's existing plan is kept.",
+      inputSchema: {
+        nativeLanguage: nonEmpty,
+        targetLanguage: nonEmpty,
+        level: z2.enum(["A1", "A2", "B1", "B2", "C1", "C2"]),
+        goal: z2.string(),
+        minutesPerDay: z2.number().int().min(5).max(180),
+        daysPerWeek: z2.number().int().min(1).max(7)
+      }
+    },
+    (args) => run(() => coach.setProfile(args))
+  );
+  server.registerTool(
+    "get_weekly_plan",
+    {
+      description: "Get this week's study plan. If none exists yet, pass a theme (picked from the learner's goal) to create it; without a theme and without an existing plan it returns an error asking for one.",
+      inputSchema: { theme: z2.string().optional() }
+    },
+    ({ theme }) => run(() => coach.weekPlan(theme))
+  );
+  server.registerTool(
+    "get_today",
+    {
+      description: "Call at the start of a study session: returns today's date and the tasks planned for today (with task ids and status)."
+    },
+    () => run(() => coach.today())
+  );
+  server.registerTool(
+    "save_lesson",
+    {
+      description: "Save a lesson you have written, BEFORE teaching it. Each item becomes a spaced-repetition review card (duplicates are skipped). Returns the lesson id to pass to complete_task.",
+      inputSchema: {
+        kind: z2.enum(["tiny_lesson", "slang_hang"]),
+        situation: nonEmpty,
+        items: z2.array(
+          z2.object({
+            term: nonEmpty,
+            translation: nonEmpty,
+            example: z2.string(),
+            note: z2.string().optional()
+          })
+        ).min(1).max(50)
+      }
+    },
+    (args) => run(() => coach.saveLesson(args))
+  );
+  server.registerTool(
+    "complete_task",
+    {
+      description: "Mark a planned task as done and award XP. Call only after the learner actually finished the task. Pass lessonId for lesson tasks and cardsReviewed for review tasks.",
+      inputSchema: {
+        taskId: nonEmpty,
+        lessonId: z2.string().optional(),
+        cardsReviewed: z2.number().int().min(0).optional()
+      }
+    },
+    ({ taskId, lessonId, cardsReviewed }) => run(() => {
+      const opts = {};
+      if (lessonId !== void 0) opts.lessonId = lessonId;
+      if (cardsReviewed !== void 0) opts.cardsReviewed = cardsReviewed;
+      return coach.completeTask(taskId, opts);
+    })
+  );
+  server.registerTool(
+    "get_due_reviews",
+    {
+      description: "Get review cards that are due now (oldest first). Use for review tasks, then quiz the learner one card at a time and record each answer with submit_review.",
+      inputSchema: { limit: z2.number().int().min(1).optional() }
+    },
+    ({ limit }) => run(() => coach.dueReviews(limit))
+  );
+  server.registerTool(
+    "submit_review",
+    {
+      description: "Record the learner's answer for one review card right after quizzing it. Rating: 1 = again (forgot), 2 = hard, 3 = good, 4 = easy.",
+      inputSchema: {
+        cardId: nonEmpty,
+        rating: z2.number().int().min(1).max(4)
+      }
+    },
+    ({ cardId, rating }) => run(() => coach.submitReview(cardId, rating))
+  );
+  server.registerTool(
+    "get_progress",
+    {
+      description: "Get profile, streak, total XP, weekly goal progress and number of due reviews. Call at the start of a session and when the learner asks how they are doing; never invent progress."
+    },
+    () => run(() => coach.progress())
+  );
+  server.registerTool(
+    "export_data",
+    {
+      description: "Export all stored learner data as JSON (backup, or to move to another machine)."
+    },
+    () => run(() => coach.exportData())
+  );
+  server.registerTool(
+    "import_data",
+    {
+      description: "Replace all stored data with a previously exported JSON document (passed as a string). The current data is backed up first. Only use when the learner explicitly asks to restore data.",
+      inputSchema: { json: z2.string() }
+    },
+    ({ json }) => run(async () => {
+      let raw;
+      try {
+        raw = JSON.parse(json);
+      } catch {
+        throw new Error("Invalid JSON: the provided text could not be parsed. Nothing was changed.");
+      }
+      return coach.importData(raw);
+    })
+  );
+  server.registerPrompt(
+    "tutor",
+    {
+      description: "Start a LangCoach tutoring session."
+    },
+    () => ({
+      messages: [{ role: "user", content: { type: "text", text: TUTOR_PROMPT } }]
+    })
+  );
+  return server;
+}
+
+// src/index.ts
+async function main() {
+  const coach = new Coach(new JsonFileStore(defaultDataPath()));
+  const server = createServer(coach);
+  await server.connect(new StdioServerTransport());
+}
+main().catch((err) => {
+  console.error("langcoach failed to start:", err instanceof Error ? err.message : err);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "langcoach",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Language-learning coach MCP server for Claude Code: Claude writes the lessons, LangCoach keeps your weekly plan, streak, XP and spaced-repetition (FSRS) reviews on your machine.",
+  "keywords": [
+    "language-learning",
+    "spaced-repetition",
+    "fsrs",
+    "mcp",
+    "mcp-server",
+    "claude",
+    "claude-code",
+    "tutor",
+    "flashcards",
+    "vocabulary"
+  ],
+  "homepage": "https://github.com/oktaybilge1/langcoach#readme",
+  "bugs": {
+    "url": "https://github.com/oktaybilge1/langcoach/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oktaybilge1/langcoach.git",
+    "directory": "packages/mcp"
+  },
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "langcoach": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "prepack": "npm run build && node scripts/copy-docs.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "ts-fsrs": "^5.4.2",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@langcoach/core": "*",
+    "tsup": "^9.0.0"
+  }
+}