Skip to content

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 ​

FileVai trò
CLAUDE.mdContext chuẩn cho AI: kiến trúc, quy ước, gotchas — AI đọc mỗi session
.mcp.jsonKhai báo MCP server: tasco (tri thức framework) + gitlab (MR/issue/CI) + figma (thiết kế)
.claude/settings.jsonGuardrail: 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:

ToolTrả về
list_componentsComponent C* của @tasco-fe/ui và primitive antdv re-export (CSelect, CModal…)
get_componentProps, sự kiện kèm kiểu payload, slot, link trang docs; primitive trả tên gốc antdv và cách import
list_tokensToken light/dark từ @tasco-fe/theme
search_docsMụ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_packagesPackage @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 version

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

bash
claude mcp list
Trạng thái của tascoViệc cần làm
✔ ConnectedXong
⏸ Pending approvalMở claude trong terminal tại project và chọn duyệt
Đã lỡ từ chốiChạ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 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ứngCách xử lý
Failed to connect, không rõ lý doChạ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 đó
E404Gõ 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.mjsChư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@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:
bash
# ~/.zshrc — PAT GitLab scope `api` cho MCP gitlab
export GITLAB_TOKEN=glpat-...

Skill nội bộ (repo core) ​

SkillViệ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_KEYCredential JenkinsJob ai-review (chưa bật trên Jenkins)
GITLAB_REVIEW_TOKENCredential Jenkins — PAT scope api, role ≥ ReporterPost comment MR
AI_GATEWAY_URL / AI_GATEWAY_KEYCredential JenkinsJob ai-eval (chưa bật trên Jenkins)
GITLAB_TOKENShell mỗi devMCP gitlab