sp-rag 0.5.0 → 0.6.1

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.5.0`
+- version đang publish: `0.6.1`
 - binary public: `sp-rag`
 
 ## Cài từ source trong monorepo
@@ -33,12 +33,13 @@ node dist/index.js doctor
 ## Cài nhanh qua `npx`
 
 ```bash
-npx sp-rag@latest install --client codex --mcp-token <token truy cập MCP> --doctor
-npx sp-rag@latest install --client cursor --scope project --cwd D:/Webs/seo-booster --mcp-token <token truy cập MCP>
-npx sp-rag@latest install --client vscode --scope project --cwd D:/Webs/seo-booster --mcp-token <token truy cập MCP>
-npx sp-rag@latest token add --token <token truy cập MCP> --client codex
-npx sp-rag@latest mcp add antigravity --mcp-token <token truy cập MCP>
-npx sp-rag@latest mcp add opencode --scope project --cwd D:/Webs/seo-booster --mcp-token <token truy cập MCP>
+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 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
 ```
@@ -46,8 +47,68 @@ npx sp-rag@latest skill install --skill-client vscode --scope project --cwd D:/W
 Tương đương bằng `npm`:
 
 ```bash
-npm exec --yes sp-rag@latest install -- --client codex --mcp-token <token truy cập MCP> --doctor
-npm exec --yes sp-rag@latest token add -- --token <token truy cập MCP> --client codex
+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 token verify -- --token <grc_pat_...>
+```
+
+## 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.
+
+Luồng chuẩn:
+
+1. đăng nhập dashboard hoặc API account của GraphRAG
+2. tạo `personal access token` qua account hiện tại
+3. dùng chính token `grc_pat_*` đó cho MCP và CLI
+4. kiểm tra token bằng `sp-rag token verify`
+
+Điểm quan trọng:
+
+- token dev dùng cho MCP nên là `grc_pat_*` của account
+- 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ó:
+
+1. lấy session token qua `POST /v1/account/login`
+2. gọi `POST /v1/account/personal-access-tokens`
+3. dùng trường `generated_token`
+
+Ví dụ đầy đủ:
+
+```bash
+curl -X POST https://sp-rag.secomapp.com/api/v1/account/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"dev@example.com","password":"<mật-khẩu>"}'
+```
+
+Lấy `session_token`, rồi gọi tiếp:
+
+```bash
+curl -X POST https://sp-rag.secomapp.com/api/v1/account/personal-access-tokens \
+  -H "Authorization: Bearer <grc_sess_...>" \
+  -H "Content-Type: application/json" \
+  -d '{"label":"SP-RAG CLI","expires_in_days":30}'
+```
+
+Response sẽ trả `generated_token`, chính là token `grc_pat_*` để đưa vào `sp-rag`.
+
+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_...>
+```
+
+Hoặc dùng biến môi trường:
+
+```bash
+$env:GRAPHRAG_MCP_TOKEN="<grc_pat_...>"
+npx sp-rag@latest mcp add vscode --scope project --cwd D:/Webs/seo-booster --auth-env-var GRAPHRAG_MCP_TOKEN
+npx sp-rag@latest token verify --token $env:GRAPHRAG_MCP_TOKEN
 ```
 
 ## MCP client được hỗ trợ
@@ -102,17 +163,18 @@ Ghi chú:
 ## Luồng khuyên dùng cho dev mới
 
 ```bash
-sp-rag install --client codex --mcp-token <token truy cập MCP> --doctor
-sp-rag token add --token <token truy cập MCP> --client codex
+sp-rag install --client codex --mcp-token <grc_pat_...> --doctor
+sp-rag token add --token <grc_pat_...> --client codex
+sp-rag token verify --token <grc_pat_...>
 sp-rag config show
 sp-rag codegraph status
 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 <token truy cập MCP>
-sp-rag mcp add vscode --scope project --cwd D:/Webs/seo-booster --mcp-token <token truy cập MCP>
-sp-rag mcp add opencode --scope project --cwd D:/Webs/seo-booster --mcp-token <token truy cập MCP>
+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
@@ -122,8 +184,9 @@ sp-rag eval run --file ./examples/eval-suite.sample.json
 ## Lệnh chính
 
 ```bash
-sp-rag install --client codex --mcp-token <token truy cập MCP> --doctor
-sp-rag token add --token <token truy cập MCP> --client codex
+sp-rag install --client codex --mcp-token <grc_pat_...> --doctor
+sp-rag token add --token <grc_pat_...> --client codex
+sp-rag token verify --token <grc_pat_...>
 sp-rag config show
 sp-rag doctor
 sp-rag codegraph status
@@ -133,10 +196,10 @@ 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 <token truy cập MCP>
-sp-rag mcp add antigravity --mcp-token <token truy cập MCP>
-sp-rag mcp add vscode --scope project --cwd D:/Webs/seo-booster --mcp-token <token truy cập MCP>
-sp-rag mcp add opencode --scope project --cwd D:/Webs/seo-booster --mcp-token <token truy cập MCP>
+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

package/dist/cli.js

@@ -140,6 +140,7 @@ 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 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 verify [--token TOKEN] [--base-url URL]
   sp-rag config show
   sp-rag doctor [--base-url URL]
   sp-rag codegraph status [--base-url URL]
@@ -375,6 +376,21 @@ async function runTokenAdd(parsed) {
         },
     }, nextDefaults, client);
 }
+async function runTokenVerify(parsed) {
+    const defaults = await loadRuntimeDefaults(parsed);
+    const token = optionString(parsed, 'token') ?? optionString(parsed, 'mcp-token') ?? defaults.mcpToken;
+    if (!token?.trim()) {
+        throw new Error('Thiếu token. Dùng --token <token>.');
+    }
+    const baseUrl = defaults.baseUrl.replace(/\/+$/, '');
+    const result = await fetchJson(`${baseUrl}/api/v1/ops/operator-auth`, {
+        method: 'GET',
+        headers: {
+            authorization: `Bearer ${token.trim()}`,
+        },
+    });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
 async function runConfigShow(parsed) {
     const config = await loadCliConfig(optionString(parsed, 'home-dir'));
     process.stdout.write(`${JSON.stringify(config ?? {}, null, 2)}\n`);
@@ -427,6 +443,10 @@ export async function runCli(argv) {
             await runTokenAdd(parsed);
             return 0;
         }
+        if (group === 'token' && action === 'verify') {
+            await runTokenVerify(parsed);
+            return 0;
+        }
         if (group === 'config' && action === 'show') {
             await runConfigShow(parsed);
             return 0;
@@ -491,7 +511,7 @@ export async function runCli(argv) {
             return 0;
         }
         if (group === 'version') {
-            process.stdout.write('sp-rag 0.5.0\n');
+            process.stdout.write('sp-rag 0.6.1\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/package.json

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