neko-mcp

MCP Server để AI agent điều khiển neko virtual browser, trong khi bạn xem live qua WebRTC stream.

Cách dùng

1. Cài đặt

cd neko-mcp
npm install
npm run build

2. Cấu hình trong Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "neko": {
      "command": "node",
      "args": ["/đường/dẫn/đến/neko-mcp/dist/index.js"],
      "env": {
        "NEKO_URL": "http://113.173.35.45:8080",
        "NEKO_USERNAME": "neko",
        "NEKO_PASSWORD": "admin"
      }
    }
  }
}

Hoặc dùng biến môi trường mặc định (đã set sẵn cho server của bạn).

3. Quy trình dùng với AI Agent

Thứ tự khuyến nghị khi bắt đầu một task:

1. connect_websocket   → Kết nối WebSocket
2. take_control        → Lấy quyền điều khiển
3. screenshot          → Xem màn hình hiện tại
4. navigate_url        → Vào URL cần thiết
5. screenshot          → Xem kết quả
6. mouse_click / type_text / key_press  → Tương tác
7. screenshot          → Xem kết quả
...

Tools

Tool	Mô tả
screenshot	Chụp màn hình → trả về base64 JPEG
navigate_url	Điều hướng đến URL (dùng Ctrl+L)
mouse_click	Click tại (x, y)
mouse_move	Di chuột đến (x, y)
mouse_scroll	Cuộn trang tại (x, y)
type_text	Gõ text (dùng clipboard trick)
key_press	Nhấn tổ hợp phím
get_clipboard	Lấy nội dung clipboard
set_clipboard	Đặt nội dung clipboard
get_screen_info	Lấy độ phân giải màn hình
take_control	Lấy quyền điều khiển
release_control	Nhả quyền điều khiển
connect_websocket	Kết nối WebSocket

Phím đặc biệt cho key_press

ctrl, shift, alt, super
Return (Enter), Escape, Tab, BackSpace, Delete
Left, Right, Up, Down
Home, End, Page_Up, Page_Down
F1 - F12
space
a-z, 0-9, ký tự bình thường

Ví dụ tổ hợp phím:

• Ctrl+C: ["ctrl", "c"]
• Ctrl+L (focus address bar): ["ctrl", "l"]
• Ctrl+Shift+T (mở tab mới): ["ctrl", "shift", "t"]

Kiến trúc

Claude/AI Agent
      │ MCP tools
      ▼
 neko-mcp server
   ├── REST API  → /api/login, /api/room/screen/shot.jpg,
   │               /api/room/clipboard, /api/room/control/take
   └── WebSocket → /api/ws  (mouse, keyboard, scroll events)
      
                        ▼ neko server renders
                  Bạn xem qua browser (WebRTC)

Ghi chú

• WebSocket format: MCP dùng v3 API format (/api/ws). Nếu server dùng legacy mode, có thể cần adjust message format.
• type_text dùng clipboard trick: set text qua REST API rồi paste Ctrl+V — đảm bảo Unicode hoạt động tốt.
• Screenshot trả về base64 JPEG — AI agent (Claude) có thể đọc ảnh này để hiểu màn hình đang hiển thị gì.