Initial implementation of UniFi MCP Light server

Implements Hybrid MCP Light pattern with:
- 4 specific tools: list_clients, list_devices, get_system_info, get_network_health
- Meta tools: tool_index, api_call (raw API pass-through)
- API documentation resource at unifi://api-reference
- Starlette wrapper with /health endpoint
- Write protection (UNIFI_ALLOW_WRITES env var)
- UniFi OS auto-detection (proxy vs direct paths)
- Docker multi-stage build
- Gitea CI workflow

Closes #1, #2, #3, #4, #5, #7

README.md

@@ -0,0 +1,158 @@
+# UniFi MCP Light
+
+A **Hybrid MCP Light Server** for UniFi Network Controller following the minimal-surface-area pattern with raw API pass-through.
+
+## Features
+
+- **4 Specific Tools**: Common read operations for clients, devices, system info, and health
+- **Raw API Pass-through**: Access any UniFi API endpoint via `unifi_api_call`
+- **Embedded Documentation**: API reference available as MCP Resource
+- **Write Protection**: Mutations disabled by default, enable with `UNIFI_ALLOW_WRITES=true`
+- **UniFi OS Support**: Auto-detects Cloud Gateway, UDM, and standalone controllers
+- **Health Endpoint**: `/health` for Docker health checks
+
+## Quick Start
+
+### Docker (Recommended)
+
+```bash
+docker run -d \
+  -p 8100:8000 \
+  -e UNIFI_HOST=192.168.1.1 \
+  -e UNIFI_USERNAME=admin \
+  -e UNIFI_PASSWORD=your_password \
+  gitea.ext.ben.io/b3nw/unifi-mcp-light:latest
+```
+
+### Docker Compose
+
+```bash
+cp .env.example .env
+# Edit .env with your UniFi credentials
+docker-compose up -d
+```
+
+### Python / UV
+
+```bash
+# Install UV
+curl -fsSL https://astral.sh/uv/install.sh | bash
+
+# Clone and install
+git clone gitea@git.local.ben.io:b3nw/unifi-mcp-light.git
+cd unifi-mcp-light
+uv venv && source .venv/bin/activate
+uv pip install -e .
+
+# Configure
+cp .env.example .env
+# Edit .env with your credentials
+
+# Run
+python server.py
+```
+
+## Configuration
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `UNIFI_HOST` | Controller IP/hostname | **required** |
+| `UNIFI_USERNAME` | Admin username | **required** |
+| `UNIFI_PASSWORD` | Admin password | **required** |
+| `UNIFI_PORT` | HTTPS port | `443` |
+| `UNIFI_SITE` | Site name | `default` |
+| `UNIFI_VERIFY_SSL` | Verify SSL certificate | `false` |
+| `UNIFI_ALLOW_WRITES` | Enable write operations | `false` |
+| `PORT` | Host port (docker-compose) | `8100` |
+
+## Tools
+
+### Specific Tools (4)
+
+| Tool | Description |
+|------|-------------|
+| `unifi_list_clients` | List connected network clients (phones, laptops, IoT) |
+| `unifi_list_devices` | List UniFi devices (APs, switches, gateways) |
+| `unifi_get_system_info` | Get controller version and configuration |
+| `unifi_get_network_health` | Get health status per subsystem (WAN, LAN, WLAN) |
+
+### Meta Tools
+
+| Tool | Description |
+|------|-------------|
+| `unifi_tool_index` | Get catalog of all available tools with schemas |
+| `unifi_api_call` | Raw API pass-through (the "escape hatch") |
+
+### Resources
+
+| URI | Description |
+|-----|-------------|
+| `unifi://api-reference` | Curated UniFi API documentation |
+
+## Usage Examples
+
+### List Connected Clients
+
+```
+Use the unifi_list_clients tool
+```
+
+### Raw API Call (Read)
+
+```
+Use unifi_api_call with:
+- endpoint: /api/s/default/stat/event
+- method: GET
+```
+
+### Raw API Call (Write - requires UNIFI_ALLOW_WRITES=true)
+
+```
+Use unifi_api_call with:
+- endpoint: /api/s/default/cmd/stamgr
+- method: POST
+- params: {"cmd": "block-sta", "mac": "aa:bb:cc:dd:ee:ff"}
+```
+
+## Claude Desktop Integration
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "unifi": {
+      "command": "docker",
+      "args": [
+        "run", "--rm", "-i",
+        "-e", "UNIFI_HOST=192.168.1.1",
+        "-e", "UNIFI_USERNAME=admin",
+        "-e", "UNIFI_PASSWORD=your_password",
+        "gitea.ext.ben.io/b3nw/unifi-mcp-light:latest"
+      ]
+    }
+  }
+}
+```
+
+## Security
+
+- **Write operations are disabled by default**
+- Set `UNIFI_ALLOW_WRITES=true` only when needed
+- Use read-only credentials when possible
+- Don't expose the server to the internet without authentication
+
+## Architecture
+
+This server follows the **Hybrid MCP Light** pattern:
+
+1. **Minimal Surface Area**: Only 4 specific tools for common operations
+2. **Escape Hatch**: Raw API pass-through for any other operation
+3. **Embedded Documentation**: API docs as MCP Resource
+4. **Starlette Wrapper**: Health checks for container orchestration
+
+See [IMPLEMENTATION.md](IMPLEMENTATION.md) for technical details.
+
+## License
+
+MIT