sp-rag 0.6.0 → 0.6.2

package/README.md

@@ -17,7 +17,7 @@ CLI để setup nhanh SP-RAG theo hướng dev-friendly:
 ## Trạng thái package
 
 - package npm public: `sp-rag`
-- version đang publish: `0.6.0`
+- version đang publish: `0.6.2`
 - binary public: `sp-rag`
 
 ## Cài từ source trong monorepo
@@ -36,22 +36,47 @@ node dist/index.js doctor
 npx sp-rag@latest install --client codex --mcp-token <grc_pat_...> --doctor
 npx sp-rag@latest install --client cursor --scope project --cwd D:/Webs/seo-booster --mcp-token <grc_pat_...>
 npx sp-rag@latest install --client vscode --scope project --cwd D:/Webs/seo-booster --mcp-token <grc_pat_...>
-npx sp-rag@latest token add --token <grc_pat_...> --client codex
+npx sp-rag@latest add --client claude-code --scope project --cwd D:/Webs/seo-booster
+npx sp-rag@latest explain --client vscode --scope project --cwd D:/Webs/seo-booster
+npx sp-rag@latest token add --token <grc_pat_...>
 npx sp-rag@latest token verify --token <grc_pat_...>
-npx sp-rag@latest mcp add antigravity --mcp-token <grc_pat_...>
-npx sp-rag@latest mcp add opencode --scope project --cwd D:/Webs/seo-booster --mcp-token <grc_pat_...>
-npx sp-rag@latest skill install --skill-client cursor --scope project --cwd D:/Webs/seo-booster
-npx sp-rag@latest skill install --skill-client vscode --scope project --cwd D:/Webs/seo-booster
+npx sp-rag@latest mcp add antigravity
+npx sp-rag@latest mcp add opencode --scope project --cwd D:/Webs/seo-booster
+npx sp-rag@latest skill install --client cursor --scope project --cwd D:/Webs/seo-booster
+npx sp-rag@latest skill install --client vscode --scope project --cwd D:/Webs/seo-booster
 ```
 
 Tương đương bằng `npm`:
 
 ```bash
 npm exec --yes sp-rag@latest install -- --client codex --mcp-token <grc_pat_...> --doctor
-npm exec --yes sp-rag@latest token add -- --token <grc_pat_...> --client codex
+npm exec --yes sp-rag@latest add -- --client claude-code --scope project --cwd D:/Webs/seo-booster
+npm exec --yes sp-rag@latest explain -- --client vscode --scope project --cwd D:/Webs/seo-booster
+npm exec --yes sp-rag@latest token add -- --token <grc_pat_...>
 npm exec --yes sp-rag@latest token verify -- --token <grc_pat_...>
 ```
 
+## Flow gọn cho dev
+
+Flow khuyên dùng sau khi đã có `grc_pat_*`:
+
+1. chạy `install` đúng một lần cho client đầu tiên, có kèm `--mcp-token`
+2. từ lần sau, dùng `add --client ...` để cài thêm MCP + skill cho client khác mà không phải nhập lại token
+3. khi chỉ muốn làm một nửa, dùng `mcp add` hoặc `skill install`
+4. khi đổi token, chỉ cần `token add`
+5. khi muốn kiểm tra máy đang được cấu hình ra sao, dùng `explain`
+
+Ví dụ:
+
+```bash
+sp-rag install --client vscode --scope project --cwd D:/Webs/seo-booster --mcp-token <grc_pat_...> --doctor
+sp-rag add --client cursor --scope project --cwd D:/Webs/seo-booster
+sp-rag mcp add antigravity
+sp-rag skill install --client vscode --scope project --cwd D:/Webs/seo-booster
+sp-rag token add --token <grc_pat_moi>
+sp-rag explain --client vscode --scope project --cwd D:/Webs/seo-booster
+```
+
 ## Lấy token ở đâu
 
 `sp-rag` public bây giờ dùng token gắn với tài khoản thật trên server.
@@ -69,6 +94,7 @@ Luồng chuẩn:
 - quyền nhìn thấy tool/resource trên MCP bám theo role của account đó
 - `viewer`, `operator`, `approver`, `admin` sẽ thấy inventory khác nhau
 - `MCP_SERVER_ACCESS_TOKENS_JSON` chỉ còn là fallback legacy/break-glass, không còn là luồng chính cho dev
+- khi client đã có sẵn một alias trỏ cùng MCP endpoint, CLI sẽ ưu tiên cập nhật alias đó thay vì tạo alias mới song song
 
 Tự tạo PAT bằng API hiện có:
 
@@ -100,6 +126,7 @@ Ví dụ dev dùng token trực tiếp:
 ```bash
 npx sp-rag@latest install --client cursor --scope project --cwd D:/Webs/seo-booster --mcp-token <grc_pat_...>
 npx sp-rag@latest token verify --token <grc_pat_...>
+npx sp-rag@latest explain --client cursor --scope project --cwd D:/Webs/seo-booster
 ```
 
 Hoặc dùng biến môi trường:
@@ -163,7 +190,9 @@ Ghi chú:
 
 ```bash
 sp-rag install --client codex --mcp-token <grc_pat_...> --doctor
-sp-rag token add --token <grc_pat_...> --client codex
+sp-rag add --client cursor --scope project --cwd D:/Webs/seo-booster
+sp-rag explain --client codex
+sp-rag token add --token <grc_pat_...>
 sp-rag token verify --token <grc_pat_...>
 sp-rag config show
 sp-rag codegraph status
@@ -171,12 +200,12 @@ sp-rag codegraph watch --interval-ms 2000
 sp-rag codegraph runs --limit 5
 sp-rag codegraph metrics
 sp-rag codegraph recover --reason "Ops dọn stale run sau crash"
-sp-rag mcp add antigravity --mcp-token <grc_pat_...>
-sp-rag mcp add vscode --scope project --cwd D:/Webs/seo-booster --mcp-token <grc_pat_...>
-sp-rag mcp add opencode --scope project --cwd D:/Webs/seo-booster --mcp-token <grc_pat_...>
-sp-rag skill install
-sp-rag skill install --skill-client cursor --scope project --cwd D:/Webs/seo-booster
-sp-rag skill install --skill-client vscode --scope project --cwd D:/Webs/seo-booster
+sp-rag mcp add antigravity
+sp-rag mcp add vscode --scope project --cwd D:/Webs/seo-booster
+sp-rag mcp add opencode --scope project --cwd D:/Webs/seo-booster
+sp-rag skill install --client codex
+sp-rag skill install --client cursor --scope project --cwd D:/Webs/seo-booster
+sp-rag skill install --client vscode --scope project --cwd D:/Webs/seo-booster
 sp-rag eval run --file ./examples/eval-suite.sample.json
 ```
 
@@ -184,7 +213,9 @@ sp-rag eval run --file ./examples/eval-suite.sample.json
 
 ```bash
 sp-rag install --client codex --mcp-token <grc_pat_...> --doctor
-sp-rag token add --token <grc_pat_...> --client codex
+sp-rag add --client cursor --scope project --cwd D:/Webs/seo-booster
+sp-rag explain --client codex
+sp-rag token add --token <grc_pat_...>
 sp-rag token verify --token <grc_pat_...>
 sp-rag config show
 sp-rag doctor
@@ -195,13 +226,13 @@ sp-rag codegraph metrics
 sp-rag codegraph recover --reason "Ops dọn stale run sau crash"
 sp-rag codegraph sync --branch master --commit-sha <sha> --webhook-token <token webhook codegraph> --gitlab-job-token <ci-job-token>
 sp-rag docs get public --format md
-sp-rag mcp add codex --mcp-token <grc_pat_...>
-sp-rag mcp add antigravity --mcp-token <grc_pat_...>
-sp-rag mcp add vscode --scope project --cwd D:/Webs/seo-booster --mcp-token <grc_pat_...>
-sp-rag mcp add opencode --scope project --cwd D:/Webs/seo-booster --mcp-token <grc_pat_...>
-sp-rag skill install
-sp-rag skill install --skill-client cursor --scope project --cwd D:/Webs/seo-booster
-sp-rag skill install --skill-client vscode --scope project --cwd D:/Webs/seo-booster
+sp-rag mcp add codex
+sp-rag mcp add antigravity
+sp-rag mcp add vscode --scope project --cwd D:/Webs/seo-booster
+sp-rag mcp add opencode --scope project --cwd D:/Webs/seo-booster
+sp-rag skill install --client codex
+sp-rag skill install --client cursor --scope project --cwd D:/Webs/seo-booster
+sp-rag skill install --client vscode --scope project --cwd D:/Webs/seo-booster
 sp-rag eval run --file ./examples/eval-suite.sample.json
 sp-rag update setup --client codex
 ```

package/dist/cli.js

@@ -1,9 +1,9 @@
 import { readFile } from 'node:fs/promises';
 import { loadCliConfig, saveCliConfig, } from './lib/config-store.js';
 import { runEvaluationSuite } from './lib/eval.js';
-import { defaultBaseUrl, defaultMcpServerAlias, defaultMcpUrl, installMcpConfig, } from './lib/mcp-config.js';
+import { defaultBaseUrl, defaultMcpServerAlias, defaultMcpUrl, installMcpConfig, resolveMcpConfigPath, } from './lib/mcp-config.js';
 import { fetchJson, fetchText, runDoctor } from './lib/http.js';
-import { installSkill, } from './lib/skill.js';
+import { installSkill, resolveSkillInstallTarget, } from './lib/skill.js';
 function parseArgv(argv) {
     const positionals = [];
     const options = {};
@@ -111,8 +111,11 @@ async function loadRuntimeDefaults(parsed) {
     const docsUrl = optionString(parsed, 'docs-url') ??
         config?.docsUrl ??
         `${baseUrl.replace(/\/+$/, '')}/codegraph/docs/public?format=md`;
-    const defaultClient = supportedClient(optionString(parsed, 'client') ?? config?.defaultClient);
+    const explicitClient = supportedClient(optionString(parsed, 'client'));
+    const defaultClient = explicitClient ?? supportedClient(config?.defaultClient);
     const defaultScope = supportedScope(optionString(parsed, 'scope') ?? config?.defaultScope);
+    const explicitSkillClient = supportedSkillClient(optionString(parsed, 'skill-client'));
+    const derivedSkillClient = defaultSkillClientForMcpClient(defaultClient);
     return {
         config,
         homeDir,
@@ -127,21 +130,58 @@ async function loadRuntimeDefaults(parsed) {
             optionString(parsed, 'token') ??
             process.env['SP_RAG_MCP_TOKEN']?.trim() ??
             config?.mcpToken,
-        skillClient: supportedSkillClient(optionString(parsed, 'skill-client')) ??
+        skillClient: explicitSkillClient ??
+            (explicitClient ? defaultSkillClientForMcpClient(explicitClient) : undefined) ??
             config?.skillClient ??
-            defaultSkillClientForMcpClient(defaultClient),
+            derivedSkillClient,
         skillTargetDir: optionString(parsed, 'target-dir') ?? config?.skillTargetDir,
     };
 }
+function resolveSelectedClient(parsed, defaults, explicitClient) {
+    return supportedClient(explicitClient ??
+        optionString(parsed, 'client') ??
+        parsed.positionals[2] ??
+        defaults.defaultClient);
+}
+function resolveSelectedSkillClient(parsed, defaults, client) {
+    return (supportedSkillClient(optionString(parsed, 'client')) ??
+        supportedSkillClient(optionString(parsed, 'skill-client')) ??
+        (client ? defaultSkillClientForMcpClient(client) : undefined) ??
+        defaults.skillClient);
+}
+function deriveDefaultsForClient(parsed, defaults, client) {
+    const nextClient = client ?? defaults.defaultClient;
+    const nextScope = supportedScope(optionString(parsed, 'scope')) ?? defaults.defaultScope;
+    const nextSkillClient = resolveSelectedSkillClient(parsed, defaults, nextClient);
+    return {
+        ...defaults,
+        defaultClient: nextClient,
+        defaultScope: nextScope,
+        skillClient: nextSkillClient,
+    };
+}
+function resolveAuthForMcp(parsed, defaults) {
+    const authToken = optionString(parsed, 'mcp-token') ?? defaults.mcpToken;
+    const authEnvVar = optionString(parsed, 'auth-env-var') ?? defaults.authEnvVar;
+    if (!authToken?.trim() && !authEnvVar?.trim()) {
+        throw new Error('Chưa có token MCP trong config. Hãy chạy sp-rag install --client <client> --mcp-token <token> hoặc sp-rag token add --token <token>.');
+    }
+    return {
+        authToken: authToken?.trim(),
+        authEnvVar: authEnvVar?.trim(),
+    };
+}
 function helpText() {
     return `sp-rag - CLI cho setup, MCP, codegraph, eval và skill của SP-RAG
 
 Lệnh chính:
-  sp-rag install [--base-url URL] [--mcp-url URL] [--client codex|cursor|claude-code|antigravity|vscode|opencode] [--skill-client codex|cursor|claude-code|antigravity|vscode|opencode] [--scope global|project] [--mcp-token TOKEN] [--auth-env-var ENV_VAR] [--target-dir PATH]
+  sp-rag install --client codex|cursor|claude-code|antigravity|vscode|opencode [--base-url URL] [--mcp-url URL] [--scope global|project] [--mcp-token TOKEN] [--auth-env-var ENV_VAR] [--target-dir PATH] [--doctor]
+  sp-rag add --client codex|cursor|claude-code|antigravity|vscode|opencode [--scope global|project] [--cwd PATH] [--target-dir PATH]
   sp-rag init [--base-url URL] [--mcp-url URL] [--client codex|cursor|claude-code|antigravity|vscode|opencode] [--skill-client codex|cursor|claude-code|antigravity|vscode|opencode] [--scope global|project] [--auth-env-var ENV_VAR] [--target-dir PATH]
-  sp-rag token add --token TOKEN [--client codex|cursor|claude-code|antigravity|vscode|opencode] [--scope global|project] [--cwd PATH]
+  sp-rag token add --token TOKEN
   sp-rag token verify [--token TOKEN] [--base-url URL]
   sp-rag config show
+  sp-rag explain [--client codex|cursor|claude-code|antigravity|vscode|opencode] [--scope global|project] [--cwd PATH]
   sp-rag doctor [--base-url URL]
   sp-rag codegraph status [--base-url URL]
   sp-rag codegraph watch [--base-url URL] [--interval-ms N] [--max-polls N]
@@ -151,7 +191,7 @@ Lệnh chính:
   sp-rag codegraph sync [--base-url URL] [--branch BRANCH] [--commit-sha SHA] [--force] [--webhook-token TOKEN] [--gitlab-job-token TOKEN]
   sp-rag docs get <public|function|dev> [--base-url URL] [--format md|json|html]
   sp-rag mcp add <codex|cursor|claude-code|antigravity|vscode|opencode> [--url URL] [--scope global|project] [--auth-env-var ENV_VAR] [--mcp-token TOKEN]
-  sp-rag skill install [--skill-client codex|cursor|claude-code|antigravity|vscode|opencode] [--scope global|project] [--cwd PATH] [--target-dir PATH] [--mcp-url URL] [--docs-url URL]
+  sp-rag skill install [--client codex|cursor|claude-code|antigravity|vscode|opencode] [--skill-client codex|cursor|claude-code|antigravity|vscode|opencode] [--scope global|project] [--cwd PATH] [--target-dir PATH] [--mcp-url URL] [--docs-url URL]
   sp-rag eval run --file eval-suite.json [--base-url URL]
   sp-rag update setup [--client codex|cursor|claude-code|antigravity|vscode|opencode] [--skill-client codex|cursor|claude-code|antigravity|vscode|opencode] [--scope global|project] [--url URL] [--auth-env-var ENV_VAR] [--target-dir PATH]
 `;
@@ -296,7 +336,7 @@ async function runDocsGet(parsed) {
     process.stdout.write(`${result}${result.endsWith('\n') ? '' : '\n'}`);
 }
 async function runMcpAdd(parsed, defaults, explicitClient) {
-    const client = supportedClient(explicitClient ?? parsed.positionals[2] ?? defaults.defaultClient);
+    const client = resolveSelectedClient(parsed, defaults, explicitClient);
     if (!client) {
         throw new Error('Thiếu client. Dùng codex, cursor, claude-code, antigravity, vscode hoặc opencode.');
     }
@@ -304,17 +344,15 @@ async function runMcpAdd(parsed, defaults, explicitClient) {
         client,
         url: optionString(parsed, 'url') ?? defaults.mcpUrl,
         scope: supportedScope(optionString(parsed, 'scope')) ?? defaults.defaultScope,
-        authEnvVar: optionString(parsed, 'auth-env-var') ?? defaults.authEnvVar,
-        authToken: optionString(parsed, 'mcp-token') ?? defaults.mcpToken,
+        authEnvVar: resolveAuthForMcp(parsed, defaults).authEnvVar,
+        authToken: resolveAuthForMcp(parsed, defaults).authToken,
         cwd: optionString(parsed, 'cwd'),
         serverAlias: optionString(parsed, 'server-alias') ?? defaults.serverAlias,
     });
     process.stdout.write(`Đã cập nhật cấu hình MCP cho ${result.client} tại ${result.path} (${result.scope}).\n`);
 }
-async function runSkillInstall(parsed, defaults) {
-    const client = supportedSkillClient(optionString(parsed, 'skill-client')) ??
-        defaults.skillClient ??
-        'codex';
+async function runSkillInstall(parsed, defaults, explicitClient) {
+    const client = resolveSelectedSkillClient(parsed, defaults, explicitClient) ?? 'codex';
     const result = await installSkill({
         client,
         cwd: optionString(parsed, 'cwd'),
@@ -326,26 +364,60 @@ async function runSkillInstall(parsed, defaults) {
     });
     process.stdout.write(`Đã cài skill cho ${result.client} tại ${result.path}\n`);
 }
+async function saveResolvedConfig(defaults) {
+    return saveCliConfig(buildCliConfig(defaults), defaults.homeDir);
+}
+async function runClientSetup(parsed, defaults, client) {
+    const nextDefaults = deriveDefaultsForClient(parsed, defaults, client);
+    const configPath = await saveResolvedConfig(nextDefaults);
+    process.stdout.write(`Đã lưu config CLI tại ${configPath}\n`);
+    if (!optionFlag(parsed, 'skip-mcp')) {
+        await runMcpAdd(parsed, nextDefaults, client);
+    }
+    if (!optionFlag(parsed, 'skip-skill')) {
+        await runSkillInstall(parsed, nextDefaults, client);
+    }
+    if (optionFlag(parsed, 'doctor')) {
+        const results = await runDoctor({ baseUrl: nextDefaults.baseUrl });
+        for (const result of results) {
+            process.stdout.write(`${result.ok ? 'OK' : 'FAIL'}  ${result.name}  ${result.status}  ${result.url}\n`);
+        }
+    }
+}
 async function runInit(parsed) {
     const defaults = await loadRuntimeDefaults(parsed);
-    const config = buildCliConfig(defaults);
-    const configPath = await saveCliConfig(config, defaults.homeDir);
+    const client = resolveSelectedClient(parsed, defaults);
+    const nextDefaults = deriveDefaultsForClient(parsed, defaults, client);
+    const configPath = await saveResolvedConfig(nextDefaults);
     process.stdout.write(`Đã lưu config CLI tại ${configPath}\n`);
-    if (!optionFlag(parsed, 'skip-mcp') && defaults.defaultClient) {
-        await runMcpAdd(parsed, defaults, defaults.defaultClient);
+    if (!optionFlag(parsed, 'skip-mcp') && client) {
+        await runMcpAdd(parsed, nextDefaults, client);
     }
-    if (!optionFlag(parsed, 'skip-skill') && defaults.skillClient) {
-        await runSkillInstall(parsed, defaults);
+    if (!optionFlag(parsed, 'skip-skill') && nextDefaults.skillClient) {
+        await runSkillInstall(parsed, nextDefaults, client);
     }
     if (optionFlag(parsed, 'doctor')) {
-        const results = await runDoctor({ baseUrl: defaults.baseUrl });
+        const results = await runDoctor({ baseUrl: nextDefaults.baseUrl });
         for (const result of results) {
             process.stdout.write(`${result.ok ? 'OK' : 'FAIL'}  ${result.name}  ${result.status}  ${result.url}\n`);
         }
     }
 }
 async function runInstall(parsed) {
-    await runInit(parsed);
+    const defaults = await loadRuntimeDefaults(parsed);
+    const client = resolveSelectedClient(parsed, defaults);
+    if (!client) {
+        throw new Error('Thiếu client. Dùng sp-rag install --client <client> --mcp-token <token>.');
+    }
+    await runClientSetup(parsed, defaults, client);
+}
+async function runAdd(parsed) {
+    const defaults = await loadRuntimeDefaults(parsed);
+    const client = resolveSelectedClient(parsed, defaults);
+    if (!client) {
+        throw new Error('Thiếu client. Dùng sp-rag add --client <client>.');
+    }
+    await runClientSetup(parsed, defaults, client);
 }
 async function runTokenAdd(parsed) {
     const defaults = await loadRuntimeDefaults(parsed);
@@ -357,24 +429,9 @@ async function runTokenAdd(parsed) {
         ...defaults,
         mcpToken: token.trim(),
     };
-    const configPath = await saveCliConfig(buildCliConfig(nextDefaults), defaults.homeDir);
+    const configPath = await saveResolvedConfig(nextDefaults);
     process.stdout.write(`Đã lưu token MCP tại ${configPath}\n`);
-    if (optionFlag(parsed, 'skip-mcp-update')) {
-        return;
-    }
-    const client = supportedClient(optionString(parsed, 'client') ?? defaults.defaultClient);
-    if (!client) {
-        process.stdout.write('Chưa có client mặc định để cập nhật MCP config. Dùng thêm --client nếu muốn ghi ngay.\n');
-        return;
-    }
-    await runMcpAdd({
-        ...parsed,
-        positionals: ['mcp', 'add', client],
-        options: {
-            ...parsed.options,
-            'mcp-token': token.trim(),
-        },
-    }, nextDefaults, client);
+    return;
 }
 async function runTokenVerify(parsed) {
     const defaults = await loadRuntimeDefaults(parsed);
@@ -395,6 +452,73 @@ async function runConfigShow(parsed) {
     const config = await loadCliConfig(optionString(parsed, 'home-dir'));
     process.stdout.write(`${JSON.stringify(config ?? {}, null, 2)}\n`);
 }
+async function runExplain(parsed) {
+    const defaults = await loadRuntimeDefaults(parsed);
+    const client = resolveSelectedClient(parsed, defaults);
+    const scope = supportedScope(optionString(parsed, 'scope')) ?? defaults.defaultScope;
+    const tokenStatus = defaults.mcpToken?.trim()
+        ? 'đã lưu'
+        : defaults.authEnvVar?.trim()
+            ? `dùng biến môi trường ${defaults.authEnvVar}`
+            : 'chưa có';
+    const lines = [];
+    lines.push('## Cấu hình hiện tại');
+    lines.push(`- Base URL: ${defaults.baseUrl}`);
+    lines.push(`- MCP URL: ${defaults.mcpUrl}`);
+    lines.push(`- Client mặc định: ${defaults.defaultClient ?? 'chưa có'}`);
+    lines.push(`- Scope mặc định: ${defaults.defaultScope ?? 'chưa có'}`);
+    lines.push(`- Token MCP đang ở trạng thái: ${tokenStatus}`);
+    if (client) {
+        try {
+            const mcpTarget = resolveMcpConfigPath({
+                client,
+                url: defaults.mcpUrl,
+                scope,
+                cwd: optionString(parsed, 'cwd'),
+            });
+            lines.push(`- File MCP cho ${client}: ${mcpTarget.path}`);
+        }
+        catch (error) {
+            lines.push(`- File MCP cho ${client}: không xác định được (${error instanceof Error ? error.message : String(error)})`);
+        }
+        try {
+            const skillClient = resolveSelectedSkillClient(parsed, defaults, client) ??
+                defaultSkillClientForMcpClient(client);
+            if (skillClient) {
+                const skillTarget = resolveSkillInstallTarget({
+                    client: skillClient,
+                    scope,
+                    cwd: optionString(parsed, 'cwd'),
+                    targetDir: optionString(parsed, 'target-dir') ?? defaults.skillTargetDir,
+                    serverAlias: defaults.serverAlias,
+                    mcpUrl: defaults.mcpUrl,
+                    docsUrl: defaults.docsUrl,
+                });
+                lines.push(`- File skill cho ${client}: ${skillTarget.path}`);
+            }
+        }
+        catch (error) {
+            lines.push(`- File skill cho ${client}: không xác định được (${error instanceof Error ? error.message : String(error)})`);
+        }
+    }
+    lines.push('');
+    lines.push('## Cách dùng chuẩn');
+    if (!defaults.mcpToken?.trim() && !defaults.authEnvVar?.trim()) {
+        lines.push('- Máy này chưa có token MCP. Hãy chạy:');
+        lines.push(`  sp-rag install --client ${client ?? 'vscode'} --mcp-token <token>`);
+    }
+    else {
+        const chosenClient = client ?? defaults.defaultClient ?? 'vscode';
+        const chosenSkillClient = resolveSelectedSkillClient(parsed, defaults, client) ?? chosenClient;
+        lines.push('- Nếu muốn cài đầy đủ MCP + skill cho client mới, hãy chạy:');
+        lines.push(`  sp-rag add --client ${chosenClient}`);
+        lines.push('- Nếu chỉ muốn cập nhật MCP, hãy chạy:');
+        lines.push(`  sp-rag mcp add ${chosenClient}`);
+        lines.push('- Nếu chỉ muốn cài lại skill, hãy chạy:');
+        lines.push(`  sp-rag skill install --client ${chosenSkillClient}`);
+    }
+    process.stdout.write(`${lines.join('\n')}\n`);
+}
 async function runEval(parsed) {
     const filePath = optionString(parsed, 'file');
     if (!filePath) {
@@ -412,15 +536,15 @@ async function runEval(parsed) {
 }
 async function runUpdateSetup(parsed) {
     const defaults = await loadRuntimeDefaults(parsed);
-    const client = optionString(parsed, 'client') ?? defaults.defaultClient;
+    const client = resolveSelectedClient(parsed, defaults);
     if (client) {
         await runMcpAdd({
             ...parsed,
             positionals: ['mcp', 'add', client],
         }, defaults, client);
     }
-    if (!optionFlag(parsed, 'skip-skill') && defaults.skillClient) {
-        await runSkillInstall(parsed, defaults);
+    if (!optionFlag(parsed, 'skip-skill') && resolveSelectedSkillClient(parsed, defaults, client)) {
+        await runSkillInstall(parsed, defaults, client);
     }
 }
 export async function runCli(argv) {
@@ -435,6 +559,10 @@ export async function runCli(argv) {
             await runInstall(parsed);
             return 0;
         }
+        if (group === 'add') {
+            await runAdd(parsed);
+            return 0;
+        }
         if (group === 'init') {
             await runInit(parsed);
             return 0;
@@ -451,6 +579,10 @@ export async function runCli(argv) {
             await runConfigShow(parsed);
             return 0;
         }
+        if (group === 'explain') {
+            await runExplain(parsed);
+            return 0;
+        }
         if (group === 'doctor') {
             const defaults = await loadRuntimeDefaults(parsed);
             const results = await runDoctor({
@@ -511,7 +643,7 @@ export async function runCli(argv) {
             return 0;
         }
         if (group === 'version') {
-            process.stdout.write('sp-rag 0.6.0\n');
+            process.stdout.write('sp-rag 0.6.2\n');
             return 0;
         }
         process.stdout.write(helpText());

package/dist/lib/mcp-config.js

@@ -19,6 +19,13 @@ function withHeaders(target, headers) {
         headers,
     };
 }
+function normalizeEndpoint(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed ? trimmed.replace(/\/+$/, '') : null;
+}
 function bearerHeader(authToken, authEnvVar, envStyle = 'shell') {
     const trimmedToken = authToken?.trim();
     if (trimmedToken) {
@@ -55,6 +62,29 @@ function upsertObjectEntry(base, sectionKey, entryKey, entryValue) {
         [sectionKey]: section,
     };
 }
+function upsertObjectEntryPreservingAliasByEndpoint(base, sectionKey, entryKey, entryValue, endpointKey) {
+    const section = base[sectionKey] && typeof base[sectionKey] === 'object'
+        ? { ...base[sectionKey] }
+        : {};
+    const targetEndpoint = normalizeEndpoint(entryValue[endpointKey]);
+    const existingAlias = targetEndpoint
+        ? Object.entries(section).find(([alias, value]) => {
+            if (alias === entryKey || !value || typeof value !== 'object') {
+                return false;
+            }
+            return normalizeEndpoint(value[endpointKey]) === targetEndpoint;
+        })?.[0]
+        : undefined;
+    const aliasToWrite = existingAlias ?? entryKey;
+    section[aliasToWrite] = entryValue;
+    if (existingAlias && existingAlias !== entryKey && entryKey in section) {
+        delete section[entryKey];
+    }
+    return {
+        ...base,
+        [sectionKey]: section,
+    };
+}
 function vscodeGlobalConfigPath(home) {
     if (process.platform === 'win32') {
         const appData = process.env['APPDATA']?.trim() || path.join(home, 'AppData', 'Roaming');
@@ -98,14 +128,14 @@ export function upsertJsonMcpConfig(existing, options) {
         ...(options.includeTypeHttp ? { type: 'http' } : {}),
         url: options.url,
     }, bearerHeader(options.authToken, options.authEnvVar, 'shell'));
-    return `${JSON.stringify(upsertObjectEntry(base, 'mcpServers', options.serverAlias, serverConfig), null, 2)}\n`;
+    return `${JSON.stringify(upsertObjectEntryPreservingAliasByEndpoint(base, 'mcpServers', options.serverAlias, serverConfig, 'url'), null, 2)}\n`;
 }
 export function upsertAntigravityConfig(existing, options) {
     const base = parseJsonObject(existing);
     const serverConfig = withHeaders({
         serverUrl: options.url,
     }, bearerHeader(options.authToken, options.authEnvVar, 'shell'));
-    return `${JSON.stringify(upsertObjectEntry(base, 'mcpServers', options.serverAlias, serverConfig), null, 2)}\n`;
+    return `${JSON.stringify(upsertObjectEntryPreservingAliasByEndpoint(base, 'mcpServers', options.serverAlias, serverConfig, 'serverUrl'), null, 2)}\n`;
 }
 export function upsertVsCodeConfig(existing, options) {
     const base = parseJsonObject(existing);
@@ -113,7 +143,7 @@ export function upsertVsCodeConfig(existing, options) {
         type: 'http',
         url: options.url,
     }, bearerHeader(options.authToken, options.authEnvVar, 'vscode'));
-    return `${JSON.stringify(upsertObjectEntry(base, 'servers', options.serverAlias, serverConfig), null, 2)}\n`;
+    return `${JSON.stringify(upsertObjectEntryPreservingAliasByEndpoint(base, 'servers', options.serverAlias, serverConfig, 'url'), null, 2)}\n`;
 }
 export function upsertOpenCodeConfig(existing, options) {
     const base = parseJsonObject(existing);
@@ -130,7 +160,7 @@ export function upsertOpenCodeConfig(existing, options) {
         enabled: true,
         ...(headers ? { oauth: false } : {}),
     }, headers);
-    return `${JSON.stringify(upsertObjectEntry(nextBase, 'mcp', options.serverAlias, serverConfig), null, 2)}\n`;
+    return `${JSON.stringify(upsertObjectEntryPreservingAliasByEndpoint(nextBase, 'mcp', options.serverAlias, serverConfig, 'url'), null, 2)}\n`;
 }
 export function resolveMcpConfigPath(options) {
     const inferredScope = options.client === 'codex' || options.client === 'antigravity'

package/dist/lib/skill.js

@@ -156,6 +156,22 @@ function renderSkillArtifact(context) {
             };
     }
 }
+export function resolveSkillInstallTarget(options = {}) {
+    const client = options.client ?? 'codex';
+    const scope = normalizeScope(client, options.scope);
+    const targetDir = path.resolve(options.targetDir ?? defaultSkillDir(client, options.cwd, scope));
+    const artifact = renderSkillArtifact({
+        client,
+        serverAlias: options.serverAlias?.trim() || 'sp-rag',
+        mcpUrl: options.mcpUrl?.trim() || 'https://sp-rag.secomapp.com/mcp',
+        docsUrl: options.docsUrl?.trim() || 'https://sp-rag.secomapp.com/codegraph/docs/public?format=md',
+    });
+    return {
+        client,
+        scope,
+        path: path.join(targetDir, artifact.fileName),
+    };
+}
 export function renderSkill(options) {
     return renderSkillArtifact(options).content;
 }
@@ -166,21 +182,18 @@ export function renderCodexSkill(options) {
     });
 }
 export async function installSkill(options = {}) {
-    const client = options.client ?? 'codex';
-    const scope = normalizeScope(client, options.scope);
-    const targetDir = path.resolve(options.targetDir ?? defaultSkillDir(client, options.cwd, scope));
+    const resolved = resolveSkillInstallTarget(options);
     const artifact = renderSkillArtifact({
-        client,
+        client: resolved.client,
         serverAlias: options.serverAlias?.trim() || 'sp-rag',
         mcpUrl: options.mcpUrl?.trim() || 'https://sp-rag.secomapp.com/mcp',
         docsUrl: options.docsUrl?.trim() || 'https://sp-rag.secomapp.com/codegraph/docs/public?format=md',
     });
-    const filePath = path.join(targetDir, artifact.fileName);
-    await mkdir(targetDir, { recursive: true });
-    await writeFile(filePath, artifact.content, 'utf8');
+    await mkdir(path.dirname(resolved.path), { recursive: true });
+    await writeFile(resolved.path, artifact.content, 'utf8');
     return {
-        client,
-        path: filePath,
+        client: resolved.client,
+        path: resolved.path,
     };
 }
 export async function installCodexSkill(options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sp-rag",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "CLI cho setup MCP, codegraph GitNexus và skill của SP-RAG",
   "type": "module",
   "files": [