@nado-language/mcp 0.1.6 → 0.1.8

package/README.md

@@ -7,6 +7,7 @@ This stdio MCP server lets AI chat clients save and practice Nado Language study
 - `nado_whoami`: validates the configured Nado account.
 - `nado_save_flashcard`: saves a structured flashcard generated by the user's chat AI. Nado does not call AI for this path.
 - `nado_save_study_item`: alias of `nado_save_flashcard` for natural memorization requests such as "암기할래", "외울래", "암기장에 넣어줘", and "단어장에 추가".
+- `nado_update_study_item`: updates an existing saved Nado card with a revised meaning, description/explanation, examples, variants, or context. Use it for requests like "hello 설명 추가", "description 추가", "뜻 수정", and "예문 추가".
 - `nado_analyze_and_save_flashcard`: Pro/Admin only. Nado AI generates the learner definition, usage note, examples, and variants, then saves the flashcard.
 - `nado_list_study_items`: loads saved flashcards for the authenticated user.
 - `nado_generate_practice`: builds practice exercises from saved flashcards only.
@@ -15,7 +16,8 @@ The default MCP path is designed to avoid double charging for AI. ChatGPT, Claud
 
 Intent routing:
 
-- If the user provides a new English item and says "암기할래", "외울래", "암기장에 추가", "단어장에 넣어줘", "remember this", or "add this to my flashcards", use `nado_save_flashcard` or `nado_save_study_item`.
+- If the user provides a new English item and says "나두 암기장", "nado 암기장", "암기할래", "외울래", "암기장에 추가", "단어장에 넣어줘", "remember this", or "add this to my flashcards", use `nado_save_flashcard` or `nado_save_study_item`. Do not create local Markdown files or Google Drive documents for these Nado requests.
+- If the user asks to add or change description/설명/뜻/예문 on an already saved card, use `nado_update_study_item`.
 - If the user asks to study already saved cards with phrases like "외울래", "암기 연습", "퀴즈 내줘", "쓰기연습", "영작하기", or "복습할래", use `nado_generate_practice`.
 - If the user wants to inspect saved items first, use `nado_list_study_items`.
 
@@ -161,6 +163,8 @@ For Codex, the command uses the Codex CLI when it is on `PATH`. If the user only
 
 Restart Codex Desktop after login completes.
 If a client was already open, start a new chat/session after restart. Most local MCP clients load tool definitions when the session starts, so a config that was just written may not appear inside an already-running conversation.
+For Codex, confirm the server is active from the chat/TUI with `/mcp`. A server can appear in Settings while still failing to start for the current session.
+On Windows, leave the Codex MCP working directory/cwd empty unless it is an existing absolute path. The Nado server does not need a working directory, and a value such as `~/code` can prevent the stdio process from starting if the client does not expand it.
 
 ChatGPT is different: it uses hosted/remote MCP apps configured from ChatGPT Apps settings, not local stdio config files. The local package can prepare local clients such as Codex, Claude Desktop, OpenCode, and generic JSON-based MCP clients.
 

package/dist/nado-language-server.mjs

@@ -43,6 +43,7 @@ const saveFlashcardInputSchema = {
     definition: { type: 'string', minLength: 1, description: 'Learner-language definition or translation generated by the chat AI.' },
     inlineDefinition: { type: 'string', description: 'Short review-side meaning. Defaults to a compact definition.' },
     explanation: { type: 'string', description: 'Optional nuance, usage note, or grammar explanation.' },
+    description: { type: 'string', description: 'Alias for explanation when the user asks for a description/설명 field.' },
     exampleSentences: {
       type: 'array',
       items: { type: 'string' },
@@ -64,6 +65,38 @@ const saveFlashcardInputSchema = {
   additionalProperties: false,
 };
 
+const updateStudyItemInputSchema = {
+  type: 'object',
+  required: ['query'],
+  properties: {
+    query: {
+      type: 'string',
+      minLength: 1,
+      description: 'Saved Nado card id, exact original text, or search text to update. Example: for "hello 설명 추가해줘", use "hello".',
+    },
+    definition: { type: 'string', description: 'Replacement learner-language definition/meaning. Use for 뜻/의미 수정 requests.' },
+    inlineDefinition: { type: 'string', description: 'Replacement short review-side meaning.' },
+    explanation: { type: 'string', description: 'Replacement usage note or explanation. Use this for 설명/description 추가 requests.' },
+    description: { type: 'string', description: 'Alias for explanation when the user says description.' },
+    exampleSentences: {
+      type: 'array',
+      items: { type: 'string' },
+      description: 'Example sentences to append by default, or replace when appendExampleSentences is false.',
+    },
+    appendExampleSentences: { type: 'boolean', default: true },
+    variants: {
+      type: 'array',
+      items: { type: 'string' },
+      description: 'Related forms, collocations, or variants to append by default, or replace when appendVariants is false.',
+    },
+    appendVariants: { type: 'boolean', default: true },
+    contextSentence: { type: 'string', description: 'Replacement context sentence.' },
+    sourceLang: { type: 'string', description: 'Replacement user language for definitions.' },
+    targetLang: { type: 'string', description: 'Replacement language being learned.' },
+  },
+  additionalProperties: false,
+};
+
 const tools = [
   {
     name: 'nado_whoami',
@@ -76,14 +109,19 @@ const tools = [
   },
   {
     name: 'nado_save_flashcard',
-    description: 'Save a structured Nado Language flashcard that the chat model already generated. Use this when the user gives an English item and asks to memorize/save it, for example "암기장에 추가해줘", "암기할래", "외울래", "단어장에 넣어줘", "remember this", or "add this to my flashcards". This does not call Nado AI; the user/chat AI supplies the content quality.',
+    description: 'Save a structured flashcard to the user\'s Nado Language/Nado 암기장. Use this when the user gives a new English item and asks to memorize/save it, for example "나두 암기장에 추가해줘", "nado 암기장에 넣어줘", "암기장에 추가해줘", "암기할래", "외울래", "단어장에 넣어줘", "remember this", or "add this to my flashcards". Do not create local Markdown files or Google Drive documents for these Nado requests. This does not call Nado AI; the user/chat AI supplies the content quality.',
     inputSchema: saveFlashcardInputSchema,
   },
   {
     name: 'nado_save_study_item',
-    description: 'Alias of nado_save_flashcard for study-list and memorization intents. Prefer this or nado_save_flashcard when the user asks to save a specific word/phrase/sentence to Nado for later memorization, including Korean requests like "암기할래", "외울래", "암기장에 넣어줘", or "단어장에 추가". This free path does not call Nado AI.',
+    description: 'Alias of nado_save_flashcard for Nado Language study-list and memorization intents. Prefer this or nado_save_flashcard when the user asks to save a specific word/phrase/sentence to Nado for later memorization, including Korean requests like "나두 암기장", "nado language", "암기할래", "외울래", "암기장에 넣어줘", or "단어장에 추가". Do not answer by editing local files or Drive docs when the user names Nado/Nado MCP. This free path does not call Nado AI.',
     inputSchema: saveFlashcardInputSchema,
   },
+  {
+    name: 'nado_update_study_item',
+    description: 'Update an existing saved card in the user\'s Nado Language/Nado 암기장. Use this for requests like "나두 암기장에 hello description 추가해줘", "hello 설명 추가", "뜻 수정", "예문 추가", or "update my saved Nado card". The query selects an existing saved card; explanation/description maps to the card explanation field. This updates Nado storage, not a local file or Google Drive document.',
+    inputSchema: updateStudyItemInputSchema,
+  },
   {
     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. Use only when the user explicitly wants Nado-verified/pro quality analysis or examples; normal memorize/save requests should use nado_save_flashcard so the user AI supplies the content.',
@@ -496,7 +534,7 @@ function normalizeFlashcardDraft(args) {
 
   const type = FLASHCARD_TYPES.has(args.type) ? args.type : inferFlashcardType(original);
   const definition = clampText(args.definition || '', 4000);
-  const explanation = clampText(args.explanation || '', 4000);
+  const explanation = clampText(args.explanation || args.description || '', 4000);
   const inlineDefinition = clampText(
     args.inlineDefinition || compactDefinition(definition || explanation),
     1000,
@@ -636,6 +674,43 @@ function rowToFlashcard(row) {
   };
 }
 
+function flashcardToRow(card) {
+  return {
+    id: card.id,
+    source_highlight_id: card.sourceHighlightId ?? 'shared',
+    article_id: card.articleId ?? 'shared',
+    original: card.original,
+    type: card.type ?? 'phrase',
+    definition: card.definition ?? '',
+    inline_definition: card.inlineDefinition ?? '',
+    explanation: card.explanation ?? '',
+    example_sentences: card.exampleSentences ?? [],
+    variants: card.variants ?? [],
+    context_sentence: card.contextSentence ?? '',
+    context_start_index: typeof card.contextStartIndex === 'number' ? card.contextStartIndex : null,
+    context_end_index: typeof card.contextEndIndex === 'number' ? card.contextEndIndex : null,
+    source_lang: card.sourceLang ?? 'ko',
+    target_lang: card.targetLang ?? 'en',
+    excluded: card.excluded ?? false,
+    used_in_writing: card.usedInWriting ?? false,
+    used_in_writing_at: card.usedInWritingAt ?? null,
+    pending_ai: card.pendingAI ?? false,
+    stability: card.stability ?? 0,
+    difficulty: card.difficulty ?? 0,
+    elapsed_days: card.elapsedDays ?? 0,
+    scheduled_days: card.scheduledDays ?? 0,
+    reps: card.reps ?? 0,
+    lapses: card.lapses ?? 0,
+    state: card.state ?? 'new',
+    learning_step: card.learningStep ?? 0,
+    next_review_at: card.nextReviewAt ?? new Date().toISOString(),
+    last_review_at: card.lastReviewAt ?? null,
+    created_at: card.createdAt ?? new Date().toISOString(),
+    updated_at: card.updatedAt ?? new Date().toISOString(),
+    deleted: false,
+  };
+}
+
 async function loadStudyItems(args = {}) {
   const limit = parseLimit(args.limit, 20, 1, 100);
   const includeExcluded = args.includeExcluded === true;
@@ -653,6 +728,7 @@ async function loadStudyItems(args = {}) {
     .filter((card) => {
       if (!query) return true;
       const haystack = [
+        card.id,
         card.original,
         card.definition,
         card.inlineDefinition,
@@ -765,6 +841,94 @@ async function handleListStudyItems(args) {
   };
 }
 
+function mergeStringArray(current, incoming, append, maxItems) {
+  const next = asStringArray(incoming);
+  if (next.length === 0) return current ?? [];
+  const values = append === false ? next : [...(current ?? []), ...next];
+  const seen = new Set();
+  return values
+    .map((value) => clampText(value, 1000))
+    .filter(Boolean)
+    .filter((value) => {
+      const key = value.toLocaleLowerCase();
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    })
+    .slice(0, maxItems);
+}
+
+function selectStudyItemForUpdate(items, query) {
+  const normalized = query.toLocaleLowerCase();
+  const exact = items.find((item) => item.id === query || item.original.toLocaleLowerCase() === normalized);
+  if (exact) return exact;
+  if (items.length === 1) return items[0];
+  if (items.length === 0) throw new Error(`STUDY_ITEM_NOT_FOUND: ${query}`);
+  throw new Error(`AMBIGUOUS_STUDY_ITEM: ${items.length} saved cards matched "${query}". Narrow the query or use a card id from nado_list_study_items.`);
+}
+
+async function handleUpdateStudyItem(args) {
+  const query = clampText(args.query || '', 500);
+  if (!query) throw new Error('QUERY_REQUIRED');
+
+  const matches = await loadStudyItems({ query, limit: 20, includeExcluded: true });
+  const current = selectStudyItemForUpdate(matches, query);
+  const updated = { ...current };
+  let changed = false;
+
+  if (typeof args.definition === 'string') {
+    updated.definition = clampText(args.definition, 4000);
+    changed = true;
+  }
+  if (typeof args.inlineDefinition === 'string') {
+    updated.inlineDefinition = clampText(args.inlineDefinition, 1000);
+    changed = true;
+  }
+  if (typeof args.explanation === 'string' || typeof args.description === 'string') {
+    updated.explanation = clampText(args.explanation ?? args.description, 4000);
+    changed = true;
+  }
+  if (Array.isArray(args.exampleSentences)) {
+    updated.exampleSentences = mergeStringArray(current.exampleSentences, args.exampleSentences, args.appendExampleSentences, 6);
+    changed = true;
+  }
+  if (Array.isArray(args.variants)) {
+    updated.variants = mergeStringArray(current.variants, args.variants, args.appendVariants, 12);
+    changed = true;
+  }
+  if (typeof args.contextSentence === 'string') {
+    updated.contextSentence = clampText(args.contextSentence, 2200);
+    changed = true;
+  }
+  if (typeof args.sourceLang === 'string') {
+    updated.sourceLang = clampText(args.sourceLang, 8) || current.sourceLang;
+    changed = true;
+  }
+  if (typeof args.targetLang === 'string') {
+    updated.targetLang = clampText(args.targetLang, 8) || current.targetLang;
+    changed = true;
+  }
+
+  if (!changed) throw new Error('UPDATE_FIELDS_REQUIRED');
+  updated.updatedAt = new Date().toISOString();
+
+  const row = flashcardToRow(updated);
+  const saved = await callAppData({
+    action: 'upsertRows',
+    table: 'flashcards',
+    rows: [row],
+  });
+
+  return {
+    updated: true,
+    matchedCount: matches.length,
+    qualitySource: 'user_ai',
+    qualityPolicy: 'Nado updated the existing card without calling Nado AI. Content quality is supplied by the user/chat AI.',
+    persisted: saved,
+    flashcard: rowToFlashcard(row),
+  };
+}
+
 async function handleGeneratePractice(args) {
   const mode = String(args.mode || '');
   if (!PRACTICE_MODES.has(mode)) throw new Error(`UNSUPPORTED_PRACTICE_MODE: ${mode}`);
@@ -895,6 +1059,7 @@ async function callTool(name, args = {}) {
   if (name === 'nado_whoami') return handleWhoami();
   if (name === 'nado_save_flashcard') return handleSaveFlashcard(args);
   if (name === 'nado_save_study_item') return handleSaveFlashcard(args);
+  if (name === 'nado_update_study_item') return handleUpdateStudyItem(args);
   if (name === 'nado_analyze_and_save_flashcard') return handleAnalyzeAndSaveFlashcard(args);
   if (name === 'nado_list_study_items') return handleListStudyItems(args);
   if (name === 'nado_generate_practice') return handleGeneratePractice(args);

package/dist/nado-mcp-cli.mjs

@@ -30,7 +30,7 @@ const command = process.argv[2] || 'help';
 const args = process.argv.slice(3);
 
 try {
-  if (command === 'help' || command === '--help' || command === '-h') {
+  if (shouldPrintHelp(command, args)) {
     printHelp();
   } else if (command === 'version' || command === '--version' || command === '-v') {
     console.log(packageVersion);
@@ -256,10 +256,16 @@ async function doctor() {
   console.log(`Claude Desktop config: ${registrationText(claude)}`);
   console.log(`OpenCode config: ${registrationText(opencode)}`);
   console.log('');
+  console.log('Current AI chat visibility: not detectable from this CLI.');
+  console.log('A green local server check only proves the stdio server can list tools; it does not prove an already-open chat loaded them.');
+  console.log('');
   console.log('If the server check is ok but Nado tools are not visible in the AI app:');
-  console.log('  1. Fully quit and restart the desktop app after `nado-mcp connect`.');
-  console.log('  2. Start a new chat/session; existing sessions may not reload newly added MCP tools.');
-  console.log('  3. Run `nado-mcp status` for auth and `nado-mcp probe list` for local server tools.');
+  console.log('  1. In Codex, run `/mcp` in the chat/TUI and confirm nado-language is active, not only listed in Settings.');
+  console.log('  2. Fully quit and restart the desktop app after `nado-mcp connect`.');
+  console.log('  3. Start a new chat/session; existing sessions may not reload newly added MCP tools.');
+  console.log('  4. On Windows, remove Working directory/cwd unless it is an existing absolute path. The Nado server does not need cwd.');
+  console.log('  5. Run `nado-mcp status` for auth and `nado-mcp probe list` for local server tools.');
+  console.log('  6. If a chat tries local files or Google Drive for "나두/Nado 암기장", that chat did not load the Nado MCP tools.');
 }
 
 function printToolProbeSummary() {
@@ -532,6 +538,11 @@ function commandExists(commandName) {
   return !result.error && result.status === 0;
 }
 
+function shouldPrintHelp(currentCommand, currentArgs) {
+  if (currentCommand === 'help' || currentCommand === '--help' || currentCommand === '-h') return true;
+  return currentArgs.includes('--help') || currentArgs.includes('-h');
+}
+
 function codexDesktopTomlSection() {
   const spec = stdioServerSpec();
   return [
@@ -630,6 +641,8 @@ function printUnknownClientSetup(client) {
 function printLoginNext(flow = {}) {
   if (flow.loginAfter) console.log('Browser login will open next.');
   else console.log('Next: run `nado-mcp login`.');
+  console.log('After login: fully restart the AI desktop app and start a new chat so it reloads MCP tools.');
+  console.log('If the chat still cannot see Nado tools, run `nado-mcp doctor`.');
 }
 
 function printIndented(text) {
@@ -827,8 +840,8 @@ Usage:
   nado-mcp status                     Show local auth status
   nado-mcp logout                     Remove local auth tokens
   nado-mcp server                     Start the stdio MCP server
-  nado-mcp probe list                 List exposed MCP tools
-  nado-mcp doctor                     Print local paths and auth status
+  nado-mcp probe list                 List local MCP server tools, not saved flashcards
+  nado-mcp doctor                     Diagnose local server, client config, auth, and chat reload state
   nado-mcp --version                  Print installed Nado MCP version
 
 Supported automatic setup clients:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nado-language/mcp",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Nado Language MCP server for saving AI-generated English flashcards and practicing saved materials.",
   "type": "module",
   "private": false,