🚀 ClickAI MCP Filesystem Gateway & Local Agent

Production-ready Model Context Protocol (MCP) Filesystem Gateway & Cross-Platform Client for ClickAI, enabling ClickAI Cloud AI Agents to interact safely with users' local filesystems over encrypted WebSocket Reverse RPC tunnels.

🌟 Key Capabilities

• ⚡ 1-Click Multi-Platform Auto Setup: Users paste a single command on macOS, Linux, or Windows; the system auto-configures daemon services (launchd, systemd, or Task Scheduler).
• 🛰️ WebSocket Reverse RPC Tunnel: Seamlessly bridges Cloud Agents with local machines behind NAT, firewalls, and routers without port forwarding or dynamic DNS.
• 🔒 Multi-Layer Security Sandbox:
  • Realpath resolution (fs.realpath) prevents Directory Traversal & Symlink Escape attacks.
  • Constant-time string comparison (crypto.timingSafeEqual) eliminates Timing Attacks.
  • Whitelist-restricted root folders (default: ~/Desktop, ~/Downloads).
• 📦 Distributed & Resilient Architecture:
  • Redis-backed distributed sessions with automatic TTL expiry and transparent in-memory fallback.
  • Multi-stage Docker container with non-root security execution.
  • Kubernetes manifests with HPA, readiness/liveness probes (/healthz, /readyz), and structured Pino logging.
• 📂 11 Filesystem MCP Tools: read_file, read_multiple_files, write_file, edit_file, list_directory, search_files, create_directory, move_file, delete_file, get_file_info, list_allowed_directories.

📐 Production Architecture

┌─────────────────────────────────────────────────────────────┐
│                    ClickAI Cloud Platform                   │
│                                                             │
│  ┌───────────────────────┐        ┌──────────────────────┐  │
│  │   ClickAI Studio UI   │        │  ClickAI Core Agent  │  │
│  │   (Web Dashboard)     │        │  (Dify v2 / AI API)  │  │
│  └───────────┬───────────┘        └──────────┬───────────┘  │
│              │ HTTP                          │ JSON-RPC     │
│              ▼                               ▼              │
│  ┌───────────────────────────────────────────────────────┐  │
│  │      ClickAI MCP Gateway & Cloud Bridge Server        │  │
│  │      (Node.js / Express / ws / ioredis)               │  │
│  │                                                       │  │
│  │  - /api/mcp/session (Issue token & expire)            │  │
│  │  - /api/mcp/install-script (Universal installer)      │  │
│  │  - /api/mcp/rpc (Agent tool dispatch)                 │  │
│  │  - /ws/bridge (WebSocket Reverse RPC Tunnel Pool)     │  │
│  │  - Redis Session Cache (Cluster-ready)                │  │
│  └───────────────────────────▲───────────────────────────┘  │
└──────────────────────────────┼──────────────────────────────┘
                               │
                       WSS Encrypted Tunnel
                     (Outbound from Client)
                               │
┌──────────────────────────────┴──────────────────────────────┐
│                  Local Client Machine (User PC)             │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │   ClickAI MCP Filesystem Agent & Server (Port 3100)   │  │
│  │                                                       │  │
│  │   1. WebSocket Bridge Client (Dispatches Cloud RPC)   │  │
│  │   2. Local MCP Server (SSE & StdIO Transport)         │  │
│  │   3. Security Sandbox (realpath, boundary checks)     │  │
│  │   4. 11 Filesystem Tools (Read, Write, Edit, Search)  │  │
│  │   5. Auto-start Daemon (macOS / Linux / Windows)      │  │
│  └───────────────────────────────────────────────────────┘  │
│                              │                              │
│              📁 Sandbox: ~/Desktop, ~/Downloads             │
└─────────────────────────────────────────────────────────────┘

🚀 Quickstart Guide

1. Run Cloud Gateway Locally

npm install
npm start

• Web Studio Dashboard: http://localhost:4000
• MCP API Base: http://localhost:4000/api/mcp
• Health Probes: http://localhost:4000/healthz (liveness), http://localhost:4000/readyz (readiness)

2. Connect Local Machine via CLI

# Direct execution via CLI
npx clickai-mcp-filesystem --token=usr_tok_xxxx --url=http://localhost:4000

3. Connect via 1-Click Installers

macOS / Linux:

curl -fsSL http://localhost:4000/api/mcp/install-script?token=usr_tok_xxxx | bash

Windows (PowerShell):

irm http://localhost:4000/scripts/install.ps1 | iex

🧪 Automated Testing

Run the full Vitest suite (29 tests across security sandbox, bridge RPC roundtrips, session lifecycle, and tools):

npm test

🖥️ ClickAI Desktop Agent (GUI & System Tray)

Dành cho người dùng phổ thông không cần cài đặt Node.js hay gõ dòng lệnh:

Tính năng Desktop App

• Tray Icon & Background Service: Ứng dụng chạy ngầm ở góc màn hình, tự khởi động cùng hệ điều hành.
• 🚀 1-Click Connect: Tự động mở trình duyệt xác thực OAuth, nhận Token qua Deep Link clickai-mcp:// hoặc HTTP Loopback 127.0.0.1:45678.
• 📁 Quản lý Thư mục An toàn: Thêm/xóa thư mục cấp quyền cho AI bằng File Dialog chuẩn của hệ điều hành.
• 📜 Live Activity Log: Theo dõi trực tiếp các thao tác đọc/ghi file của AI Agent theo thời gian thực.

Chạy và Đóng gói Desktop App

# Chạy ở môi trường Development
npm run desktop:dev

# Đóng gói file cài đặt cho từng nền tảng (electron-builder)
npm run desktop:package:win    # Xuất ra file .exe (NSIS Installer & Portable)
npm run desktop:package:mac    # Xuất ra file .dmg / .zip
npm run desktop:package:linux  # Xuất ra file .AppImage / .deb

☸️ Kubernetes Deployment

Manifests are located in k8s/:

# Apply ConfigMap & Secret
kubectl apply -f k8s/configmap.yaml -n prod
kubectl apply -f k8s/secret.yaml.template -n prod

# Apply Deployment, Service & HPA
kubectl apply -f k8s/deployment.yaml -n prod
kubectl apply -f k8s/service.yaml -n prod
kubectl apply -f k8s/hpa.yaml -n prod

Environment Variables

| Variable | Default | Description | | :--- | :--- | :--- | | PORT | 4000 | Gateway HTTP/WS listen port | | REDIS_URL | "" | Redis connection URL for distributed state | | MCP_CALLBACK_BASE_URL | http://localhost:4000 | Base callback URL | | SESSION_TTL_SECONDS | 86400 | Connected session TTL (24h) | | TOKEN_TTL_SECONDS | 900 | Pending session token TTL (15m) | | LOG_LEVEL | info | Pino log level (debug, info, warn, error) |

🛡️ Security Guarantees

1. Path Boundary Strictness: Access outside designated ALLOWED_DIRS is blocked.
2. Symlink Resolution: Paths are resolved to their canonical disk targets (fs.realpath) before authorization.
3. Constant-Time Verification: Headers are checked via crypto.timingSafeEqual.
4. Least Privilege Container: Docker runs with non-root user clickai (UID 1001), drop ALL capabilities, read-only root where possible.

📄 License

MIT © ClickAI Engineering