# `sp-rag` ## Context boundary `sp-rag` exists to connect IDEs/agents to SP-RAG evidence for the `seo-booster` application. - `graphrag-core` is the SP-RAG platform and knowledge runtime. - `seo-booster` is the target application and source workspace for app/business review. - `GitNexus`/codegraph references are platform internals or artifact sources, not the project to review unless the task explicitly asks for codegraph debugging. - For project-scoped installs, use `--cwd `. - Do not install project-scoped VS Code/Cursor/Claude config into `` when the goal is to review `seo-booster`. - Use `` as `--cwd` only when developing or debugging this SP-RAG platform itself. - `` and `` are placeholders, not literal paths. Replace them with the local checkout path on each machine, or omit `--cwd` when already inside the target repo. Canonical boundary doc: [../../docs/runbooks/sp-rag-seo-booster-boundary.md](../../docs/runbooks/sp-rag-seo-booster-boundary.md) CLI để setup nhanh SP-RAG theo hướng dev-friendly: - lưu cấu hình mặc định để dev không phải nhớ lại URL, client, alias - cài MCP config đúng format cho từng client - cài native skill / rule / custom agent cho từng IDE khi có convention ổn định - kiểm tra nhanh health và observability của stack - gọi sync codegraph/GitNexus theo branch hoặc `commit_sha` - đọc docs đã render - chạy evaluation/regression suite từ file JSON ## Yêu cầu - Node.js `>= 20` ## Trạng thái package - package npm public: `sp-rag` - version trong repo: `0.6.20` - npm latest sau publish: `0.6.20` - binary public: `sp-rag` ## Cài từ source trong monorepo ```bash cd apps/sp-rag-cli npm install npm test -- --run npm run build node dist/index.js doctor ``` ## Cài nhanh qua `npx` ```bash npx sp-rag@latest token add --token npx sp-rag@latest install --client codex --doctor npx sp-rag@latest install --client cursor --cwd npx sp-rag@latest install --client vscode --cwd npx sp-rag@latest add --client claude-code --scope project --cwd npx sp-rag@latest update --client claude-code --scope project --cwd npx sp-rag@latest uninstall --client claude-code --scope project --cwd npx sp-rag@latest explain --client vscode --scope project --cwd npx sp-rag@latest token add --token npx sp-rag@latest token verify --token npx sp-rag@latest set role team --cwd npx sp-rag@latest mcp add antigravity npx sp-rag@latest mcp add antigravity-ide npx sp-rag@latest mcp add opencode --scope project --cwd npx sp-rag@latest skill install --client cursor --scope project --cwd npx sp-rag@latest skill install --client vscode --scope project --cwd ``` Tương đương bằng `npm`: ```bash npm exec --yes sp-rag@latest token add -- --token npm exec --yes sp-rag@latest install -- --client codex --doctor npm exec --yes sp-rag@latest add -- --client claude-code --scope project --cwd npm exec --yes sp-rag@latest update -- --client claude-code --scope project --cwd npm exec --yes sp-rag@latest uninstall -- --client claude-code --scope project --cwd npm exec --yes sp-rag@latest explain -- --client vscode --scope project --cwd npm exec --yes sp-rag@latest token add -- --token npm exec --yes sp-rag@latest token verify -- --token npm exec --yes sp-rag@latest set role team -- --cwd ``` ## Flow gọn cho dev Flow khuyên dùng sau khi đã có `grc_pat_*`: 1. chạy `sp-rag token add --token ` đúng một lần để lưu token 2. chạy `install` cho client đầu tiên, không cần kèm `--mcp-token` 3. 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 4. khi muốn cập nhật lại MCP + skill mà giữ token cũ, dùng `update` 5. khi muốn gỡ sạch MCP + skill + config CLI do `sp-rag` tạo, dùng `uninstall` 6. khi chỉ muốn làm một nửa, dùng `mcp add` hoặc `skill install` 7. khi đổi token, chỉ cần `token add` 8. khi muốn kiểm tra máy đang được cấu hình ra sao, dùng `explain` Ghi chú: - với `cursor` và `vscode` ở `scope project`, nếu Sếpp đang đứng sẵn trong repo thì có thể bỏ `--cwd` - CLI sẽ tự dùng thư mục hiện tại cho cả MCP lẫn skill - `update` sẽ tự tính lại target project từ `--cwd` hoặc thư mục hiện tại, không dùng target cũ lệch project nếu user không truyền `--target-dir` - rule/agent mới route theo intent: feature/domain/docs thì MCP trước, còn edit/debug/current-code thì kiểm tra workspace trước - skill mới dùng hướng MCP-grounded + workspace-verified: tổng hợp từ `matched_passages`, `top_entities`, `top_relations`, `citations`, không bê nguyên `answer_brief`, và đối chiếu lại `git status --short`/file hiện tại khi cần Ví dụ: ```bash sp-rag token add --token sp-rag install --client vscode --cwd --doctor sp-rag add --client cursor --cwd sp-rag update --client vscode --cwd sp-rag uninstall --client claude-code --scope project --cwd sp-rag mcp add antigravity sp-rag mcp add antigravity-ide sp-rag skill install --client vscode --scope project --cwd sp-rag token add --token sp-rag explain --client vscode --scope project --cwd ``` ## 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://sb-rag.pielab.io/api/v1/account/login \ -H "Content-Type: application/json" \ -d '{"email":"dev@example.com","password":""}' ``` Lấy `session_token`, rồi gọi tiếp: ```bash curl -X POST https://sb-rag.pielab.io/api/v1/account/personal-access-tokens \ -H "Authorization: Bearer " \ -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 lưu token một lần rồi cài client: ```bash npx sp-rag@latest token add --token npx sp-rag@latest install --client cursor --cwd npx sp-rag@latest token verify --token npx sp-rag@latest explain --client cursor --scope project --cwd ``` Hoặc dùng biến môi trường: ```bash $env:GRAPHRAG_MCP_TOKEN="" npx sp-rag@latest mcp add vscode --scope project --cwd --auth-env-var GRAPHRAG_MCP_TOKEN npx sp-rag@latest token verify --token $env:GRAPHRAG_MCP_TOKEN ``` ## MCP client được hỗ trợ - `codex` - `cursor` - `claude-code` - `antigravity` - `antigravity-ide` - `vscode` - `opencode` ## Skill client được hỗ trợ - `codex` -> `SKILL.md` - `claude-code` -> `SKILL.md` - `antigravity` -> `SKILL.md` - `antigravity-ide` -> `SKILL.md` - `opencode` -> `SKILL.md` - `cursor` -> `.cursor/rules/sp-rag.mdc` - `vscode` -> `.github/agents/sp-rag.agent.md` + `.github/copilot-instructions.md` hoặc `~/.copilot/agents/sp-rag.agent.md` + `~/.copilot/instructions/sp-rag.instructions.md` Ghi chú: - generated skill luôn được render bằng tiếng Anh - `cursor` hiện nên dùng `scope project` cho rule `.mdc` - `vscode` hỗ trợ cả `scope project` lẫn `scope global` - nếu không muốn lưu token literal vào file config client, dùng `sp-rag mcp add --auth-env-var SP_RAG_MCP_TOKEN` ## Path mặc định quan trọng ### MCP - `codex`: `~/.codex/config.toml` - `cursor` project: `.cursor/mcp.json` - `cursor` global: `~/.cursor/mcp.json` - `claude-code`: `.mcp.json` - `antigravity`: `~/.gemini/config/mcp_config.json` - `antigravity-ide`: `~/.gemini/antigravity/mcp_config.json` - `vscode` project: `.vscode/mcp.json` - `vscode` global: file `mcp.json` trong user profile của VS Code - `opencode` project: `opencode.json` - `opencode` global: `~/.config/opencode/opencode.json` ### Skill / rule / custom agent - `codex`: `~/.codex/skills/sp-rag/SKILL.md` - `claude-code` project: `.claude/skills/sp-rag/SKILL.md` - `claude-code` global skill-only override: `~/.claude/skills/sp-rag/SKILL.md` - `antigravity`: `~/.gemini/antigravity/skills/sp-rag/SKILL.md` - `antigravity-ide`: `~/.gemini/antigravity/skills/sp-rag/SKILL.md` - `opencode`: `~/.config/opencode/skills/sp-rag/SKILL.md` - `cursor` project: `.cursor/rules/sp-rag.mdc` - `vscode` project: `.github/agents/sp-rag.agent.md` và `.github/copilot-instructions.md` - `vscode` global: `~/.copilot/agents/sp-rag.agent.md` và `~/.copilot/instructions/sp-rag.instructions.md` ## Luồng khuyên dùng cho dev mới ```bash sp-rag token add --token sp-rag install --client codex --doctor sp-rag add --client cursor --cwd sp-rag update --client cursor --cwd sp-rag uninstall --client cursor --scope project --cwd sp-rag explain --client codex sp-rag token verify --token sp-rag config show sp-rag set role team --cwd 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 sp-rag mcp add antigravity-ide sp-rag mcp add vscode --scope project --cwd sp-rag mcp add opencode --scope project --cwd sp-rag skill install --client codex sp-rag skill install --client cursor --scope project --cwd sp-rag skill install --client vscode --scope project --cwd sp-rag eval run --file ./examples/eval-suite.sample.json sp-rag update --client vscode --scope project --cwd sp-rag uninstall --client vscode --scope project --cwd ``` ## Lệnh chính ```bash sp-rag token add --token sp-rag install --client codex --doctor sp-rag add --client cursor --cwd sp-rag explain --client codex sp-rag token verify --token sp-rag config show sp-rag set role team --cwd sp-rag doctor sp-rag audit install --client codex sp-rag audit signal --file ./sp-audit-signal.json sp-rag codegraph status sp-rag codegraph watch --interval-ms 2000 sp-rag codegraph runs --limit 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 --webhook-token --gitlab-job-token sp-rag docs get public --format md sp-rag mcp add codex sp-rag mcp add antigravity sp-rag mcp add antigravity-ide sp-rag mcp add vscode --scope project --cwd sp-rag mcp add opencode --scope project --cwd sp-rag skill install --client codex sp-rag skill install --client cursor --scope project --cwd sp-rag skill install --client vscode --scope project --cwd sp-rag eval run --file ./examples/eval-suite.sample.json sp-rag update --client codex sp-rag update setup --client codex sp-rag uninstall --client codex ``` ## `doctor` kiểm gì `sp-rag doctor` giờ kiểm 2 lớp: - ping các endpoint `api`, `mcp`, `codegraph` - đọc đúng file MCP của client để kiểm: - IDE đang nhìn vào file nào - server entry nào được match theo alias hoặc theo endpoint - `Authorization` đang là token literal, env var hợp lệ, hay đang thiếu - riêng Codex, xác nhận `bearer_token_env_var`/`http_headers` thay vì legacy `[mcp_servers..headers]` - khả năng IDE sẽ bật link đăng nhập OAuth Ví dụ: ```bash sp-rag doctor --client vscode --scope project --cwd ``` Nếu output có dòng: ```text - Authorization: thiếu hoàn toàn - Khả năng IDE bật link đăng nhập: cao ``` thì vấn đề thường không nằm ở skill, mà ở chỗ IDE chưa nạp được bearer header từ file MCP thực tế. ## Cấu hình mặc định CLI lưu cấu hình tại: - `~/.sp-rag/config.json` - có thể override home dir bằng `SP_RAG_HOME_DIR` CLI có thể lưu thêm: - `mcpToken` cho flow cài nhanh - `authEnvVar` nếu muốn client đọc token từ biến môi trường thay vì lưu literal - `defaultClient`, `defaultScope`, `skillClient`, `setupRole` Giá trị mặc định: - base URL: `https://sb-rag.pielab.io` - MCP URL: `https://sb-rag.pielab.io/mcp` - alias MCP: `sp-rag` ## Audit workflow `sp-rag audit` `sp-audit` khong phai la CLI moi. No la skill/agent workflow duoc cai bang CLI hien tai `sp-rag`. Lenh chuan de cai audit workflow: ```bash sp-rag audit install --client codex ``` Lenh nay: - cai MCP config cho client da chon - cai native skill/rule/custom agent `sp-audit` - tai su dung config/token cua `sp-rag` - van la cung binary `sp-rag`, tuong tu `sp-rag add` hay `sp-rag doctor` - neu token chua duoc luu, chay `sp-rag token add --token ` mot lan truoc do - scope mac dinh suy theo client: `codex` la global, `cursor`/`vscode` la project Neu chi muon cai lai skill audit ma khong cham vao MCP config, co the dung low-level command: ```bash sp-rag skill install --client codex --name sp-audit ``` Day JSON signal do `sp-audit` tao ra vao server memory import path: ```bash sp-rag audit signal --file ./sp-audit-signal.json ``` `audit signal` posts through the existing knowledge-source import API with `normalizer_provider=heuristic` and `warm_cache=false`, so small audit feedback records do not block on AI normalization or semantic-cache materialization. Native paths cua audit workflow: - Codex: `~/.codex/skills/sp-audit/SKILL.md` - Claude Code: `.claude/skills/sp-audit/SKILL.md` hoac `~/.claude/skills/sp-audit/SKILL.md` - Antigravity: `~/.gemini/antigravity/skills/sp-audit/SKILL.md` - Antigravity IDE: `~/.gemini/antigravity/skills/sp-audit/SKILL.md` - OpenCode: `~/.config/opencode/skills/sp-audit/SKILL.md` - Cursor: `.cursor/rules/sp-audit.mdc` - VS Code: `.github/agents/sp-audit.agent.md` hoac `~/.copilot/agents/sp-audit.agent.md` Chi tiet: [Runbook `sp-rag audit`](../../docs/runbooks/sp-audit.md). ## Evaluation mẫu - file mẫu: [`examples/eval-suite.sample.json`](./examples/eval-suite.sample.json) ## Tài liệu thêm - [Hướng dẫn dev sử dụng SP-RAG](../../docs/runbooks/dev-usage-guide.md) - [Runbook CLI `sp-rag`](../../docs/runbooks/sp-rag-cli.md) - [Runbook `sp-rag audit`](../../docs/runbooks/sp-audit.md) - [Runbook phát hành CLI `sp-rag`](../../docs/runbooks/sp-rag-cli-release.md) - [Runbook MCP Public](../../docs/runbooks/mcp-public-clients.md)