Live MCP

Cầu nối cho AI agent điều khiển trang web thuần declarative — agent hành động bằng chuột và bàn phím thật (trusted events qua CDP), không gọi JavaScript của trang.

• Đặc tả cho web developer: docs/livemcp-declarative-spec.md

• Kiến trúc hệ thống: docs/livemcp-architecture.md

• Lộ trình phát triển: docs/livemcp-roadmap.md

• Hỏi–đáp kỹ thuật với chuyên gia: docs/consult/

Trạng thái

M0 ✅ · M1 ✅ · M1.5 ✅ · M2 ✅ — toàn tuyến agent → MCP → server → WebSocket → extension → CDP → DOM đã thông; form điền được đủ loại ô bằng bàn phím thật, mọi sự kiện isTrusted: true. Hub có token pairing + chặn origin web, và mọi text từ trang tới agent đi qua đúng một cửa.

Luận điểm trung tâm đã chứng minh được: agent gọi một tool → đợi → nhận tool mới sinh ra từ DOM mới → gọi tiếp, không cần biết trước gì về chúng. Xem packages/demo-site/dynamic.html. Lưới E2E: 30 bài trên Chrome thật, ba locale.

Milestone tiếp theo và thứ tự ưu tiên: docs/livemcp-roadmap.md.

Related MCP server: WeaveTab-MCP

Chạy thử

npm install
npm run build

1. Demo site

npm run dev:site        # http://localhost:5180

2. Local Server — chọn MỘT trong hai cách, không được cả hai

⚠️ Server giữ hub WebSocket ở cổng 8787, và extension chỉ nối vào một chỗ. Chạy npm run dev:server trong lúc agent cũng tự spawn server thì tiến trình thứ hai chết vì EADDRINUSE, và ở phía agent nó hiện ra thành một lỗi MCP không giải thích gì. Đây là cái bẫy dễ sập nhất của cả quy trình.

3. Extension — chrome://extensions → bật Developer mode → Load unpacked → chọn packages/extension/dist.

Ghép token (một lần).

npm run token           # in token, KHÔNG mở cổng nào — chạy được kể cả khi agent đang giữ server

Bấm icon extension → dán token → Lưu & kết nối lại. Token lưu ở ~/.livemcp/token nên mọi tiến trình server đều dùng chung, ghép một lần là xong.

Không có token thì server từ chối kết nối, và đó là chủ ý: handshake WebSocket không bị CORS chặn, nên bất kỳ trang web nào bạn đang mở cũng nối được tới ws://127.0.0.1:8787 nếu hub không kiểm gì. Extension còn bị chặn thêm một lớp theo Origin — trang web không giả mạo được header đó.

Mở http://localhost:5180, mở DevTools Console, phải thấy:

[Live MCP] "LiveMCP Demo" — phát hiện 1 tool declarative.

Popup extension phải hiện chấm xanh "đã nối server". Nếu Console báo server TỪ CHỐI kết nối thì token chưa đúng — chạy npm run token và dán lại.

4. Đấu nối agent

claude mcp add livemcp -- node D:/vibeBoss/webmcp/LiveMCP/packages/server/dist/index.js --stdio

Nhớ tắt npm run dev:server trước bước này (xem cảnh báo ở bước 2) — agent tự spawn server riêng, hai bên không dùng chung cổng được.

Rồi yêu cầu agent: "gọi tool livemcp_list_sites" → "gọi livemcp_demo__say_hello". Nút trên trang phải thực sự bị bấm, Chrome hiện banner "đang debug", và ô kết quả ghi sự kiện thật (trusted) — đó là bằng chứng CDP hoạt động đúng.

Muốn xem vòng lặp trung tâm của chuẩn thì mở dynamic.html và bảo agent "gọi dynamicdemo__mo_danh_muc": ba tool chon_* chưa hề tồn tại trước lệnh đó, và agent nhận được tên chúng ngay trong kết quả trả về.

Banner "Live MCP is debugging this browser" là cố ý, không phải lỗi: không có cách hợp lệ nào tắt nó, và nó cho user biết agent đang điều khiển trình duyệt.

Test

npm test              # unit — logic thuần, ~2s
npm run e2e:setup     # một lần: tải Chromium cho Playwright
npm run test:e2e      # E2E trên Chrome thật, ~1.6 phút

Hai tầng, phân vai rõ:

Ranh giới giữa hai tầng không phải sở thích. jsdom trả getBoundingClientRect() toàn số 0, nên mọi test layout viết trên DOM giả sẽ xanh trong khi sản phẩm hỏng — tệ hơn không có test. Browser chính là layout engine: thuê nó, đừng giả nó.

Lưới E2E chạy agent giả nói MCP thật qua đúng đường sản phẩm (agent → MCP → server → WS → extension → CDP → DOM); Playwright chỉ dựng rạp và đọc DOM để assert, không bao giờ tự click hay gõ. Chi tiết: packages/e2e/README.md.

Cố ý không viết test cho tác vụ thuần giao diện.