# 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

```bash
cd neko-mcp
npm install
npm run build
```

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

```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ì.