@nado-language/mcp 0.1.0

package/dist/nado-language-server.mjs

@@ -0,0 +1,1020 @@
+#!/usr/bin/env node
+
+import { chmodSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DEFAULT_SUPABASE_URL = 'https://ptbwzhxifxdnfmqsiugi.supabase.co';
+const DEFAULT_SUPABASE_ANON_KEY = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InB0Ynd6aHhpZnhkbmZtcXNpdWdpIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzU1MTU4MjEsImV4cCI6MjA5MTA5MTgyMX0.c0SU8lvIb8BbwhYyI529dn7tQUfwTl1cGqeahGKaD_g';
+
+const SERVER_NAME = 'nado-language';
+const SERVER_VERSION = '0.1.0';
+const SUPPORTED_PROTOCOLS = ['2025-06-18', '2025-03-26', '2024-11-05'];
+const SERVER_DIR = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(SERVER_DIR, '..');
+
+let authEnvFilePath = process.env.NADO_MCP_AUTH_ENV_FILE || null;
+
+loadLocalEnvFiles();
+
+const env = process.env;
+const SUPABASE_URL = normalizeUrl(env.NADO_MCP_SUPABASE_URL || env.EXPO_PUBLIC_SUPABASE_URL || DEFAULT_SUPABASE_URL);
+const SUPABASE_ANON_KEY = env.NADO_MCP_SUPABASE_ANON_KEY || env.EXPO_PUBLIC_SUPABASE_ANON_KEY || DEFAULT_SUPABASE_ANON_KEY;
+const FUNCTIONS_URL = normalizeUrl(env.NADO_MCP_FUNCTIONS_URL || `${SUPABASE_URL}/functions/v1`);
+const DEVICE_ID = env.NADO_MCP_DEVICE_ID || `nado-mcp-${crypto.randomUUID()}`;
+
+let cachedPasswordGrant = null;
+let cachedRefreshGrant = null;
+
+const FLASHCARD_TYPES = new Set(['word', 'phrase', 'sentence_structure']);
+const PRACTICE_MODES = new Set(['writing', 'vocabulary_quiz', 'conversation', 'sentence_completion', 'translation']);
+
+const tools = [
+  {
+    name: 'nado_whoami',
+    description: 'Validate the configured Nado Language user and return profile metadata.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'nado_save_flashcard',
+    description: 'Save a structured flashcard that the chat model already generated. This does not call Nado AI; the user/chat AI is responsible for content quality.',
+    inputSchema: {
+      type: 'object',
+      required: ['original', 'definition'],
+      properties: {
+        original: { type: 'string', minLength: 1, description: 'English word, phrase, or sentence to save.' },
+        type: { type: 'string', enum: ['word', 'phrase', 'sentence_structure'], default: 'phrase' },
+        definition: { type: 'string', minLength: 1, description: 'Learner-language definition or translation.' },
+        inlineDefinition: { type: 'string', description: 'Short review-side meaning. Defaults to a compact definition.' },
+        explanation: { type: 'string', description: 'Optional nuance, usage note, or grammar explanation.' },
+        exampleSentences: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Optional examples generated by the user chat AI.',
+        },
+        variants: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Optional related forms, collocations, or variants.',
+        },
+        contextSentence: { type: 'string', description: 'Original sentence/context from the chat. Defaults to text.' },
+        articleTitle: { type: 'string', description: 'Source title shown in analysis. Defaults to MCP Chat.' },
+        sourceLang: { type: 'string', default: 'ko', description: 'User language for definitions.' },
+        targetLang: { type: 'string', default: 'en', description: 'Language being learned.' },
+        userLevel: { type: 'string', default: 'B1', description: 'CEFR level used by Nado analysis.' },
+        articleId: { type: 'string', default: 'mcp-chat' },
+        sourceHighlightId: { type: 'string', default: 'mcp-chat' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'nado_analyze_and_save_flashcard',
+    description: 'Pro/Admin only: use Nado AI to produce validated definitions/examples for a word, phrase, or sentence, then save the flashcard.',
+    inputSchema: {
+      type: 'object',
+      required: ['original'],
+      properties: {
+        original: { type: 'string', minLength: 1, description: 'English word, phrase, or sentence to analyze and save with Nado AI.' },
+        contextSentence: { type: 'string', description: 'Original sentence/context from the chat. Defaults to original.' },
+        articleTitle: { type: 'string', description: 'Source title shown in analysis. Defaults to MCP Chat.' },
+        sourceLang: { type: 'string', default: 'ko', description: 'User language for definitions.' },
+        targetLang: { type: 'string', default: 'en', description: 'Language being learned.' },
+        userLevel: { type: 'string', default: 'B1', description: 'CEFR level used by Nado analysis.' },
+        articleId: { type: 'string', default: 'mcp-chat' },
+        sourceHighlightId: { type: 'string', default: 'mcp-chat' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'nado_list_study_items',
+    description: 'Load saved Nado Language vocabulary and sentence cards for practice.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Optional substring filter over original/context/definition.' },
+        limit: { type: 'number', default: 20, minimum: 1, maximum: 100 },
+        includeExcluded: { type: 'boolean', default: false },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'nado_generate_practice',
+    description: 'Generate English practice content using only the authenticated user saved Nado Language study cards.',
+    inputSchema: {
+      type: 'object',
+      required: ['mode'],
+      properties: {
+        mode: {
+          type: 'string',
+          enum: ['writing', 'vocabulary_quiz', 'conversation', 'sentence_completion', 'translation'],
+        },
+        query: { type: 'string', description: 'Optional substring filter over saved cards before practice generation.' },
+        limit: { type: 'number', default: 5, minimum: 1, maximum: 20 },
+      },
+      additionalProperties: false,
+    },
+  },
+];
+
+function normalizeUrl(value) {
+  return String(value || '').replace(/\/+$/, '');
+}
+
+function loadLocalEnvFiles() {
+  if (process.env.NADO_MCP_SKIP_DOTENV === '1') return;
+
+  const candidates = [
+    authEnvFilePath,
+    path.join(process.cwd(), '.env.mcp.local'),
+    path.join(process.cwd(), '.env.local'),
+    path.join(REPO_ROOT, '.env.mcp.local'),
+    path.join(REPO_ROOT, '.env.local'),
+    defaultUserAuthEnvFile(),
+  ].filter(Boolean);
+
+  for (const filePath of [...new Set(candidates)]) {
+    if (!authEnvFilePath && existsSync(filePath) && (path.basename(filePath) === '.env.mcp.local' || filePath === defaultUserAuthEnvFile())) {
+      authEnvFilePath = filePath;
+    }
+    loadEnvFile(filePath);
+  }
+}
+
+function defaultUserAuthEnvFile() {
+  if (process.platform === 'win32') {
+    return path.join(process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming'), 'Nado', 'MCP', 'auth.env');
+  }
+  if (process.platform === 'darwin') {
+    return path.join(os.homedir(), 'Library', 'Application Support', 'Nado', 'MCP', 'auth.env');
+  }
+  return path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'nado', 'mcp', 'auth.env');
+}
+
+function loadEnvFile(filePath) {
+  if (!existsSync(filePath)) return;
+
+  const lines = readFileSync(filePath, 'utf8').split(/\r?\n/);
+  for (const line of lines) {
+    const parsed = parseEnvLine(line);
+    if (!parsed) continue;
+    const { key, value } = parsed;
+    if (Object.prototype.hasOwnProperty.call(process.env, key)) continue;
+    process.env[key] = value;
+  }
+}
+
+function parseEnvLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith('#')) return null;
+
+  const withoutExport = trimmed.startsWith('export ') ? trimmed.slice('export '.length).trimStart() : trimmed;
+  const separator = withoutExport.indexOf('=');
+  if (separator <= 0) return null;
+
+  const key = withoutExport.slice(0, separator).trim();
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) return null;
+
+  let value = withoutExport.slice(separator + 1).trim();
+  const quote = value[0];
+  if ((quote === '"' || quote === "'") && value.endsWith(quote)) {
+    value = value.slice(1, -1);
+  } else {
+    value = value.replace(/\s+#.*$/, '').trim();
+  }
+
+  return { key, value };
+}
+
+function clampText(value, max) {
+  return typeof value === 'string' ? value.trim().slice(0, max) : '';
+}
+
+function asStringArray(value, fallback = []) {
+  if (!Array.isArray(value)) return fallback;
+  return value.map((item) => String(item || '').trim()).filter(Boolean);
+}
+
+function parseLimit(value, fallback, min, max) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.min(max, Math.max(min, Math.trunc(parsed)));
+}
+
+function tokenFromEnv() {
+  const token = clampText(env.NADO_MCP_ACCESS_TOKEN || env.NADO_ACCESS_TOKEN || '', 10000);
+  return token || null;
+}
+
+function refreshTokenFromEnv() {
+  const token = clampText(env.NADO_MCP_REFRESH_TOKEN || env.NADO_REFRESH_TOKEN || '', 10000);
+  return token || null;
+}
+
+async function getAccessToken() {
+  const directToken = tokenFromEnv();
+  const refreshToken = refreshTokenFromEnv();
+
+  if (directToken && !tokenNeedsRefresh(directToken)) return directToken;
+
+  if (refreshToken) {
+    if (
+      cachedRefreshGrant
+      && cachedRefreshGrant.sourceRefreshToken === refreshToken
+      && cachedRefreshGrant.expiresAt > Date.now() + 60_000
+    ) {
+      return cachedRefreshGrant.accessToken;
+    }
+
+    try {
+      return await refreshAccessToken(refreshToken);
+    } catch (error) {
+      if (directToken && !tokenIsExpired(directToken)) return directToken;
+      throw error;
+    }
+  }
+
+  if (directToken) return directToken;
+
+  const email = clampText(env.NADO_MCP_EMAIL || '', 320);
+  const password = env.NADO_MCP_PASSWORD || '';
+  if (!email || !password) {
+    throw new Error('AUTH_NOT_CONFIGURED: run `nado-mcp login`, or in a repo checkout run `npm run mcp:nado:auth -- --provider google`, before using Nado MCP tools.');
+  }
+
+  if (cachedPasswordGrant && cachedPasswordGrant.expiresAt > Date.now() + 60_000) {
+    return cachedPasswordGrant.accessToken;
+  }
+
+  const response = await fetch(`${SUPABASE_URL}/auth/v1/token?grant_type=password`, {
+    method: 'POST',
+    headers: {
+      apikey: SUPABASE_ANON_KEY,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ email, password }),
+  });
+
+  const body = await readJsonResponse(response);
+  if (!response.ok || !body.access_token) {
+    throw new Error(`AUTH_FAILED: ${response.status} ${body.error_description || body.error || body.msg || 'password grant failed'}`);
+  }
+
+  cachedPasswordGrant = {
+    accessToken: body.access_token,
+    expiresAt: Date.now() + Math.max(0, Number(body.expires_in || 3600) * 1000),
+  };
+  return cachedPasswordGrant.accessToken;
+}
+
+async function refreshAccessToken(refreshToken) {
+  const response = await fetch(`${SUPABASE_URL}/auth/v1/token?grant_type=refresh_token`, {
+    method: 'POST',
+    headers: {
+      apikey: SUPABASE_ANON_KEY,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ refresh_token: refreshToken }),
+  });
+
+  const body = await readJsonResponse(response);
+  if (!response.ok || !body.access_token) {
+    throw new Error(`AUTH_REFRESH_FAILED: ${response.status} ${body.error_description || body.error || body.msg || 'refresh token grant failed'}`);
+  }
+
+  const rotatedRefreshToken = body.refresh_token || refreshToken;
+  const expiresAt = jwtExpiresAtMs(body.access_token) ?? (Date.now() + Math.max(0, Number(body.expires_in || 3600) * 1000));
+
+  cachedRefreshGrant = {
+    accessToken: body.access_token,
+    sourceRefreshToken: rotatedRefreshToken,
+    expiresAt,
+  };
+
+  persistAuthSession({
+    access_token: body.access_token,
+    refresh_token: rotatedRefreshToken,
+  });
+
+  return cachedRefreshGrant.accessToken;
+}
+
+function tokenNeedsRefresh(token) {
+  const expiresAt = jwtExpiresAtMs(token);
+  return expiresAt !== null && expiresAt <= Date.now() + 60_000;
+}
+
+function tokenIsExpired(token) {
+  const expiresAt = jwtExpiresAtMs(token);
+  return expiresAt !== null && expiresAt <= Date.now();
+}
+
+function jwtExpiresAtMs(token) {
+  const parts = String(token || '').split('.');
+  if (parts.length < 2) return null;
+  try {
+    const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+    const exp = Number(payload.exp);
+    return Number.isFinite(exp) ? exp * 1000 : null;
+  } catch {
+    return null;
+  }
+}
+
+function persistAuthSession(session) {
+  if (!session?.access_token) return;
+
+  process.env.NADO_MCP_ACCESS_TOKEN = session.access_token;
+  if (session.refresh_token) process.env.NADO_MCP_REFRESH_TOKEN = session.refresh_token;
+
+  if (process.env.NADO_MCP_DISABLE_AUTH_PERSIST === '1') return;
+
+  const filePath = process.env.NADO_MCP_AUTH_ENV_FILE || authEnvFilePath;
+  if (!filePath) return;
+
+  try {
+    updateEnvFile(filePath, {
+      NADO_MCP_ACCESS_TOKEN: session.access_token,
+      NADO_MCP_REFRESH_TOKEN: session.refresh_token,
+    });
+  } catch (error) {
+    console.error(`Nado MCP auth refresh succeeded but token persistence failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+function updateEnvFile(filePath, updates) {
+  const nextUpdates = Object.fromEntries(
+    Object.entries(updates).filter(([, value]) => typeof value === 'string' && value.length > 0),
+  );
+  if (Object.keys(nextUpdates).length === 0) return;
+
+  const seen = new Set();
+  const existingLines = existsSync(filePath) ? readFileSync(filePath, 'utf8').split(/\r?\n/) : [];
+  const lines = existingLines.map((line) => {
+    const parsed = parseEnvLine(line);
+    if (!parsed || !(parsed.key in nextUpdates)) return line;
+    seen.add(parsed.key);
+    return `${parsed.key}=${formatEnvValue(nextUpdates[parsed.key])}`;
+  });
+
+  for (const [key, value] of Object.entries(nextUpdates)) {
+    if (!seen.has(key)) lines.push(`${key}=${formatEnvValue(value)}`);
+  }
+
+  writeFileSync(filePath, `${lines.filter((line, index) => index < lines.length - 1 || line).join('\n')}\n`, { mode: 0o600 });
+  try {
+    chmodSync(filePath, 0o600);
+  } catch {
+    // Best effort. Some filesystems do not support chmod.
+  }
+}
+
+function formatEnvValue(value) {
+  if (/^[A-Za-z0-9_./:@-]+$/.test(value)) return value;
+  return JSON.stringify(value);
+}
+
+async function readJsonResponse(response) {
+  const text = await response.text();
+  if (!text) return {};
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { raw: text };
+  }
+}
+
+async function fetchJson(url, options) {
+  const response = await fetch(url, options);
+  const body = await readJsonResponse(response);
+  if (!response.ok) {
+    const message = body.message || body.error_description || body.error || body.raw || response.statusText;
+    throw new Error(`HTTP_${response.status}: ${message}`);
+  }
+  return body;
+}
+
+async function callAppData(actionBody) {
+  const token = await getAccessToken();
+  const body = await fetchJson(`${FUNCTIONS_URL}/app-data`, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${token}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(actionBody),
+  });
+
+  if (body.error) {
+    throw new Error(`${body.error}: ${body.message || 'app-data call failed'}`);
+  }
+  return body.data ?? body;
+}
+
+async function analyzeForFlashcard(args) {
+  const token = await getAccessToken();
+  const text = clampText(args.original || args.text, 3000);
+  if (!text) throw new Error('TEXT_REQUIRED');
+
+  const contextSentence = clampText(args.contextSentence || text, 2200) || text;
+  const articleTitle = clampText(args.articleTitle || 'MCP Chat', 180) || 'MCP Chat';
+  const sourceLang = clampText(args.sourceLang || 'ko', 8) || 'ko';
+  const targetLang = clampText(args.targetLang || 'en', 8) || 'en';
+  const userLevel = clampText(args.userLevel || 'B1', 8) || 'B1';
+
+  const body = await fetchJson(`${FUNCTIONS_URL}/ai-proxy`, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${token}`,
+      'x-device-id': DEVICE_ID,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      action: 'analyze',
+      text,
+      contextSentence,
+      articleTitle,
+      sourceLang,
+      targetLang,
+      userLevel,
+    }),
+  });
+
+  if (body.error) throw new Error(`${body.error}: ai-proxy analyze failed`);
+  if (!body.data || typeof body.data !== 'object') throw new Error('ANALYZE_EMPTY_RESULT');
+
+  return {
+    analysis: normalizeAnalysis(body.data),
+    remaining: body.remaining,
+    isPro: body.isPro,
+    contextSentence,
+    articleTitle,
+    sourceLang,
+    targetLang,
+  };
+}
+
+function normalizeAnalysis(data) {
+  const type = ['word', 'phrase', 'sentence_structure'].includes(data.type) ? data.type : 'phrase';
+  const definition = clampText(data.definition, 4000);
+  const inlineDefinition = clampText(data.inlineDefinition || definition.split(',')[0] || '', 1000);
+  const explanation = clampText(data.explanation, 4000);
+  const exampleSentences = asStringArray(data.exampleSentences).slice(0, 6);
+  const variants = asStringArray(data.variants).slice(0, 12);
+
+  return {
+    type,
+    definition,
+    inlineDefinition,
+    explanation,
+    exampleSentences,
+    variants,
+  };
+}
+
+function normalizeFlashcardDraft(args) {
+  const original = clampText(args.original || args.text, 3000);
+  if (!original) throw new Error('ORIGINAL_REQUIRED');
+
+  const type = FLASHCARD_TYPES.has(args.type) ? args.type : inferFlashcardType(original);
+  const definition = clampText(args.definition || '', 4000);
+  const explanation = clampText(args.explanation || '', 4000);
+  const inlineDefinition = clampText(
+    args.inlineDefinition || compactDefinition(definition || explanation),
+    1000,
+  );
+
+  if (!definition && !inlineDefinition && !explanation) {
+    throw new Error('DEFINITION_REQUIRED');
+  }
+
+  return {
+    original,
+    type,
+    definition: definition || inlineDefinition || explanation,
+    inlineDefinition: inlineDefinition || compactDefinition(definition || explanation),
+    explanation,
+    exampleSentences: asStringArray(args.exampleSentences).slice(0, 6),
+    variants: asStringArray(args.variants).slice(0, 12),
+    contextSentence: clampText(args.contextSentence || original, 2200) || original,
+    articleTitle: clampText(args.articleTitle || 'MCP Chat', 180) || 'MCP Chat',
+    sourceLang: clampText(args.sourceLang || 'ko', 8) || 'ko',
+    targetLang: clampText(args.targetLang || 'en', 8) || 'en',
+  };
+}
+
+function compactDefinition(value) {
+  const text = clampText(value || '', 1000);
+  return text.split(/\n|,/)[0]?.trim() || text;
+}
+
+function inferFlashcardType(original) {
+  const trimmed = original.trim();
+  if (!trimmed) return 'phrase';
+  if (/[.!?。！？]\s*$/.test(trimmed) || trimmed.split(/\s+/).length > 6) return 'sentence_structure';
+  if (/^[A-Za-z][A-Za-z'-]*$/.test(trimmed)) return 'word';
+  return 'phrase';
+}
+
+function buildFlashcardRow(args, analyzed) {
+  const now = new Date().toISOString();
+  const original = clampText(args.original || args.text, 3000);
+  const sourceHighlightId = clampText(args.sourceHighlightId || 'mcp-chat', 120) || 'mcp-chat';
+  const articleId = clampText(args.articleId || 'mcp-chat', 120) || 'mcp-chat';
+  const contextSentence = analyzed.contextSentence || original;
+  const startIndex = contextSentence.toLocaleLowerCase().indexOf(original.toLocaleLowerCase());
+  const endIndex = startIndex >= 0 ? startIndex + original.length : null;
+
+  return {
+    id: `mcp-${crypto.randomUUID()}`,
+    source_highlight_id: sourceHighlightId,
+    article_id: articleId,
+    original,
+    type: analyzed.analysis.type,
+    definition: analyzed.analysis.definition,
+    inline_definition: analyzed.analysis.inlineDefinition,
+    explanation: analyzed.analysis.explanation,
+    example_sentences: analyzed.analysis.exampleSentences,
+    variants: analyzed.analysis.variants,
+    context_sentence: contextSentence,
+    context_start_index: startIndex >= 0 ? startIndex : null,
+    context_end_index: endIndex,
+    source_lang: analyzed.sourceLang,
+    target_lang: analyzed.targetLang,
+    excluded: false,
+    used_in_writing: false,
+    used_in_writing_at: null,
+    pending_ai: false,
+    stability: 0,
+    difficulty: 0,
+    elapsed_days: 0,
+    scheduled_days: 0,
+    reps: 0,
+    lapses: 0,
+    state: 'new',
+    learning_step: 0,
+    next_review_at: now,
+    last_review_at: null,
+    created_at: now,
+    updated_at: now,
+    deleted: false,
+  };
+}
+
+function buildStructuredFlashcardRow(args) {
+  const card = normalizeFlashcardDraft(args);
+  return buildFlashcardRow(
+    { ...args, original: card.original },
+    {
+      analysis: {
+        type: card.type,
+        definition: card.definition,
+        inlineDefinition: card.inlineDefinition,
+        explanation: card.explanation,
+        exampleSentences: card.exampleSentences,
+        variants: card.variants,
+      },
+      contextSentence: card.contextSentence,
+      articleTitle: card.articleTitle,
+      sourceLang: card.sourceLang,
+      targetLang: card.targetLang,
+    },
+  );
+}
+
+function rowToFlashcard(row) {
+  return {
+    id: row.id,
+    sourceHighlightId: row.source_highlight_id ?? 'shared',
+    articleId: row.article_id ?? 'shared',
+    original: row.original,
+    type: row.type ?? 'phrase',
+    definition: row.definition ?? '',
+    inlineDefinition: row.inline_definition ?? undefined,
+    explanation: row.explanation ?? '',
+    exampleSentences: row.example_sentences ?? [],
+    variants: row.variants ?? [],
+    contextSentence: row.context_sentence ?? '',
+    contextStartIndex: typeof row.context_start_index === 'number' ? row.context_start_index : undefined,
+    contextEndIndex: typeof row.context_end_index === 'number' ? row.context_end_index : undefined,
+    sourceLang: row.source_lang ?? 'ko',
+    targetLang: row.target_lang ?? 'en',
+    excluded: row.excluded ?? false,
+    usedInWriting: row.used_in_writing ?? false,
+    usedInWritingAt: row.used_in_writing_at ?? undefined,
+    pendingAI: row.pending_ai ?? false,
+    stability: row.stability ?? 0,
+    difficulty: row.difficulty ?? 0,
+    elapsedDays: row.elapsed_days ?? 0,
+    scheduledDays: row.scheduled_days ?? 0,
+    reps: row.reps ?? 0,
+    lapses: row.lapses ?? 0,
+    state: row.state ?? 'new',
+    learningStep: row.learning_step ?? 0,
+    nextReviewAt: row.next_review_at ?? new Date().toISOString(),
+    lastReviewAt: row.last_review_at ?? null,
+    createdAt: row.created_at ?? new Date().toISOString(),
+    updatedAt: row.updated_at ?? row.created_at,
+  };
+}
+
+async function loadStudyItems(args = {}) {
+  const limit = parseLimit(args.limit, 20, 1, 100);
+  const includeExcluded = args.includeExcluded === true;
+  const query = clampText(args.query || '', 500).toLocaleLowerCase();
+  const rows = await callAppData({
+    action: 'selectRowsChangedSince',
+    table: 'flashcards',
+    updatedAfter: '1970-01-01T00:00:00.000Z',
+  });
+
+  const items = (Array.isArray(rows) ? rows : [])
+    .filter((row) => row && row.deleted !== true)
+    .filter((row) => includeExcluded || row.excluded !== true)
+    .map(rowToFlashcard)
+    .filter((card) => {
+      if (!query) return true;
+      const haystack = [
+        card.original,
+        card.definition,
+        card.inlineDefinition,
+        card.explanation,
+        card.contextSentence,
+        ...(card.exampleSentences || []),
+        ...(card.variants || []),
+      ].join('\n').toLocaleLowerCase();
+      return haystack.includes(query);
+    })
+    .sort((a, b) => String(b.updatedAt || b.createdAt).localeCompare(String(a.updatedAt || a.createdAt)))
+    .slice(0, limit);
+
+  return items;
+}
+
+async function handleWhoami() {
+  const token = await getAccessToken();
+  const user = await fetchJson(`${SUPABASE_URL}/auth/v1/user`, {
+    method: 'GET',
+    headers: {
+      apikey: SUPABASE_ANON_KEY,
+      Authorization: `Bearer ${token}`,
+    },
+  });
+  const profile = await callAppData({ action: 'selectProfile' });
+  return {
+    user: {
+      id: user.id,
+      email: user.email,
+      aud: user.aud,
+    },
+    profile,
+    supabaseUrl: SUPABASE_URL,
+  };
+}
+
+async function loadProfile() {
+  return await callAppData({ action: 'selectProfile' });
+}
+
+function isActiveProProfile(profile) {
+  if (!profile || profile.is_pro !== true) return false;
+  if (!profile.pro_expires_at) return true;
+  const expiresAt = Date.parse(profile.pro_expires_at);
+  return Number.isNaN(expiresAt) || expiresAt > Date.now();
+}
+
+async function requireProOrAdmin(feature) {
+  const profile = await loadProfile();
+  if (profile?.is_admin === true || isActiveProProfile(profile)) return profile;
+  throw new Error(`PRO_REQUIRED: ${feature} is available to Pro/Admin users. Use nado_save_flashcard for user-AI generated cards without Nado AI cost.`);
+}
+
+async function handleSaveFlashcard(args) {
+  const row = buildStructuredFlashcardRow(args);
+  const saved = await callAppData({
+    action: 'upsertRows',
+    table: 'flashcards',
+    rows: [row],
+  });
+
+  return {
+    saved: true,
+    qualitySource: 'user_ai',
+    qualityPolicy: 'Nado validated schema and saved the card without calling Nado AI. Content quality is supplied by the user/chat AI.',
+    persisted: saved,
+    flashcard: rowToFlashcard(row),
+    storage: {
+      table: 'flashcards',
+      articleId: row.article_id,
+      sourceHighlightId: row.source_highlight_id,
+    },
+  };
+}
+
+async function handleAnalyzeAndSaveFlashcard(args) {
+  const profile = await requireProOrAdmin('Nado AI flashcard analysis');
+  const analyzed = await analyzeForFlashcard(args);
+  const row = buildFlashcardRow({ ...args, original: args.original || args.text }, analyzed);
+  const saved = await callAppData({
+    action: 'upsertRows',
+    table: 'flashcards',
+    rows: [row],
+  });
+
+  return {
+    saved: true,
+    qualitySource: 'nado_ai',
+    qualityPolicy: 'Nado AI generated the learner definition, short meaning, usage explanation, examples, and variants for Pro/Admin quality.',
+    profileTier: profile?.is_admin === true ? 'admin' : 'pro',
+    persisted: saved,
+    remainingAiCalls: analyzed.remaining,
+    isPro: analyzed.isPro,
+    analysis: analyzed.analysis,
+    flashcard: rowToFlashcard(row),
+    storage: {
+      table: 'flashcards',
+      articleId: row.article_id,
+      sourceHighlightId: row.source_highlight_id,
+    },
+  };
+}
+
+async function handleListStudyItems(args) {
+  const items = await loadStudyItems(args);
+  return {
+    count: items.length,
+    items,
+  };
+}
+
+async function handleGeneratePractice(args) {
+  const mode = String(args.mode || '');
+  if (!PRACTICE_MODES.has(mode)) throw new Error(`UNSUPPORTED_PRACTICE_MODE: ${mode}`);
+
+  const limit = parseLimit(args.limit, 5, 1, 20);
+  const items = await loadStudyItems({ query: args.query, limit, includeExcluded: false });
+  if (items.length === 0) {
+    return {
+      mode,
+      onlySavedMaterials: true,
+      materialCount: 0,
+      exercises: [],
+      message: 'No saved study materials matched the request.',
+    };
+  }
+
+  return {
+    mode,
+    onlySavedMaterials: true,
+    materialPolicy: 'Exercises are generated from saved Nado flashcards only. Each exercise cites sourceCardIds.',
+    materialCount: items.length,
+    materials: items.map(compactCard),
+    exercises: buildPractice(mode, items),
+  };
+}
+
+function compactCard(card) {
+  return {
+    id: card.id,
+    original: card.original,
+    type: card.type,
+    definition: card.definition,
+    inlineDefinition: card.inlineDefinition,
+    contextSentence: card.contextSentence,
+    exampleSentences: card.exampleSentences,
+    variants: card.variants,
+  };
+}
+
+function buildPractice(mode, items) {
+  switch (mode) {
+    case 'writing':
+      return items.map((card, index) => ({
+        id: `writing-${index + 1}`,
+        type: 'writing',
+        prompt: `Write two original sentences that correctly use the saved item "${card.original}".`,
+        requiredSavedItems: [card.original],
+        referenceMeaning: card.inlineDefinition || card.definition,
+        sourceCardIds: [card.id],
+      }));
+
+    case 'vocabulary_quiz':
+      return items.map((card, index) => {
+        const distractors = items
+          .filter((candidate) => candidate.id !== card.id)
+          .map((candidate) => candidate.inlineDefinition || candidate.definition)
+          .filter(Boolean)
+          .slice(0, 3);
+        return {
+          id: `quiz-${index + 1}`,
+          type: 'vocabulary_quiz',
+          question: `Choose the saved meaning of "${card.original}".`,
+          options: shuffleStable([card.inlineDefinition || card.definition, ...distractors].filter(Boolean)),
+          answer: card.inlineDefinition || card.definition,
+          sourceCardIds: [card.id, ...items.filter((candidate) => candidate.id !== card.id).slice(0, 3).map((candidate) => candidate.id)],
+        };
+      });
+
+    case 'conversation':
+      return items.map((card, index) => ({
+        id: `conversation-${index + 1}`,
+        type: 'conversation',
+        prompt: `Continue a short conversation using the saved item "${card.original}" naturally.`,
+        context: card.contextSentence || card.exampleSentences?.[0] || card.original,
+        expectedFocus: card.inlineDefinition || card.definition,
+        sourceCardIds: [card.id],
+      }));
+
+    case 'sentence_completion':
+      return items.map((card, index) => ({
+        id: `completion-${index + 1}`,
+        type: 'sentence_completion',
+        question: makeBlank(card),
+        answer: card.original,
+        hint: card.inlineDefinition || card.definition,
+        sourceCardIds: [card.id],
+      }));
+
+    case 'translation':
+      return items.map((card, index) => ({
+        id: `translation-${index + 1}`,
+        type: 'translation',
+        prompt: `Translate the saved item or sentence: "${card.original}".`,
+        answer: card.inlineDefinition || card.definition,
+        context: card.contextSentence,
+        sourceCardIds: [card.id],
+      }));
+
+    default:
+      throw new Error(`UNSUPPORTED_PRACTICE_MODE: ${mode}`);
+  }
+}
+
+function makeBlank(card) {
+  const context = card.contextSentence || card.exampleSentences?.[0] || card.original;
+  if (!context || context === card.original) return '_____';
+  const index = context.toLocaleLowerCase().indexOf(card.original.toLocaleLowerCase());
+  if (index < 0) return `${context} [blank: ${card.original.length} chars]`;
+  return `${context.slice(0, index)}_____${context.slice(index + card.original.length)}`;
+}
+
+function shuffleStable(values) {
+  return values
+    .map((value, index) => ({ value, index, key: stableHash(`${value}:${index}`) }))
+    .sort((a, b) => a.key - b.key)
+    .map((entry) => entry.value);
+}
+
+function stableHash(value) {
+  let hash = 0;
+  for (let i = 0; i < value.length; i += 1) {
+    hash = (hash * 31 + value.charCodeAt(i)) >>> 0;
+  }
+  return hash;
+}
+
+async function callTool(name, args = {}) {
+  if (name === 'nado_whoami') return handleWhoami();
+  if (name === 'nado_save_flashcard') return handleSaveFlashcard(args);
+  if (name === 'nado_analyze_and_save_flashcard') return handleAnalyzeAndSaveFlashcard(args);
+  if (name === 'nado_save_study_item') return handleAnalyzeAndSaveFlashcard({ ...args, original: args.original || args.text });
+  if (name === 'nado_list_study_items') return handleListStudyItems(args);
+  if (name === 'nado_generate_practice') return handleGeneratePractice(args);
+  throw new Error(`UNKNOWN_TOOL: ${name}`);
+}
+
+function toolResult(result) {
+  return {
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(result, null, 2),
+      },
+    ],
+    structuredContent: result,
+  };
+}
+
+function toolError(error) {
+  const result = {
+    error: error instanceof Error ? error.message : String(error),
+  };
+  return {
+    isError: true,
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(result, null, 2),
+      },
+    ],
+    structuredContent: result,
+  };
+}
+
+async function handleRequest(request) {
+  const { id, method, params = {} } = request;
+  if (!method) return null;
+
+  if (method.startsWith('notifications/')) return null;
+
+  if (method === 'initialize') {
+    const requested = params.protocolVersion;
+    const protocolVersion = SUPPORTED_PROTOCOLS.includes(requested) ? requested : SUPPORTED_PROTOCOLS[0];
+    return {
+      jsonrpc: '2.0',
+      id,
+      result: {
+        protocolVersion,
+        capabilities: {
+          tools: {},
+        },
+        serverInfo: {
+          name: SERVER_NAME,
+          version: SERVER_VERSION,
+        },
+      },
+    };
+  }
+
+  if (method === 'ping') {
+    return { jsonrpc: '2.0', id, result: {} };
+  }
+
+  if (method === 'tools/list') {
+    return { jsonrpc: '2.0', id, result: { tools } };
+  }
+
+  if (method === 'tools/call') {
+    try {
+      const result = await callTool(params.name, params.arguments || {});
+      return { jsonrpc: '2.0', id, result: toolResult(result) };
+    } catch (error) {
+      return { jsonrpc: '2.0', id, result: toolError(error) };
+    }
+  }
+
+  return {
+    jsonrpc: '2.0',
+    id,
+    error: { code: -32601, message: `Method not found: ${method}` },
+  };
+}
+
+let inputBuffer = Buffer.alloc(0);
+
+process.stdin.on('data', (chunk) => {
+  inputBuffer = Buffer.concat([inputBuffer, chunk]);
+  void drainInput();
+});
+
+process.stdin.on('end', () => {
+  process.exit(0);
+});
+
+async function drainInput() {
+  while (true) {
+    const headerEnd = inputBuffer.indexOf('\r\n\r\n');
+    if (headerEnd < 0) return;
+
+    const header = inputBuffer.slice(0, headerEnd).toString('utf8');
+    const match = header.match(/content-length:\s*(\d+)/i);
+    if (!match) {
+      inputBuffer = inputBuffer.slice(headerEnd + 4);
+      continue;
+    }
+
+    const contentLength = Number(match[1]);
+    const frameEnd = headerEnd + 4 + contentLength;
+    if (inputBuffer.length < frameEnd) return;
+
+    const payload = inputBuffer.slice(headerEnd + 4, frameEnd).toString('utf8');
+    inputBuffer = inputBuffer.slice(frameEnd);
+
+    try {
+      const request = JSON.parse(payload);
+      const response = await handleRequest(request);
+      if (response) writeMessage(response);
+    } catch (error) {
+      writeMessage({
+        jsonrpc: '2.0',
+        id: null,
+        error: {
+          code: -32700,
+          message: error instanceof Error ? error.message : String(error),
+        },
+      });
+    }
+  }
+}
+
+function writeMessage(message) {
+  const payload = JSON.stringify(message);
+  process.stdout.write(`Content-Length: ${Buffer.byteLength(payload, 'utf8')}\r\n\r\n${payload}`);
+}