@nado-language/mcp 0.1.2 → 0.1.4

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:
@@ -47,6 +54,8 @@ NADO_MCP_REFRESH_TOKEN='supabase-user-refresh-token'
 
 By default this uses the existing Azure Static Web Apps production site as a static OAuth relay. It does not require a new Azure Function, App Service, database, or paid runtime. The local helper still receives the final callback on `127.0.0.1`; Azure only serves the static relay page.
 
+The installed CLI opens the Nado relay page first. The relay stores the local callback in browser session storage, then sends Supabase a fixed redirect URL. This avoids Supabase rejecting a dynamic `redirect_to` URL with `local_callback` query parameters and falling back to the normal Nado web site.
+
 The MCP server refreshes expired access tokens with `NADO_MCP_REFRESH_TOKEN` and updates the auth file when Supabase rotates the refresh token.
 
 Supported local browser providers are `google`, `kakao`, and `apple`. Naver login is not available in the local MCP flow yet because the current Naver Edge Function uses fixed web/native redirect URLs.
@@ -57,6 +66,8 @@ Supabase Auth must allow the Azure relay redirect URL:
 https://language.nado.ai.kr/auth/mcp-callback
 ```
 
+Register the exact URL above. Do not include `local_callback`, `provider`, or other query parameters in the Supabase allow list.
+
 For direct local callback mode, run with `--redirect-mode local` and allow:
 
 ```text
@@ -139,6 +150,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 +192,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 +258,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 +273,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

@@ -183,23 +183,22 @@ async function login(options) {
 
   const localCallbackUrl = new URL(`http://127.0.0.1:${address.port}/callback`);
   localCallbackUrl.searchParams.set('state', state);
-  const redirectTo = buildRedirectTo(options, localCallbackUrl.toString());
-  const authUrl = buildAuthorizeUrl({
-    supabaseUrl: options.supabaseUrl,
+  const browserUrl = buildBrowserLoginUrl({
+    options,
     provider,
-    redirectTo,
+    localCallbackUrl: localCallbackUrl.toString(),
     codeChallenge,
   });
 
   console.log(`Opening browser for Nado MCP login (${provider}).`);
   console.log(`Local callback: ${localCallbackUrl.toString()}`);
   if (options.redirectMode === 'azure') console.log(`Azure relay: ${options.relayUrl}`);
-  if (!options.noOpen) openBrowser(authUrl);
-  console.log(`If the browser did not open, visit:\n${authUrl}`);
+  if (!options.noOpen) openBrowser(browserUrl);
+  console.log(`If the browser did not open, visit:\n${browserUrl}`);
 
   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,14 +211,44 @@ async function login(options) {
   }
 }
 
-function buildRedirectTo(options, localCallbackUrl) {
-  if (options.redirectMode === 'local') return localCallbackUrl;
+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 Google login succeeds but the browser lands on the normal Nado site, upgrade @nado-language/mcp and confirm Supabase Auth allows the exact relay URL without query parameters.',
+    'If it still times out after the relay page says it is returning to the local helper, check that the browser can reach the printed 127.0.0.1 local callback URL.',
+  ].join(' '));
+}
+
+function buildBrowserLoginUrl({ options, provider, localCallbackUrl, codeChallenge }) {
+  if (options.redirectMode === 'local') {
+    return buildAuthorizeUrl({
+      supabaseUrl: options.supabaseUrl,
+      provider,
+      redirectTo: localCallbackUrl,
+      codeChallenge,
+    });
+  }
+
+  return buildRelayStartUrl({
+    relayUrl: options.relayUrl,
+    localCallbackUrl,
+    provider,
+    supabaseUrl: options.supabaseUrl,
+    codeChallenge,
+  });
+}
 
-  const relayUrl = new URL(options.relayUrl);
+function buildRelayStartUrl({ relayUrl: value, localCallbackUrl, provider, supabaseUrl, codeChallenge }) {
+  const relayUrl = new URL(value);
   if (relayUrl.protocol !== 'https:') {
     throw new Error('--relay-url must be an HTTPS URL when --redirect-mode azure is used.');
   }
   relayUrl.searchParams.set('local_callback', localCallbackUrl);
+  relayUrl.searchParams.set('provider', provider);
+  relayUrl.searchParams.set('supabase_url', supabaseUrl);
+  relayUrl.searchParams.set('code_challenge', codeChallenge);
   return relayUrl.toString();
 }
 
@@ -489,6 +518,10 @@ Default mode uses the existing Azure Static Web Apps site as a zero-new-resource
 OAuth relay. Supabase Auth must allow this redirect URL:
   ${DEFAULT_RELAY_URL}
 
+The relay starts login with local state in browser sessionStorage, then sends
+Supabase the fixed redirect URL above. Do not add local_callback query strings
+to the Supabase allow list.
+
 The optional local mode requires Supabase Auth to allow:
   http://127.0.0.1:*/callback
 `);

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.4",
   "description": "Nado Language MCP server for saving AI-generated English flashcards and practicing saved materials.",
   "type": "module",
   "private": false,