sp-rag

v0.6.14

Published

3 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`

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 đang publish: 0.6.14
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 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 add --client claude-code --scope project --cwd D:/Webs/seo-booster
npx sp-rag@latest update --client claude-code --scope project --cwd D:/Webs/seo-booster
npx sp-rag@latest uninstall --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
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:

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

chạy install đúng một lần cho client đầu tiên, có 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 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 update --client vscode --scope project --cwd D:/Webs/seo-booster
sp-rag uninstall --client claude-code --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.

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 dùng token trực tiếp:

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:

$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ợ

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 install --client codex --mcp-token <grc_pat_...> --doctor
sp-rag add --client cursor --scope project --cwd D:/Webs/seo-booster
sp-rag update --client cursor --scope project --cwd D:/Webs/seo-booster
sp-rag uninstall --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
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 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 --client vscode --scope project --cwd D:/Webs/seo-booster
sp-rag uninstall --client vscode --scope project --cwd D:/Webs/seo-booster

Lệnh chính

sp-rag install --client codex --mcp-token <grc_pat_...> --doctor
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
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 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 --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
- khả năng IDE sẽ bật link đăng nhập OAuth

Ví dụ:

sp-rag doctor --client vscode --scope project --cwd D:/Webs/seo-booster

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

Evaluation mẫu

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme