Giao diện
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-fe/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-fe/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-fe/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-fe/* + 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 (/v3/, /v2/…) mà package thuộc về.
Bản 2.0 của @tasco-fe/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. npx tải @tasco-fe/mcp từ npmjs.org như mọi package @tasco-fe/*: không cần token hay dòng registry.
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à request bị 401.
Kiểm tra ở thư mục gốc project, in ra số version là được:
bash
npm view @tasco-fe/mcp version2. Ghim version. npx -y @tasco-fe/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-fe/* 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:
json
{
"mcpServers": {
"tasco": { "command": "npx", "args": ["-y", "@tasco-fe/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.
bash
claude mcp add --scope project tasco -- npx -y @tasco-fe/mcp@23. 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.
bash
claude mcp listTrạ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:
bash
pnpm --filter @tasco-fe/mcp buildServer 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 | .npmrc hoặc ~/.npmrc còn dòng _authToken cũ (vd ${NPM_TOKEN} rỗng) → xoá dòng đó |
E404 | Gõ sai tên package (scope là @tasco-fe), hoặc .npmrc còn trỏ registry khác → xoá dòng registry thừa |
| 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-fe/mcp |
| Windows (không phải WSL) | Bọc qua cmd: "command": "cmd", "args": ["/c", "npx", "-y", "@tasco-fe/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-fe/mcp@2 bằng node packages/mcp/bin/cli.mjs.
bash
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-fe/mcp@2Thiết lập mỗi dev làm 1 lần
- Token registry trong
~/.npmrccho MCPtasco: xem bước 1 ở mục Cấu hình Claude Code phía trên. - PAT GitLab cho MCP
gitlab:
bash
# ~/.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 | Credential Jenkins | Job ai-review (chưa bật trên Jenkins) |
GITLAB_REVIEW_TOKEN | Credential Jenkins — PAT scope api, role ≥ Reporter | Post comment MR |
AI_GATEWAY_URL / AI_GATEWAY_KEY | Credential Jenkins | Job ai-eval (chưa bật trên Jenkins) |
GITLAB_TOKEN | Shell mỗi dev | MCP gitlab |