feat: add xiaozhi websocket based mcp server support

Author: atom2ueki

Dockerfile

@@ -20,9 +20,17 @@ COPY src/ ./src/
 COPY main.py .
 COPY .env* ./
 
+# Create logs directory
+RUN mkdir -p logs
+
 # Create non-root user for security
 RUN useradd -m -u 1000 mcpuser && chown -R mcpuser:mcpuser /app
 USER mcpuser
 
-# Expose stdio for MCP communication
+# Set environment variables for MCP
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONPATH=/app
+
+# Default command - supports both stdio (Claude/Cursor) and WebSocket (Xiaozhi) modes
+# Mode is controlled by ENABLE_XIAOZHI environment variable
 CMD ["python", "main.py"] 

README.md

@@ -4,6 +4,8 @@
 
 A Model Context Protocol (MCP) server for Synology NAS devices. Enables AI assistants to manage files and downloads through secure authentication and session management.
 
+**🌟 NEW: Unified server supports both Claude/Cursor (stdio) and Xiaozhi (WebSocket) simultaneously!**
+
 ## 🚀 Quick Start with Docker
 
 ### 1️⃣ Setup Environment
@@ -17,6 +19,20 @@ cp env.example .env
 ```
 
 ### 2️⃣ Configure .env File
+
+**Basic Configuration (Claude/Cursor only):**
+```bash
+# Required: Synology NAS connection
+SYNOLOGY_URL=http://192.168.1.100:5000
+SYNOLOGY_USERNAME=your_username
+SYNOLOGY_PASSWORD=your_password
+
+# Optional: Auto-login on startup
+AUTO_LOGIN=true
+VERIFY_SSL=false
+```
+
+**Extended Configuration (Both Claude/Cursor + Xiaozhi):**
 ```bash
 # Required: Synology NAS connection
 SYNOLOGY_URL=http://192.168.1.100:5000
@@ -26,27 +42,39 @@ SYNOLOGY_PASSWORD=your_password
 # Optional: Auto-login on startup
 AUTO_LOGIN=true
 VERIFY_SSL=false
+
+# Enable Xiaozhi support
+ENABLE_XIAOZHI=true
+XIAOZHI_TOKEN=your_xiaozhi_token_here
+XIAOZHI_MCP_ENDPOINT=wss://api.xiaozhi.me/mcp/
 ```
 
 ### 3️⃣ Run with Docker
+
+**One simple command supports both modes:**
+
 ```bash
-# Build and run
-docker-compose up --build
+# Claude/Cursor only mode (default if ENABLE_XIAOZHI not set)
+docker-compose up -d
+
+# Both Claude/Cursor + Xiaozhi mode (if ENABLE_XIAOZHI=true in .env)
+docker-compose up -d
 
-# Most of the case you run detached
+# Build and run
 docker-compose up -d --build
 ```
 
-### 4️⃣ Alternative: Docker Run
+### 4️⃣ Alternative: Local Python
+
 ```bash
-# Build image
-docker build -t synology-mcp-server .
+# Install dependencies
+pip install -r requirements.txt
 
-# Run container
-docker run --env-file .env synology-mcp-server
+# Run with environment control
+python main.py
 ```
 
-## 🔌 MCP Client Setup
+## 🔌 Client Setup
 
 ### 🤖 Claude Desktop
 
@@ -70,9 +98,9 @@ Add to your Claude Desktop configuration file:
 }
 ```
 
-### 🔄 Continue (VS Code Extension)
+### ↗️ Cursor
 
-Add to your Continue configuration (`.continue/config.json`):
+Add to your Cursor MCP settings:
 
 ```json
 {
@@ -89,9 +117,9 @@ Add to your Continue configuration (`.continue/config.json`):
 }
 ```
 
-### ↗️ Cursor
+### 🔄 Continue (VS Code Extension)
 
-Add to your Cursor MCP settings:
+Add to your Continue configuration (`.continue/config.json`):
 
 ```json
 {
@@ -129,7 +157,7 @@ For Codeium's MCP support:
 
 ### 🐍 Alternative: Direct Python Execution
 
-If you prefer not to use Docker, you can run the server directly:
+If you prefer not to use Docker:
 
 ```json
 {
@@ -142,21 +170,63 @@ If you prefer not to use Docker, you can run the server directly:
         "SYNOLOGY_URL": "http://192.168.1.100:5000",
         "SYNOLOGY_USERNAME": "your_username",
         "SYNOLOGY_PASSWORD": "your_password",
-        "AUTO_LOGIN": "true"
+        "AUTO_LOGIN": "true",
+        "ENABLE_XIAOZHI": "false"
       }
     }
   }
 }
 ```
 
-## 💻 Local Development Setup
+## 🌟 Xiaozhi Integration
+
+**New unified architecture supports both clients simultaneously!**
+
+### How It Works
+
+- **ENABLE_XIAOZHI=false** (default): Standard MCP server for Claude/Cursor via stdio
+- **ENABLE_XIAOZHI=true**: Multi-client bridge supporting both:
+  - 📡 **Xiaozhi**: WebSocket connection
+  - 💻 **Claude/Cursor**: stdio connection
 
+### Setup Steps
+
+1. **Add to your .env file:**
 ```bash
-# Install dependencies
-pip install -r requirements.txt
+ENABLE_XIAOZHI=true
+XIAOZHI_TOKEN=your_xiaozhi_token_here
+```
 
-# Run directly
+2. **Run normally:**
+```bash
+# Same command, different behavior based on environment
 python main.py
+# OR
+docker-compose up
+```
+
+### Key Features
+- ✅ **Zero Configuration Conflicts**: One server, multiple clients
+- ✅ **Parallel Operation**: Both clients can work simultaneously  
+- ✅ **All Tools Available**: Xiaozhi gets access to all Synology MCP tools
+- ✅ **Backward Compatible**: Existing setups work unchanged
+- ✅ **Auto-Reconnection**: Handles WebSocket connection drops
+- ✅ **Environment Controlled**: Simple boolean flag to enable/disable
+
+### Startup Messages
+
+**Claude/Cursor only mode:**
+```
+🚀 Synology MCP Server
+==============================
+📌 Claude/Cursor only mode (ENABLE_XIAOZHI=false)
+```
+
+**Both clients mode:**
+```
+🚀 Synology MCP Server with Xiaozhi Bridge
+==================================================
+🌟 Supports BOTH Xiaozhi and Claude/Cursor simultaneously!
 ```
 
 ## 🛠️ Available MCP Tools
@@ -220,6 +290,9 @@ python main.py
 | `AUTO_LOGIN` | No | `true` | Auto-login on server start |
 | `VERIFY_SSL` | No | `true` | Verify SSL certificates |
 | `DEBUG` | No | `false` | Enable debug logging |
+| `ENABLE_XIAOZHI` | No | `false` | Enable Xiaozhi WebSocket bridge |
+| `XIAOZHI_TOKEN` | Xiaozhi only | - | Authentication token for Xiaozhi |
+| `XIAOZHI_MCP_ENDPOINT` | No | `wss://api.xiaozhi.me/mcp/` | Xiaozhi WebSocket endpoint |
 
 *Required for auto-login and default operations
 
@@ -289,11 +362,38 @@ python main.py
 
 ## ✨ Features
 
+- ✅ **Unified Entry Point** - Single `main.py` supports both stdio and WebSocket clients
+- ✅ **Environment Controlled** - Switch modes via `ENABLE_XIAOZHI` environment variable
+- ✅ **Multi-Client Support** - Simultaneous Claude/Cursor + Xiaozhi access
 - ✅ **Secure Authentication** - RSA encrypted password transmission
 - ✅ **Session Management** - Persistent sessions across multiple NAS devices  
 - ✅ **Complete File Operations** - Create, delete, list, search, rename, move files with detailed metadata
 - ✅ **Directory Management** - Recursive directory operations with safety checks
 - ✅ **Download Station** - Complete torrent and download management
 - ✅ **Docker Support** - Easy containerized deployment
-- ✅ **Multi-Client Support** - Works with Claude, Continue, Cursor, Codeium and more
-- ✅ **Error Handling** - Comprehensive error reporting and recovery 
+- ✅ **Backward Compatible** - Existing configurations work unchanged
+- ✅ **Error Handling** - Comprehensive error reporting and recovery
+
+## 🏗️ Architecture
+
+### File Structure
+```
+mcp-server-synology/
+├── main.py                    # 🎯 Unified entry point
+├── src/
+│   ├── mcp_server.py         # Standard MCP server
+│   ├── multiclient_bridge.py # Multi-client bridge
+│   ├── auth/                 # Authentication modules
+│   ├── filestation/          # File operations
+│   └── downloadstation/      # Download management
+├── docker-compose.yml        # Single service, environment-controlled
+├── Dockerfile
+├── requirements.txt
+└── .env                      # Configuration
+```
+
+### Mode Selection
+- **`ENABLE_XIAOZHI=false`** → `main.py` → `mcp_server.py` (stdio only)
+- **`ENABLE_XIAOZHI=true`** → `main.py` → `multiclient_bridge.py` → `mcp_server.py` (both clients)
+
+**Perfect for any workflow - from simple Claude/Cursor usage to advanced multi-client setups!** 🚀

docker-compose.yml

@@ -1,24 +1,38 @@
-version: '3.8'
-
 services:
+  # Synology MCP Server with optional Xiaozhi support
+  # Set ENABLE_XIAOZHI=true in .env to enable both Xiaozhi and Claude/Cursor
+  # Set ENABLE_XIAOZHI=false (or omit) for Claude/Cursor only
   synology-mcp:
     build: .
     container_name: synology-mcp-server
+    command: ["python", "main.py"]
     network_mode: host  # Allow access to local network (192.168.x.x)
     environment:
-      # Override these in .env file or here
+      - ENABLE_XIAOZHI=${ENABLE_XIAOZHI:-false}
+      - XIAOZHI_TOKEN=${XIAOZHI_TOKEN}
+      - XIAOZHI_MCP_ENDPOINT=${XIAOZHI_MCP_ENDPOINT:-wss://api.xiaozhi.me/mcp/}
       - SYNOLOGY_URL=${SYNOLOGY_URL:-http://192.168.1.10:5000}
       - SYNOLOGY_USERNAME=${SYNOLOGY_USERNAME:-your_username}
       - SYNOLOGY_PASSWORD=${SYNOLOGY_PASSWORD:-your_password}
       - AUTO_LOGIN=${AUTO_LOGIN:-true}
       - DEBUG=${DEBUG:-false}
       - VERIFY_SSL=${VERIFY_SSL:-false}
+    env_file:
+      - .env
     volumes:
-      # Mount .env file if you want to use it
+      - ./logs:/app/logs
       - ./.env:/app/.env:ro
     stdin_open: true
     tty: true
-    # For MCP, we typically don't need port mapping since it uses stdio
-    # ports:
-    #   - "8000:8000"
-    restart: unless-stopped 
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "python", "-c", "import sys; sys.exit(0)"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 10s
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10m"
+        max-file: "3"

env.example

@@ -17,4 +17,11 @@ VERIFY_SSL=false  # Set to true if your NAS has valid SSL certificate
 
 # Optional: Debug settings
 DEBUG=false
-LOG_LEVEL=INFO 
+LOG_LEVEL=INFO 
+
+# Xiaozhi MCP Integration (optional)
+# Set to true to enable both Xiaozhi (WebSocket) and Claude/Cursor (stdio) support
+# Set to false or omit for Claude/Cursor only mode
+ENABLE_XIAOZHI=false
+XIAOZHI_TOKEN=your_xiaozhi_token_here
+XIAOZHI_MCP_ENDPOINT=wss://api.xiaozhi.me/mcp/