mcp-view

Máy chủ MCP dựng một trang web trong máy để xem kế hoạch, báo cáo và sơ đồ của trợ lý AI, thay vì đọc một khối chữ dài trong khung chat.

Nguyên tắc xuyên suốt: AI chỉ gửi con trỏ, không gửi nội dung. Mọi thứ đắt token — nội dung tệp, phần thay đổi, mã SVG, toạ độ, màu sắc — do máy chủ tự lấy hoặc tự tính. Giá trị trả về cho AI luôn chỉ là một dòng:

Đã dựng: http://127.0.0.1:7391/s/a3f9

Cài đặt

Cần Node.js ≥ 22. Không cần đăng ký npm — cài thẳng từ GitHub, hai lệnh:

npm i -g https://github.com/zivhdinfo/mcp-view/archive/refs/heads/claude/mcp-view-server-scdc2o.tar.gz

cd /duong/dan/du-an-cua-ban
mcp-view init

Bản đã dựng nằm sẵn trong kho nên cài xong là chạy được ngay, không phải chờ biên dịch.

mcp-view init làm ba việc và in ra đúng những gì nó đã ghi:

• thêm mục mcp-view vào .mcp.json của dự án, trỏ tới đường dẫn tuyệt đối của bản đã cài

• cài skill vào ~/.claude/skills/mcp-view/ để trợ lý tự biết khi nào nên gọi

• thêm .mcp-view/ vào .gitignore

Chạy lại nhiều lần cũng không sao — cái gì đã có thì nó giữ nguyên và nói rõ là đã bỏ qua.

Khởi động lại trình soạn thảo, gõ /mcp để kiểm tra ba công cụ đã kết nối chưa.

Cursor (.cursor/mcp.json) và Claude Desktop (claude_desktop_config.json) dùng cùng định dạng .mcp.json; chép khối mcpServers sang là được.

Dựng từ nguồn

git clone -b claude/mcp-view-server-scdc2o https://github.com/zivhdinfo/mcp-view
cd mcp-view
npm install
npm run build     # dựng giao diện rồi biên dịch máy chủ
node dist/index.js init

dist/ và ui/dist/ được đưa vào git có chủ đích, vì gói này cài thẳng từ GitHub. Sửa src/ hay ui/src/ thì chạy npm run build trước khi commit.

Gốc dự án

Lấy từ thư mục làm việc của tiến trình. Nếu trình soạn thảo chạy máy chủ từ chỗ khác, đặt MCP_VIEW_ROOT trỏ tới gốc dự án.

Thêm .mcp-view/ vào .gitignore của dự án — đó là chỗ máy chủ ghi phiên và ảnh chụp mốc.

Related MCP server: ToolCenter MCP

Skill

mcp-view init cài kèm một skill ở ~/.claude/skills/mcp-view/SKILL.md. Đó là thứ dạy trợ lý khi nào nên gọi, chứ không chỉ là gọi thế nào:

• sắp viết một kế hoạch nhiều bước trước khi sửa code → view_plan

• vừa làm xong một việc → view_report

• câu trả lời đúng ra là một cái hình → view_diagram

• phép thử: nếu viết ra sẽ dài quá một đoạn ngắn, hoặc phải chèn code, thì nó thuộc về trang web

Skill cũng dặn trợ lý trả lời bằng đúng dòng URL, gửi con trỏ chứ không dán nội dung, chọn anchor là chữ nó thật sự đọc thấy trong tệp, và khi bị máy chủ từ chối thì sửa đúng trường được nêu rồi gọi lại — chứ không quay về đổ chữ ra chat.

Nguồn nằm ở skill/mcp-view/SKILL.md trong kho, sửa được rồi chạy lại mcp-view init --force.

Muốn chắc hơn nữa thì thêm vào CLAUDE.md của dự án một dòng: skill nạp theo tình huống, còn CLAUDE.md thì luôn có mặt.

Dùng mcp-view thay vì viết dài trong chat: view_plan trước khi sửa code,
view_report sau khi xong. Trả lời tôi bằng đúng dòng URL công cụ trả về.

Ba công cụ

Trỏ tới code bằng anchor, không bằng số dòng

{ path: "src/core/queue.ts", anchor: "async function claim", note: "chỗ khoá việc" }

Mô hình đếm dòng rất kém và số dòng lệch ngay khi tệp bị sửa, nên máy chủ nhận một mẩu chữ có thật rồi tự đi tìm:

• khớp đúng một chỗ → tô sáng vùng đó

• khớp nhiều chỗ → chỉ chỗ đầu tiên, ghi chú "còn N chỗ khác khớp"

• không khớp → hiện cả tệp kèm cảnh báo, không bao giờ đoán vị trí

Nếu không khớp nguyên văn, máy chủ thử lại một lần nữa sau khi bỏ qua khoảng trắng thừa — vẫn là chỗ có thật, không phải phỏng đoán.

Sơ đồ

{ kind: "flow" | "architecture", nodes: [...], edges: [...] }

flow xếp dọc theo thứ tự các bước. architecture trải ngang, các nút cùng group nằm trong một khung viền nét đứt có tên nhóm.

Máy chủ chặn cứng ở 9 nút. Quá thì trả về lỗi kèm câu nhắc tách thành nhiều sơ đồ nhỏ. AI không được gửi màu, toạ độ hay mã SVG — gửi là bị từ chối kèm lời giải thích.

Khi AI gửi sai định dạng

Máy chủ trả về lỗi nói rõ sai ở trường nào và cần sửa thành gì, để mô hình tự gọi lại đúng mà không tốn thêm lượt của bạn:

'diagram.nodes' has 12 nodes, over the hard limit of 9. Split this into several
diagrams instead of shrinking the labels: one overview diagram of at most 9 boxes,
then one diagram per sub-flow. Call the tool again for each.

Mốc so sánh

Ngay khi máy chủ khởi động, nó ghi lại một ảnh chụp trạng thái dự án:

• là kho git → lưu mã commit của HEAD, cộng bản sao nội dung mọi tệp đang sửa dở

• không phải kho git → băm nội dung mọi tệp, cộng bản sao để so sánh từng dòng

Phần thay đổi hiển thị trên web luôn là so với ảnh chụp lúc mở phiên, không phải so với commit gần nhất — để bạn thấy đúng những gì AI đụng vào trong lượt này, không lẫn với những gì bạn tự sửa từ hôm qua. Có nút "đặt lại mốc" ở cột phải.

Mỗi tiến trình giữ ảnh chụp riêng theo pid, nên mở hai cửa sổ trình soạn thảo trên cùng một dự án cũng không cái nào xoá mốc của cái nào. Cổng cũng vậy: dò tìm từ 7391 trở lên, cổng đang dùng ghi vào .mcp-view/port.

Giao diện

Ba cột: danh sách phiên bên trái, nội dung ở giữa (giới hạn 880px), cây tệp đã thay đổi bên phải. Trang tự cập nhật qua SSE — mỗi lời gọi công cụ mới hiện thành một dòng trong thanh bên, đánh dấu "mới", và tab đang mở không bị nhảy đi chỗ khác.

Chọn hai phiên bằng checkbox rồi bấm "so sánh" để đặt kế hoạch cạnh báo cáo: bước nào rơi rụng, việc nào phát sinh ngoài kế hoạch.

Quy tắc màu

Màu trong giao diện này mang nghĩa, không trang trí. Chỉ ba màu được phép bão hoà, và cả ba đều nằm trong phần code:

Ngoài ba chỗ đó, toàn bộ giao diện là thang xám — nút bấm, thẻ, nhãn, trạng thái, cây tệp đều không dùng màu. Hai lớp chồng nhau và bật tắt riêng được: lớp thay đổi tô nền, lớp "AI chỉ tới" chỉ vẽ một vạch dọc ở lề trái cộng một dấu ở thanh cuộn — không tô nền, để dòng vừa sửa vừa được nhắc tới không mất lớp nào.

Ràng buộc này được kiểm tra tự động, không phải chỉ ghi trong tài liệu: npm run test:visual mở trình duyệt thật rồi đo màu, phông, cỡ chữ, độ đậm, bo góc và đổ bóng của từng phần tử.

Kiểm tra

npm test           # 47 phép thử: ba công cụ, chặn đầu vào, tìm anchor, so sánh, phiên
npm run test:visual  # 25 phép thử qua trình duyệt thật; cần: npm i --no-save playwright

Cấu trúc

src/
  mcp/       máy chủ stdio, khai báo và xử lý ba công cụ, chặn đầu vào
  web/       Hono, các tuyến đường, SSE, phục vụ tệp tĩnh
  core/      phiên, ảnh chụp, so sánh thay đổi, tìm anchor, tô màu cú pháp
  diagram/   elkjs, sinh SVG, bảng màu
ui/          React + Vite + Tailwind + shadcn/ui, dựng ra ui/dist
test/        smoke.mjs (MCP + API), visual.mjs (trình duyệt)