@nado-language/mcp 0.1.2 → 0.1.3

package/README.md

@@ -6,12 +6,19 @@ 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_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.
 
 The default MCP path is designed to avoid double charging for AI. ChatGPT, Claude, Codex, or another user-paid AI model should fill the structured flashcard fields, and Nado only validates/saves them. Nado AI quality generation is a separate Pro/Admin tool.
 
+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 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`.
+
 ## Authentication
 
 Install from npm:
@@ -139,6 +146,7 @@ For Codex, the command uses the Codex CLI when it is on `PATH`. If the user only
 - Windows: `%USERPROFILE%\.codex\config.toml`
 
 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.
 
 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.
 
@@ -180,6 +188,7 @@ When using the installed package, `nado-mcp login` saves auth to the user's OS c
 Basic tool discovery:
 
 ```bash
+nado-mcp doctor
 nado-mcp probe list
 ```
 
@@ -245,9 +254,13 @@ npm run mcp:nado:probe -- save-nado-ai "serendipity"
 Install/register/login flow:
 
 ```bash
-nado-mcp connect codex
-nado-mcp connect claude
-nado-mcp connect opencode
+nado-mcp connect
+```
+
+Force all supported local config writers:
+
+```bash
+nado-mcp connect all
 ```
 
 Generic MCP fallback:
@@ -256,3 +269,10 @@ Generic MCP fallback:
 nado-mcp config
 nado-mcp login
 ```
+
+Diagnostics:
+
+```bash
+nado-mcp doctor
+nado-mcp probe list
+```

package/dist/nado-language-server.mjs

@@ -30,6 +30,40 @@ 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 saveFlashcardInputSchema = {
+  type: 'object',
+  required: ['original', 'definition'],
+  properties: {
+    original: {
+      type: 'string',
+      minLength: 1,
+      description: 'English word, phrase, or sentence to save. Example: for "hello 암기할래", use "hello".',
+    },
+    type: { type: 'string', enum: ['word', 'phrase', 'sentence_structure'], default: 'phrase' },
+    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.' },
+    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,
+};
+
 const tools = [
   {
     name: 'nado_whoami',
@@ -42,40 +76,17 @@ const tools = [
   },
   {
     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,
-    },
+    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.',
+    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.',
+    inputSchema: saveFlashcardInputSchema,
   },
   {
     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.',
+    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.',
     inputSchema: {
       type: 'object',
       required: ['original'],
@@ -94,7 +105,7 @@ const tools = [
   },
   {
     name: 'nado_list_study_items',
-    description: 'Load saved Nado Language vocabulary and sentence cards for practice.',
+    description: 'Load saved Nado Language vocabulary and sentence cards. Use when the user asks what is saved, wants to inspect the memorization list, or asks to review existing Nado study items before practice.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -107,7 +118,7 @@ const tools = [
   },
   {
     name: 'nado_generate_practice',
-    description: 'Generate English practice content using only the authenticated user saved Nado Language study cards.',
+    description: 'Generate English practice content using only the authenticated user saved Nado Language study cards. Use when the user wants to study/review already saved items: "외울래", "암기 연습", "퀴즈 내줘", "쓰기연습", "영작하기", "복습할래", "practice my saved words". If the user supplies a new English item to save, use nado_save_flashcard instead.',
     inputSchema: {
       type: 'object',
       required: ['mode'],
@@ -883,8 +894,8 @@ function stableHash(value) {
 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_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}`);

package/dist/nado-mcp-auth.mjs

@@ -199,7 +199,7 @@ async function login(options) {
 
   let timeoutId;
   const timeout = new Promise((_, reject) => {
-    timeoutId = setTimeout(() => reject(new Error('Timed out waiting for browser login.')), options.timeoutMs);
+    timeoutId = setTimeout(() => reject(loginTimeoutError(options)), options.timeoutMs);
   });
 
   try {
@@ -212,6 +212,15 @@ async function login(options) {
   }
 }
 
+function loginTimeoutError(options) {
+  return new Error([
+    'Timed out waiting for browser login.',
+    `Rerun \`nado-mcp login --provider ${options.provider} --timeout-ms 900000\` and keep the terminal open until the browser says login completed.`,
+    'If the browser did not open, copy the printed URL into the same desktop browser where you can sign in.',
+    'If you already signed in but it still timed out, check that the browser can reach the printed 127.0.0.1 local callback URL and that Supabase Auth allows the relay URL.',
+  ].join(' '));
+}
+
 function buildRedirectTo(options, localCallbackUrl) {
   if (options.redirectMode === 'local') return localCallbackUrl;
 

package/dist/nado-mcp-cli.mjs

@@ -45,15 +45,19 @@ try {
     await runNode(probePath, args, { stdio: 'inherit' });
   } else if (command === 'setup') {
     const parsed = splitClientAndSetupOptions(args);
-    await setup(parsed.client, parsed.setupOptions);
+    const didRegister = await setup(parsed.client, parsed.setupOptions);
+    if (didRegister) printToolProbeSummary();
   } else if (command === 'connect' || command === 'install') {
     const parsed = splitClientAndSetupOptions(args);
     const didRegister = await setup(parsed.client, parsed.setupOptions, { loginAfter: true });
-    if (didRegister) await runAuth(['login', ...parsed.rest]);
+    if (didRegister) {
+      printToolProbeSummary();
+      await runAuth(['login', ...parsed.rest]);
+    }
   } else if (command === 'config') {
     printConfig(args[0] || 'all');
   } else if (command === 'doctor') {
-    doctor();
+    await doctor();
   } else {
     throw new Error(`Unknown command: ${command}`);
   }
@@ -228,15 +232,182 @@ function setupMcpServersJson(configPath, flow = {}) {
   printLoginNext(flow);
 }
 
-function doctor() {
+async function doctor() {
+  const auth = authStatus(configuredAuthEnvFile());
+  const codex = codexRegistrationStatus();
+  const claude = jsonRegistrationStatus(claudeDesktopConfigPath(), ['mcpServers', serverName]);
+  const opencode = jsonRegistrationStatus(opencodeConfigPath(), ['mcp', serverName]);
+  const probe = probeTools();
+
   console.log('Nado MCP doctor');
   console.log(`Node: ${process.version}`);
   console.log(`Server: ${serverPath}${existsSync(serverPath) ? '' : ' (missing)'}`);
   console.log(`Auth CLI: ${authPath}${existsSync(authPath) ? '' : ' (missing)'}`);
-  console.log(`Auth file: ${defaultUserAuthEnvFile()}${existsSync(defaultUserAuthEnvFile()) ? ' (present)' : ' (missing)'}`);
-  console.log(`Codex Desktop config: ${codexDesktopConfigPath()}`);
-  console.log(`Claude Desktop config: ${claudeDesktopConfigPath()}`);
-  console.log(`OpenCode config: ${opencodeConfigPath()}`);
+  console.log(`Local MCP server check: ${probe.ok ? `ok (${probe.tools.join(', ')})` : `failed (${probe.error})`}`);
+  console.log(`Auth file: ${auth.filePath}${auth.fileExists ? ' (present)' : ' (missing)'}`);
+  console.log(`Auth access token: ${auth.accessToken ? `present${tokenExpiryText(auth.accessToken)}` : 'missing'}`);
+  console.log(`Auth refresh token: ${auth.refreshToken ? 'present' : 'missing'}`);
+  console.log(`Auth email/password fallback: ${auth.email ? `configured for ${auth.email}` : 'missing'}`);
+  console.log(`Codex Desktop config: ${registrationText(codex)}`);
+  console.log(`Claude Desktop config: ${registrationText(claude)}`);
+  console.log(`OpenCode config: ${registrationText(opencode)}`);
+  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.');
+}
+
+function printToolProbeSummary() {
+  const probe = probeTools();
+  if (probe.ok) {
+    console.log(`Local MCP server check: ok (${probe.tools.join(', ')})`);
+  } else {
+    console.log(`Local MCP server check failed: ${probe.error}`);
+  }
+}
+
+function probeTools() {
+  if (!existsSync(probePath)) return { ok: false, error: `probe script missing at ${probePath}` };
+
+  const result = spawnSync(process.execPath, [probePath, 'list'], {
+    encoding: 'utf8',
+    env: {
+      ...process.env,
+      NADO_MCP_SKIP_DOTENV: '1',
+    },
+  });
+
+  if (result.error) return { ok: false, error: result.error.message };
+  if (result.status !== 0) {
+    const message = (result.stderr || result.stdout || `probe exited with code ${result.status}`).trim();
+    return { ok: false, error: message };
+  }
+
+  try {
+    const parsed = JSON.parse(result.stdout);
+    const tools = (parsed.tools || []).map((tool) => tool.name).filter(Boolean);
+    if (tools.length === 0) return { ok: false, error: 'no tools returned by server' };
+    return { ok: true, tools };
+  } catch (error) {
+    return { ok: false, error: `could not parse probe output: ${error instanceof Error ? error.message : String(error)}` };
+  }
+}
+
+function configuredAuthEnvFile() {
+  return process.env.NADO_MCP_AUTH_ENV_FILE ? expandHome(process.env.NADO_MCP_AUTH_ENV_FILE) : defaultUserAuthEnvFile();
+}
+
+function authStatus(filePath) {
+  const values = readEnvFile(filePath);
+  const accessToken = process.env.NADO_MCP_ACCESS_TOKEN || values.NADO_MCP_ACCESS_TOKEN || process.env.NADO_ACCESS_TOKEN || '';
+  const refreshToken = process.env.NADO_MCP_REFRESH_TOKEN || values.NADO_MCP_REFRESH_TOKEN || process.env.NADO_REFRESH_TOKEN || '';
+  const email = process.env.NADO_MCP_EMAIL || values.NADO_MCP_EMAIL || '';
+
+  return {
+    filePath,
+    fileExists: existsSync(filePath),
+    accessToken,
+    refreshToken,
+    email,
+  };
+}
+
+function codexRegistrationStatus() {
+  const configPath = codexDesktopConfigPath();
+  if (!existsSync(configPath)) return { path: configPath, fileExists: false, registered: false };
+
+  try {
+    const text = readFileSync(configPath, 'utf8');
+    const sectionPattern = new RegExp(`^\\s*\\[mcp_servers\\.${escapeRegExp(serverName)}]\\s*$`, 'm');
+    return { path: configPath, fileExists: true, registered: sectionPattern.test(text) };
+  } catch (error) {
+    return { path: configPath, fileExists: true, registered: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+function jsonRegistrationStatus(configPath, keyPath) {
+  if (!existsSync(configPath)) return { path: configPath, fileExists: false, registered: false };
+
+  try {
+    const config = readJsonConfig(configPath);
+    return {
+      path: configPath,
+      fileExists: true,
+      registered: getPathValue(config, keyPath) !== undefined,
+    };
+  } catch (error) {
+    return { path: configPath, fileExists: true, registered: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+function registrationText(status) {
+  if (status.error) return `${status.path} (error: ${status.error})`;
+  if (!status.fileExists) return `${status.path} (missing)`;
+  return `${status.path} (${status.registered ? 'registered' : 'not registered'})`;
+}
+
+function getPathValue(value, keys) {
+  let current = value;
+  for (const key of keys) {
+    if (!current || typeof current !== 'object' || !(key in current)) return undefined;
+    current = current[key];
+  }
+  return current;
+}
+
+function readEnvFile(filePath) {
+  if (!existsSync(filePath)) return {};
+  const values = {};
+  for (const line of readFileSync(filePath, 'utf8').split(/\r?\n/)) {
+    const parsed = parseEnvLine(line);
+    if (parsed) values[parsed.key] = parsed.value;
+  }
+  return values;
+}
+
+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 tokenExpiryText(token) {
+  const expiresAt = jwtExpiresAtMs(token);
+  if (!expiresAt) return '';
+  return `, expires ${new Date(expiresAt).toISOString()}`;
+}
+
+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 escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
 function firstExisting(candidates) {

package/package.json

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