MCP & AI review

Ba công cụ AI core duy trì cho cả core lẫn team sản phẩm: MCP server @tasco/mcp, job AI review trên MR, và bộ prompt có eval của @tasco/ai. Cách dùng phía team sản phẩm: AI tooling cho dev.

@tasco/mcp

MCP server chạy qua stdio, cho Claude Code/Cursor tra tri thức framework thay vì đoán. Mọi tool chỉ đọc. Lúc kết nối, server gửi instructions cho client: tool nào dùng cho việc gì, app không import ant-design-vue.

Tool	Trả về	Dữ liệu từ
list_components	Component C* (mô tả, số props/sự kiện/slot) và primitive antdv re-export	component-meta.json, packages/ui/src/index.ts
get_component	Props, sự kiện kèm kiểu payload, slot, link trang docs; primitive (CSelect…) trả tên gốc antdv và cách import	@tasco/ui/component-meta.json — cùng nguồn với bảng API của docs
list_tokens	Biến --tasco-* sáng/tối, lọc theo tên	cssVars() của @tasco/theme
search_docs	Mục ##/### khớp từ khoá, kèm link /v<major>/…#anchor và đoạn đầu nội dung	docs/**/*.md, CLAUDE.md
read_doc	Đủ một mục kèm mục con, hoặc cả trang — nhận link, route hoặc đường dẫn file	Như search_docs
list_packages	Package @tasco/*, version, mô tả	package.json các package

Dữ liệu sinh lúc build

pnpm --filter @tasco/mcp build        # turbo build @tasco/theme, @tasco/ui trước
  └─ tsx scripts/generate.ts → data/components.json, primitives.json, tokens.json, docs.json, packages.json
  └─ unbuild → dist/

data/ đóng gói cùng package nên server chạy độc lập trong repo sản phẩm. Hệ quả: tri thức đứng yên theo bản phát hành — đổi component, token hay docs thì bản MCP mới chỉ có ở lần publish sau. Trang sinh lúc build docs (Tra cứu API, Changelog) không vào dữ liệu: job release chỉ build packages/*, và script bỏ qua các trang đó để dữ liệu build trên máy giống trên CI.

Markdown của docs qua ba bước trước khi thành dữ liệu:

1. Thay <!--@include--> như VitePress. Vùng của CLAUDE.md đã nhúng vào trang docs chỉ giữ ở trang đó (có link, search_docs không trả hai kết quả trùng); mục tương ứng trong CLAUDE.md còn một dòng trỏ tới trang.
2. Tách theo ## và ### nằm ngoài code block. Anchor tính cùng thuật toán slugify của VitePress, kể cả {#id} và hậu tố -1 khi trùng tên.
3. Thay <demo src> bằng code của file demo, <ApiTable> bằng props/sự kiện/slot, <TokenTable> bằng token; link trong trang thành link tuyệt đối https://web.docs.vtii.vn/v<major>/….

Major của link lấy từ base trong docs/.vitepress/config.ts — đúng nơi docs cùng commit được deploy: app dùng @tasco/mcp@2 nhận link /v2/, kể cả sau khi 3.0 ra mắt, và bản beta 3.0 (docs vẫn ở /v2/) không trả link /v3/ chưa tồn tại. Job quality chạy scripts/check-mcp-links.mjs sau pnpm build: mọi link trong data/*.json phải trỏ tới trang và id heading có thật trong bản build docs — đổi cách đọc markdown hay nâng VitePress mà lệch anchor thì fail.

Repo core chạy server thẳng từ source (.mcp.json gọi node packages/mcp/bin/cli.mjs): build lại rồi mở session mới sau khi sửa component hoặc docs.

Sửa MCP

Việc	Sửa
Thêm tool	src/server.ts (registerTool với schema zod, mô tả tiếng Việt), hàm định dạng trong src/format.ts, test cho hàm định dạng; sửa INSTRUCTIONS nếu tool đổi cách AI nên làm việc
Thêm loại dữ liệu	scripts/generate.ts sinh file mới, kiểu trong src/types.ts, nạp trong src/data.ts
Đổi cách đọc markdown	src/markdown.ts (frontmatter, include, heading, anchor), src/doc-entries.ts (thẻ của theme docs)
Đổi cách tìm docs	src/docs.ts + docs.test.ts
Theme docs có thẻ mới dùng trong markdown	Cách thay thẻ trong src/doc-entries.ts — không thì AI chỉ thấy dòng thẻ trần

Ngưỡng coverage 90% dòng; server.ts, data.ts, index.ts là glue nên nằm ngoài coverage — logic đặt ở các module còn lại để test được. Module chỉ chạy lúc sinh dữ liệu (primitives.ts dùng typescript) không được import từ server.ts: typescript không nằm trong dependencies, server trong repo sản phẩm sẽ lỗi ngay khi khởi động.

Thử server không cần client AI: gửi initialize và tools/list qua stdin — lệnh có sẵn ở AI tooling cho dev › Xử lý lỗi.

Giới hạn đã biết

• search_docs khớp từ khoá (có bỏ dấu), không hiểu từ đồng nghĩa: hỏi "xoá bản ghi" không ra mục chỉ viết "huỷ đơn". AI nên thử lại bằng từ khác hoặc tên API.
• API của package TS (useTable, toAppError…) chỉ có ở các trang hướng dẫn nhắc tới — trang Tra cứu sinh bằng TypeDoc không vào dữ liệu MCP.

AI review trên MR

Job ai-review (CI/CD) chạy Claude Code headless trên diff của MR:

• Ngữ cảnh: CLAUDE.md tự nạp; mr.diff (diff từ merge-base, tối đa 200KB); mr-description.md (mô tả MR).
• Prompt: .claude/ci-review-prompt.md — thứ tự ưu tiên: vi phạm kiến trúc → bug → thiếu changeset/test/đăng ký component → bảo mật → checklist MR chưa đủ.
• Quyền: chỉ Read, Grep, Glob; model claude-sonnet-5; tối đa 30 lượt.
• Đầu ra: comment markdown ≤ 400 từ, mỗi vấn đề một dòng 🔴 Chặn hoặc 🟡 Nên sửa, không khen.

Review không chặn merge. Người duyệt đọc như một reviewer thêm: 🔴 cần xem kỹ, nhưng AI có thể sai.

Sửa prompt

1. Sửa .claude/ci-review-prompt.md (cần core team duyệt). Quy tắc của repo thì sửa CLAUDE.md thay vì chép vào prompt — prompt chỉ nói cách review.

2. Thử trên một nhánh có thay đổi thật trước khi merge:

   git diff origin/main...HEAD > mr.diff
   printf 'Mô tả MR để thử' > mr-description.md
   claude -p "$(cat .claude/ci-review-prompt.md)" --model claude-sonnet-5 --allowedTools "Read,Grep,Glob" --max-turns 30
   rm mr.diff mr-description.md

3. So kết quả với vài MR đã biết có lỗi: prompt mới vẫn bắt được, và không bịa vấn đề ở MR sạch.

Prompt library và eval

Prompt dùng chung của sản phẩm nằm ở packages/ai/src/prompts/library.ts, định nghĩa bằng definePrompt có version.

Đổi nội dung một prompt:

1. Tăng version.

2. Thêm hoặc sửa case trong packages/ai/evals/cases.ts — assertion tất định (contains, regex, json-valid, max-lines…), không dùng model chấm model.

3. Chạy eval với gateway thật:

   AI_GATEWAY_URL=https://ai-gateway.example.com/v1 AI_GATEWAY_KEY=… pnpm --filter @tasco/ai eval

   AI_EVAL_MODEL đổi model chạy eval (mặc định claude-haiku-4-5). Job ai-eval chạy lại trên MR đụng packages/ai/**.

4. Changeset cho @tasco/ai: đổi hành vi prompt mà app đang dùng là thay đổi nhìn thấy được, mô tả rõ.

API: @tasco/ai/prompts, @tasco/ai/eval.

Skill của Claude Code

Skill	Ở đâu	Làm gì
/new-component <Tên>	.claude/skills/new-component/SKILL.md	Tạo component, test, đăng ký, trang docs (qua /doc-component), changeset — xem Thêm component C*
/doc-component <Tên>	.claude/skills/doc-component/SKILL.md	Soạn nháp trang docs và demo từ source theo chuẩn trang component

Skill là hướng dẫn dạng markdown: quy trình đổi thì sửa SKILL.md cùng MR với trang docs tương ứng, để AI và người làm theo cùng một checklist.

Liên quan

• AI tooling cho dev — cấu hình MCP ở repo sản phẩm.
• AI trong sản phẩm — useAiChat, createAiChatProxy.
• CI/CD của core — biến cần cho job AI.