sp-rag

v0.6.16

Published

25 days ago

CLI cho setup MCP, codegraph GitNexus và skill của SP-RAG

0High
0Medium
0Low

mawta

rag mcp gitnexus cli sp-rag

`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 <seo-booster-workspace>.
Do not install project-scoped VS Code/Cursor/Claude config into <graphrag-core-workspace> when the goal is to review seo-booster.
Use <graphrag-core-workspace> as --cwd only when developing or debugging this SP-RAG platform itself.
<seo-booster-workspace> and <graphrag-core-workspace> 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

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.16
npm latest hiện tại: 0.6.15
binary public: sp-rag

Cài từ source trong monorepo

cd apps/sp-rag-cli
npm install
npm test -- --run
npm run build
node dist/index.js doctor

Cài nhanh qua `npx`

npx sp-rag@latest token add --token <grc_pat_...>
npx sp-rag@latest install --client codex --doctor
npx sp-rag@latest install --client cursor --cwd <seo-booster-workspace>
npx sp-rag@latest install --client vscode --cwd <seo-booster-workspace>
npx sp-rag@latest add --client claude-code --scope project --cwd <seo-booster-workspace>
npx sp-rag@latest update --client claude-code --scope project --cwd <seo-booster-workspace>
npx sp-rag@latest uninstall --client claude-code --scope project --cwd <seo-booster-workspace>
npx sp-rag@latest explain --client vscode --scope project --cwd <seo-booster-workspace>
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
npx sp-rag@latest mcp add opencode --scope project --cwd <seo-booster-workspace>
npx sp-rag@latest skill install --client cursor --scope project --cwd <seo-booster-workspace>
npx sp-rag@latest skill install --client vscode --scope project --cwd <seo-booster-workspace>

Tương đương bằng npm:

npm exec --yes sp-rag@latest token add -- --token <grc_pat_...>
npm exec --yes sp-rag@latest install -- --client codex --doctor
npm exec --yes sp-rag@latest add -- --client claude-code --scope project --cwd <seo-booster-workspace>
npm exec --yes sp-rag@latest update -- --client claude-code --scope project --cwd <seo-booster-workspace>
npm exec --yes sp-rag@latest uninstall -- --client claude-code --scope project --cwd <seo-booster-workspace>
npm exec --yes sp-rag@latest explain -- --client vscode --scope project --cwd <seo-booster-workspace>
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_*:

chạy sp-rag token add --token <grc_pat_...> đúng một lần để lưu token
chạy install cho client đầu tiên, không cần kèm --mcp-token
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
khi muốn cập nhật lại MCP + skill mà giữ token cũ, dùng update
khi muốn gỡ sạch MCP + skill + config CLI do sp-rag tạo, dùng uninstall
khi chỉ muốn làm một nửa, dùng mcp add hoặc skill install
khi đổi token, chỉ cần token add
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ụ:

sp-rag token add --token <grc_pat_...>
sp-rag install --client vscode --cwd <seo-booster-workspace> --doctor
sp-rag add --client cursor --cwd <seo-booster-workspace>
sp-rag update --client vscode --cwd <seo-booster-workspace>
sp-rag uninstall --client claude-code --scope project --cwd <seo-booster-workspace>
sp-rag mcp add antigravity
sp-rag skill install --client vscode --scope project --cwd <seo-booster-workspace>
sp-rag token add --token <grc_pat_moi>
sp-rag explain --client vscode --scope project --cwd <seo-booster-workspace>

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:

đăng nhập dashboard hoặc API account của GraphRAG
tạo personal access token qua account hiện tại
dùng chính token grc_pat_* đó cho MCP và CLI
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ó:

lấy session token qua POST /v1/account/login
gọi POST /v1/account/personal-access-tokens
dùng trường generated_token

Ví dụ đầy đủ:

curl -X POST https://sp-rag.secomapp.com/api/v1/account/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"<mật-khẩu>"}'

Lấy session_token, rồi gọi tiếp:

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 lưu token một lần rồi cài client:

npx sp-rag@latest token add --token <grc_pat_...>
npx sp-rag@latest install --client cursor --cwd <seo-booster-workspace>
npx sp-rag@latest token verify --token <grc_pat_...>
npx sp-rag@latest explain --client cursor --scope project --cwd <seo-booster-workspace>

Hoặc dùng biến môi trường:

$env:GRAPHRAG_MCP_TOKEN="<grc_pat_...>"
npx sp-rag@latest mcp add vscode --scope project --cwd <seo-booster-workspace> --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
vscode
opencode

Skill client được hỗ trợ

codex -> SKILL.md
claude-code -> SKILL.md
antigravity -> 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/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
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

sp-rag token add --token <grc_pat_...>
sp-rag install --client codex --doctor
sp-rag add --client cursor --cwd <seo-booster-workspace>
sp-rag update --client cursor --cwd <seo-booster-workspace>
sp-rag uninstall --client cursor --scope project --cwd <seo-booster-workspace>
sp-rag explain --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
sp-rag mcp add vscode --scope project --cwd <seo-booster-workspace>
sp-rag mcp add opencode --scope project --cwd <seo-booster-workspace>
sp-rag skill install --client codex
sp-rag skill install --client cursor --scope project --cwd <seo-booster-workspace>
sp-rag skill install --client vscode --scope project --cwd <seo-booster-workspace>
sp-rag eval run --file ./examples/eval-suite.sample.json
sp-rag update --client vscode --scope project --cwd <seo-booster-workspace>
sp-rag uninstall --client vscode --scope project --cwd <seo-booster-workspace>

Lệnh chính

sp-rag token add --token <grc_pat_...>
sp-rag install --client codex --doctor
sp-rag add --client cursor --cwd <seo-booster-workspace>
sp-rag explain --client codex
sp-rag token verify --token <grc_pat_...>
sp-rag config show
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 <sha> --webhook-token <token webhook codegraph> --gitlab-job-token <ci-job-token>
sp-rag docs get public --format md
sp-rag mcp add codex
sp-rag mcp add antigravity
sp-rag mcp add vscode --scope project --cwd <seo-booster-workspace>
sp-rag mcp add opencode --scope project --cwd <seo-booster-workspace>
sp-rag skill install --client codex
sp-rag skill install --client cursor --scope project --cwd <seo-booster-workspace>
sp-rag skill install --client vscode --scope project --cwd <seo-booster-workspace>
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.<alias>.headers]
- khả năng IDE sẽ bật link đăng nhập OAuth

Ví dụ:

sp-rag doctor --client vscode --scope project --cwd <seo-booster-workspace>

Nếu output có dòng:

- 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

Giá trị mặc định:

base URL: https://sp-rag.secomapp.com
MCP URL: https://sp-rag.secomapp.com/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:

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 <grc_pat_...> 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:

sp-rag skill install --client codex --name sp-audit

Day JSON signal do sp-audit tao ra vao server memory import path:

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
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.

Evaluation mẫu

file mẫu: examples/eval-suite.sample.json

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme