@nado-language/mcp 0.1.0

package/README.md

@@ -0,0 +1,225 @@
+# Nado Language MCP
+
+This stdio MCP server lets AI chat clients save and practice Nado Language study items.
+
+## Tools
+
+- `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_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.
+
+## Authentication
+
+Installed package browser login:
+
+```bash
+nado-mcp login
+```
+
+Source checkout alias:
+
+```bash
+npm run mcp:nado:auth -- --provider google
+```
+
+This opens the provider login page, relays the Supabase OAuth callback through the existing Azure Static Web Apps site, receives the final callback on `127.0.0.1`, and writes ignored local tokens to the user's OS config directory for package installs or `.env.mcp.local` in a repo checkout:
+
+```bash
+NADO_MCP_ACCESS_TOKEN='supabase-user-access-token'
+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 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.
+
+Supabase Auth must allow the Azure relay redirect URL:
+
+```text
+https://language.nado.ai.kr/auth/mcp-callback
+```
+
+For direct local callback mode, run with `--redirect-mode local` and allow:
+
+```text
+http://127.0.0.1:*/callback
+```
+
+You can inspect or clear local MCP auth with:
+
+```bash
+nado-mcp status
+nado-mcp logout
+```
+
+Source checkout aliases:
+
+```bash
+npm run mcp:nado:auth -- status
+npm run mcp:nado:auth -- logout
+```
+
+Manual access-token option:
+
+```bash
+export NADO_MCP_ACCESS_TOKEN='supabase-user-access-token'
+export NADO_MCP_REFRESH_TOKEN='supabase-user-refresh-token'
+```
+
+Password fallback:
+
+```bash
+export NADO_MCP_EMAIL='user@example.com'
+export NADO_MCP_PASSWORD='password'
+```
+
+For local development, the server also loads ignored local env files from the current working directory or repo root:
+
+- `.env.mcp.local`
+- `.env.local`
+
+Example `.env.mcp.local`:
+
+```bash
+NADO_MCP_ACCESS_TOKEN=supabase-user-access-token
+NADO_MCP_REFRESH_TOKEN=supabase-user-refresh-token
+```
+
+Optional environment:
+
+```bash
+export NADO_MCP_SUPABASE_URL='https://ptbwzhxifxdnfmqsiugi.supabase.co'
+export NADO_MCP_SUPABASE_ANON_KEY='...'
+export NADO_MCP_AUTH_RELAY_URL='https://language.nado.ai.kr/auth/mcp-callback'
+```
+
+## Client Registration
+
+Installed package, one-command setup plus browser login:
+
+```bash
+nado-mcp connect codex
+nado-mcp connect claude
+nado-mcp connect opencode
+```
+
+Setup without login:
+
+```bash
+nado-mcp setup codex
+nado-mcp setup claude
+nado-mcp setup opencode
+```
+
+For any other MCP-compatible client, print portable stdio config:
+
+```bash
+nado-mcp config
+```
+
+If the client uses a JSON file with a top-level `mcpServers` object:
+
+```bash
+nado-mcp setup mcp-json --file /path/to/mcp.json
+nado-mcp login
+```
+
+Unknown clients are handled as generic MCP clients. `nado-mcp setup <client-name>` prints the portable config instead of failing.
+
+Manual Codex registration from a source checkout:
+
+```bash
+codex mcp add nado-language -- node /Users/jin/Documents/nado/eng/mcp/nado-language-server.mjs
+```
+
+Then run Codex from a shell where the auth environment variables above are set.
+Alternatively, create `.env.mcp.local` in the repo root before Codex starts the MCP server.
+When using the installed package, `nado-mcp login` saves auth to the user's OS config directory and the server reads it automatically.
+
+## Verification
+
+Basic tool discovery:
+
+```bash
+nado-mcp probe list
+```
+
+Source checkout alias:
+
+```bash
+npm run mcp:nado:probe -- list
+```
+
+Authenticated account check:
+
+```bash
+nado-mcp probe whoami
+```
+
+Source checkout alias:
+
+```bash
+npm run mcp:nado:probe -- whoami
+```
+
+End-to-end admin verification. This saves a unique word, lists it back, and confirms generated practice cites only saved card IDs:
+
+```bash
+nado-mcp probe verify-admin "serendipity"
+```
+
+Source checkout alias:
+
+```bash
+npm run mcp:nado:probe -- verify-admin "serendipity"
+```
+
+The admin verification requires browser login, `NADO_MCP_ACCESS_TOKEN`, or `NADO_MCP_EMAIL` and `NADO_MCP_PASSWORD`, either in the current process, the package auth file, or `.env.mcp.local`.
+
+Save a user-AI generated card without Nado AI cost:
+
+```bash
+nado-mcp probe save "serendipity"
+```
+
+Source checkout alias:
+
+```bash
+npm run mcp:nado:probe -- save "serendipity"
+```
+
+Pro/Admin Nado AI quality path:
+
+```bash
+nado-mcp probe save-nado-ai "serendipity"
+```
+
+Source checkout alias:
+
+```bash
+npm run mcp:nado:probe -- save-nado-ai "serendipity"
+```
+
+
+## Package CLI
+
+Install/register/login flow:
+
+```bash
+nado-mcp connect codex
+nado-mcp connect claude
+nado-mcp connect opencode
+```
+
+Generic MCP fallback:
+
+```bash
+nado-mcp config
+nado-mcp login
+```