AI tooling cho dev

Bộ công cụ để Claude Code / Cursor làm việc đúng chuẩn framework trong cả repo core lẫn repo sản phẩm. App scaffold bằng create-tasco-app đã có sẵn các file cấu hình dưới đây; mỗi dev chỉ cần thêm token và duyệt MCP server một lần.

Có sẵn trong repo

File	Vai trò
CLAUDE.md	Context chuẩn cho AI: kiến trúc, quy ước, gotchas — AI đọc mỗi session
.mcp.json	Khai báo MCP server: tasco (tri thức framework) + gitlab (MR/issue/CI) + figma (thiết kế)
.claude/settings.json	Guardrail: allow sẵn lệnh lint/test/build + git read-only; deny đọc .env*, ~/.npmrc, force-push

MCP server @tasco/mcp

Phơi tri thức framework cho AI — component C* (props, sự kiện, slot thật, không đoán), design token --tasco-*, docs + gotchas, danh sách package. Server chạy qua stdio, mọi tool đều chỉ đọc:

Tool	Trả về
list_components	Component C* của @tasco/ui và primitive antdv re-export (CSelect, CModal…)
get_component	Props, sự kiện kèm kiểu payload, slot, link trang docs; primitive trả tên gốc antdv và cách import
list_tokens	Token light/dark từ @tasco/theme
search_docs	Mục docs và gotcha khớp từ khoá, kèm link tới đúng mục trên site
read_doc từ 2.1	Đọc đủ một mục hoặc cả trang theo link, route (/guide/auth/guard) hoặc đường dẫn file
list_packages	Package @tasco/* + version + vai trò

Dữ liệu sinh lúc build và ship kèm package → chạy standalone trong repo sản phẩm qua npx, không cần monorepo core. Bảng API trong trang component và get_component đọc cùng một file, nên AI và người đọc docs thấy cùng một API. Link docs trỏ đúng bản /v2/ mà package thuộc về.

Bản 2.0 của @tasco/mcp chỉ có props và tên sự kiện, search_docs trả cả trang; slot, kiểu payload, primitive, link tới từng mục và read_doc có từ 2.1.

Cấu hình Claude Code (repo sản phẩm)

1. Registry và token. npx tải @tasco/mcp từ GitLab Package Registry như mọi package @tasco/*. .npmrc của project chỉ commit dòng registry trỏ group endpoint; token (Group Deploy Token scope read_package_registry) để trong ~/.npmrc cá nhân:

# .npmrc của project (commit)
@tasco:registry=https://gitlab.dnpwater.vn/api/v4/groups/tasco/-/packages/npm/

# ~/.npmrc cá nhân (không commit)
//gitlab.dnpwater.vn/api/v4/groups/tasco/-/packages/npm/:_authToken=<token>

WARNING

Không commit dòng _authToken=${NPM_TOKEN} vào .npmrc của project. App Claude desktop không nạp biến export trong ~/.zshrc cho MCP server. Khi biến không tồn tại, npm giữ nguyên chuỗi ${NPM_TOKEN} làm token, và dòng này ở project đè token đúng trong ~/.npmrc → 401. CI tự append dòng token trong before_script (xem Cấu hình .npmrc).

Kiểm tra ở thư mục gốc project, in ra số version là được:

npm view @tasco/mcp version

2. Ghim version. npx -y @tasco/mcp không ghim version, nên AI có thể đọc dữ liệu (props, token, link docs) của bản khác với bản app đang cài. Ghim cùng major với @tasco/* trong package.json — app tạo bằng create-tasco-app từ 2.1 đã ghim sẵn; app tạo từ bản CLI cũ hơn thì sửa tay, ví dụ app đang dùng 2.x:

{
  "mcpServers": {
    "tasco": { "command": "npx", "args": ["-y", "@tasco/mcp@2"] }
  }
}

Repo chưa có .mcp.json thì tạo bằng lệnh dưới. --scope project ghi vào .mcp.json để commit cho cả team; --scope user dùng cho mọi repo trên máy.

claude mcp add --scope project tasco -- npx -y @tasco/mcp@2

3. Duyệt server và kiểm tra. Server khai báo trong .mcp.json phải được duyệt ở lần đầu dùng. Trạng thái duyệt của CLI tách biệt với app desktop: app đang chạy tasco bình thường thì claude mcp list vẫn có thể báo chờ duyệt.

claude mcp list

Trạng thái của tasco	Việc cần làm
✔ Connected	Xong
⏸ Pending approval	Mở claude trong terminal tại project và chọn duyệt
Đã lỡ từ chối	Chạy claude mcp reset-project-choices rồi mở lại claude

Sau đó hỏi "CChat có những props nào?" — AI gọi get_component và trả đúng props là MCP tasco đã chạy. Mọi tool đều chỉ đọc, nên có thể thêm "mcp__tasco" vào permissions.allow trong .claude/settings.json để AI không hỏi quyền mỗi lần gọi.

Repo core

.mcp.json của repo core chạy thẳng từ source (node packages/mcp/bin/cli.mjs), không qua registry, nên phải build trước:

pnpm --filter @tasco/mcp build

Server chỉ nạp data/*.json lúc khởi động. Sửa component, token hoặc docs xong thì build lại rồi mở session mới (hoặc /mcp → Reconnect).

Xử lý lỗi

Triệu chứng	Cách xử lý
Failed to connect, không rõ lý do	Chạy server bằng tay (lệnh bên dưới) để xem stderr
E401	Thiếu token, dòng _authToken không khớp host/path của @tasco:registry, hoặc bị dòng ${NPM_TOKEN} ở project đè
E404	.npmrc còn trỏ instance endpoint …/api/v4/packages/npm/ mà dev không phải member → đổi sang group endpoint
Timeout ở lần đầu (npx đang tải package)	Chạy lệnh test bên dưới một lần để có sẵn cache; với CLI có thể dùng MCP_TIMEOUT=60000 claude
Repo core: ERR_MODULE_NOT_FOUND …/dist/index.mjs	Chưa build @tasco/mcp
Windows (không phải WSL)	Bọc qua cmd: "command": "cmd", "args": ["/c", "npx", "-y", "@tasco/mcp@2"]

Lệnh test chạy ở gốc project, in ra JSON có list_components là server chạy đúng. Ở repo core, thay npx -y @tasco/mcp@2 bằng node packages/mcp/bin/cli.mjs.

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"0"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | npx -y @tasco/mcp@2

Thiết lập mỗi dev làm 1 lần

• Token registry trong ~/.npmrc cho MCP tasco: xem bước 1 ở mục Cấu hình Claude Code phía trên.
• PAT GitLab cho MCP gitlab:

# ~/.zshrc — PAT GitLab scope `api` cho MCP gitlab
export GITLAB_TOKEN=glpat-...

Skill nội bộ (repo core)

Skill	Việc
/new-component <Tên>	Tạo component C* đủ bộ: component + test + đăng ký 4 chỗ (index.ts, install.ts, tasco.d.ts, env.d.ts của docs) + trang docs + changeset
/doc-component <Tên>	Soạn nháp trang docs và demo của một component từ source, test, story

AI review trên MR

Job CI ai-review chạy Claude Code headless review mỗi MR: bám quy ước CLAUDE.md, soi vi phạm kiến trúc / bug / thiếu changeset / security, post comment lên MR. allow_failure — chỉ tham khảo, người duyệt vẫn quyết. Prompt ở .claude/ci-review-prompt.md.

Biến cần cấu hình (admin làm 1 lần)

Biến	Đặt ở	Dùng cho
ANTHROPIC_API_KEY	CI/CD Variables (masked)	Job ai-review
GITLAB_REVIEW_TOKEN	CI/CD Variables (masked) — PAT scope api, role ≥ Reporter	Post comment MR
AI_GATEWAY_URL / AI_GATEWAY_KEY	CI/CD Variables (masked)	Job ai-eval
GITLAB_TOKEN	Shell mỗi dev	MCP gitlab