# Ugreen NAS Docker MCP Server Setup

This repository contains a secure, containerized Model Context Protocol (MCP) server designed to be hosted on your **Ugreen NAS (UGOS)**.

## Security Architecture (Pre-Gateway Mitigations)

This setup is configured with several key pre-gateway security practices:
1. **Transport Layer Token Authentication**: Direct SSE access is protected with a token (`X-API-Key` header).
2. **Container Isolation (Non-Root)**: The server runs as `mcpuser` (UID/GID 1000) inside the container. Even if a tool is compromised, the attacker has no root privileges and is restricted to the container environment.
3. **Directory Sandboxing**: The `list_nas_shared_directories` tool is restricted to `/volume1/shared` inside the container. It cannot traverse to other system files or directories on your NAS.
4. **Environment-Driven Secrets**: The secret token is passed via a Docker environment variable rather than hardcoded in the codebase.

---

## Deployment on Ugreen NAS (UGOS)

### Step 1: Build the Docker Image
You can build this image locally and push it to your NAS, or build it directly on the NAS if you have SSH enabled:
```bash
docker build -t ugreen-nas-mcp:latest .
```

### Step 2: Running via Ugreen Container Manager UI
1. Open the **App Center** -> **Container Manager** (or **Docker** app) on your Ugreen NAS.
2. Go to **Image** and import/load `ugreen-nas-mcp:latest` or upload the folder and build it.
3. Create a new container with the image:
   - **Network**: Bridge (recommended, expose port `8000`).
   - **Port Settings**: Map Container Port `8000` to Host Port `8000` (or another free port like `8080`).
   - **Environment Variables**:
     - `MCP_SECRET_TOKEN`: Set a strong random password (e.g. `uGr33n-S3cur3-Mcp-2026!`).
   - **Volume/Bind Mounts**:
     - Mount the NAS shared directory you want the MCP to access (e.g. `/volume1/homes` or a specific shared folder `/volume1/Public`) to `/volume1/shared` inside the container. Set it to **Read-Only** (Recommended) for maximum security.
4. Start the container.

---

## Client Configuration

To connect your AI client (e.g., Claude Desktop, Cursor, or another MCP client) to the NAS MCP server, update your client's configuration file:

### Example: `claude_desktop_config.json`
Replace `<NAS_IP>` with the local IP address of your Ugreen NAS, and the header value with your configured `MCP_SECRET_TOKEN`.

```json
{
  "mcpServers": {
    "ugreen-nas-mcp": {
      "type": "sse",
      "url": "http://<NAS_IP>:8000/mcp/sse",
      "headers": {
        "X-API-Key": "your-configured-mcp-secret-token"
      }
    }
  }
}
```

---

## Verification & Testing
To verify the server is running and secure, run a quick curl command from your computer:

```bash
# Verify it blocks unauthorized access (Should return 401 Unauthorized)
curl -i http://<NAS_IP>:8000/mcp/sse

# Verify authorized access (Should establish connection)
curl -i -H "X-API-Key: your-configured-mcp-secret-token" http://<NAS_IP>:8000/mcp/sse
```