Skip to content

Commit 8faf431

Browse files
vedantavedanta
authored
Merge pull request #9 from vedanta/feature/quick-timeout
feat: add quick timeout and spinners for local commands
2 parents 70e402e + 70e247a commit 8faf431

23 files changed

Lines changed: 610 additions & 124 deletions

‎.env.example‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,8 @@ UNIFI_API_KEY=your-api-key-here
99
# Optional: API base URL (defaults to stable v1 API)
1010
# UNIFI_API_URL=https://api.ui.com/v1
1111

12-
# Optional: Request timeout in seconds (default: 30)
13-
# UNIFI_TIMEOUT=30
12+
# Optional: Request timeout in seconds (default: 15)
13+
# UNIFI_TIMEOUT=15
1414

1515

1616
# Local Controller Configuration (for ./ui local commands)
@@ -29,3 +29,11 @@ UNIFI_API_KEY=your-api-key-here
2929

3030
# SSL verification - set to false for self-signed certificates (default: false)
3131
# UNIFI_CONTROLLER_VERIFY_SSL=false
32+
33+
34+
# CLI Behavior
35+
# ============
36+
37+
# Disable spinner animations (useful for CI/CD, scripts, or logging)
38+
# Also auto-disabled when CI=true or NO_COLOR is set
39+
# UNIFI_NO_SPINNER=false

‎README.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -152,6 +152,14 @@ Commands that use the UniFi Site Manager API (`api.ui.com`).
152152

153153
Commands that connect directly to your UniFi Controller. Use `./ui local` or `./ui lo`.
154154

155+
### Timeout Options
156+
157+
```bash
158+
./ui lo health # Default 15s timeout
159+
./ui lo -q health # Quick mode (5s timeout)
160+
./ui lo --timeout 60 health # Custom timeout
161+
```
162+
155163
### Health & Monitoring
156164

157165
```bash
@@ -331,6 +339,18 @@ All commands support multiple output formats:
331339
./ui lo clients list -o json | jq -r '.[].ip'
332340
```
333341

342+
### CI/CD Usage
343+
344+
Spinners are automatically disabled when `CI=true` or `NO_COLOR` is set:
345+
346+
```bash
347+
# Disable spinner explicitly
348+
UNIFI_NO_SPINNER=1 ./ui lo health -o json
349+
350+
# In GitHub Actions (CI=true is set automatically)
351+
./ui lo clients count -o json
352+
```
353+
334354
---
335355

336356
## Installation
@@ -539,6 +559,7 @@ docker run ui-cli # Using Docker
539559
| "Controller URL not configured" | Add `UNIFI_CONTROLLER_URL` to `.env` |
540560
| "Invalid username or password" | Verify credentials work in UniFi web UI |
541561
| "SSL certificate verify failed" | Set `UNIFI_CONTROLLER_VERIFY_SSL=false` |
562+
| "Connection timeout" (local) | Use `--timeout 60` for slow connections |
542563

543564
---
544565

‎docs/changelog.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,44 @@ All notable changes to UI-CLI are documented here.
44

55
---
66

7+
## [0.3.0] - December 2, 2024
8+
9+
### Highlights
10+
11+
🤖 **Claude Desktop Integration** - Manage your UniFi network using natural language!
12+
13+
### Added
14+
15+
**MCP Server v2 (Tools Layer Architecture)**
16+
17+
- 16 AI-optimized tools for Claude Desktop integration
18+
- Natural language network management
19+
- `./ui mcp install` - One-command setup
20+
- `./ui mcp check` - Verify installation
21+
- `./ui mcp show` - View configuration
22+
23+
**Available Tools**
24+
25+
| Category | Tools |
26+
|----------|-------|
27+
| Status & Health | `network_status`, `network_health`, `internet_speed`, `run_speedtest`, `isp_performance` |
28+
| Counts & Lists | `client_count`, `device_list`, `network_list` |
29+
| Lookups | `find_client`, `find_device`, `client_status` |
30+
| Actions | `block_client`, `unblock_client`, `kick_client`, `restart_device`, `create_voucher` |
31+
32+
### Architecture
33+
34+
- Subprocess-based tools layer for consistent behavior
35+
- CLI remains single source of truth
36+
- JSON output for all action commands
37+
38+
### Documentation
39+
40+
- Claude Desktop integration guide
41+
- MCP architecture documentation
42+
43+
---
44+
745
## [0.2.0] - December 1, 2024
846

947
### Highlights

‎docs/commands/index.md‎

Lines changed: 17 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
# Command Reference
22

3-
UI-CLI provides two sets of commands:
3+
UI-CLI provides three interfaces:
44

55
- **Cloud API** - Commands via `api.ui.com` for multi-site management
66
- **Local Controller** - Direct connection to your controller for real-time operations
7+
- **Claude Desktop** - Natural language control via MCP integration
78

89
## Command Tree
910

@@ -17,7 +18,8 @@ UI-CLI provides two sets of commands:
1718
├── devices # Cloud: manage devices
1819
├── isp # Cloud: ISP metrics
1920
├── sdwan # Cloud: SD-WAN configs
20-
└── local (lo) # Local controller commands
21+
├── local (lo) # Local controller commands
22+
└── mcp # Claude Desktop integration
2123
```
2224

2325
## Quick Reference
@@ -50,6 +52,19 @@ UI-CLI provides two sets of commands:
5052
| `./ui lo stats daily` | Daily traffic stats |
5153
| `./ui lo config show` | Export running config |
5254

55+
### Claude Desktop (MCP)
56+
57+
| Tool | Description |
58+
|------|-------------|
59+
| `network_health` | Network health summary |
60+
| `client_count` | Count connected clients |
61+
| `find_client` | Find client by name |
62+
| `block_client` | Block a client |
63+
| `restart_device` | Restart a device |
64+
| `create_voucher` | Create guest WiFi code |
65+
66+
See [Claude Desktop](mcp.md) for full tool list and setup instructions.
67+
5368
## Output Formats
5469

5570
All commands support multiple output formats:

‎docs/commands/mcp.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
# Claude Desktop Integration
2+
3+
Control your UniFi network using natural language through Claude Desktop.
4+
5+
## Overview
6+
7+
UI-CLI includes an MCP (Model Context Protocol) server that enables Claude Desktop to manage your UniFi infrastructure. Ask questions like:
8+
9+
- "How many devices are connected to my network?"
10+
- "What's my network health status?"
11+
- "Block the kids iPad"
12+
- "Restart the garage access point"
13+
14+
## Architecture
15+
16+
```
17+
┌─────────────────┐
18+
│ Claude Desktop │
19+
└────────┬────────┘
20+
│ MCP Protocol (stdio)
21+
▼
22+
┌─────────────────┐
23+
│ MCP Server │ ← 16 AI-optimized tools
24+
│ (ui_mcp) │
25+
└────────┬────────┘
26+
│ subprocess
27+
▼
28+
┌─────────────────┐
29+
│ UI CLI │ ← All business logic
30+
│ (ui_cli) │
31+
└─────────────────┘
32+
```
33+
34+
## Installation
35+
36+
### Prerequisites
37+
38+
- Python 3.11+ with conda environment `ui-cli`
39+
- Claude Desktop installed
40+
- UniFi credentials configured in `.env`
41+
42+
### Setup
43+
44+
```bash
45+
# Install MCP server to Claude Desktop
46+
./ui mcp install
47+
48+
# Verify installation
49+
./ui mcp check
50+
51+
# View current config
52+
./ui mcp show
53+
```
54+
55+
After installation, restart Claude Desktop to load the new tools.
56+
57+
## Available Tools
58+
59+
### Status & Health
60+
61+
| Tool | Description | Example Prompt |
62+
|------|-------------|----------------|
63+
| `network_status` | Check API connectivity | "Is my network API working?" |
64+
| `network_health` | Site health summary | "What's my network health?" |
65+
| `internet_speed` | Last speed test result | "What's my internet speed?" |
66+
| `run_speedtest` | Run new speed test | "Run a speed test" |
67+
| `isp_performance` | ISP metrics over time | "How's my ISP been performing?" |
68+
69+
### Counts & Lists
70+
71+
| Tool | Description | Example Prompt |
72+
|------|-------------|----------------|
73+
| `client_count` | Count clients by category | "How many devices are connected?" |
74+
| `device_list` | List UniFi devices | "What UniFi devices do I have?" |
75+
| `network_list` | List networks/VLANs | "Show my networks" |
76+
77+
### Lookups
78+
79+
| Tool | Description | Example Prompt |
80+
|------|-------------|----------------|
81+
| `find_client` | Find client by name/MAC | "Find my iPhone" |
82+
| `find_device` | Find device by name/MAC/IP | "Show the living room AP" |
83+
| `client_status` | Check if client is online/blocked | "Is the TV online?" |
84+
85+
### Actions
86+
87+
| Tool | Description | Example Prompt |
88+
|------|-------------|----------------|
89+
| `block_client` | Block from network | "Block the kids iPad" |
90+
| `unblock_client` | Restore access | "Unblock the kids iPad" |
91+
| `kick_client` | Force disconnect | "Disconnect my laptop" |
92+
| `restart_device` | Reboot device | "Restart the garage AP" |
93+
| `create_voucher` | Create guest WiFi code | "Create a guest WiFi voucher" |
94+
95+
## Example Conversations
96+
97+
### Checking Network Status
98+
99+
> **You:** How many devices are connected to my network?
100+
>
101+
> **Claude:** You have 87 devices connected:
102+
> - 17 wired clients
103+
> - 70 wireless clients
104+
> - 52 on WiFi 6, 18 on WiFi 5
105+
106+
### Managing Clients
107+
108+
> **You:** Block the kids iPad
109+
>
110+
> **Claude:** I'll block that device. Looking for "kids iPad"...
111+
>
112+
> Found: Kids-iPad (MAC: aa:bb:cc:dd:ee:ff)
113+
>
114+
> Done! Kids-iPad has been blocked from the network.
115+
116+
### Device Management
117+
118+
> **You:** Restart the garage access point
119+
>
120+
> **Claude:** I'll restart that device. Looking for "garage"...
121+
>
122+
> Found: Garage-AP (U6-Lite)
123+
>
124+
> Restart initiated. The access point will be back online in about 2 minutes.
125+
126+
## Troubleshooting
127+
128+
### Tools Not Appearing
129+
130+
1. Restart Claude Desktop after running `./ui mcp install`
131+
2. Check that `.env` file exists with credentials
132+
3. Run `./ui mcp check` to verify setup
133+
134+
### "Conda environment not found"
135+
136+
Ensure the conda environment is activated when installing:
137+
138+
```bash
139+
conda activate ui-cli
140+
./ui mcp install
141+
```
142+
143+
### Timeout Errors
144+
145+
Some operations like speed tests take longer. Claude will wait up to 60 seconds for these operations.
146+
147+
### View Logs
148+
149+
Check MCP server logs in Claude Desktop:
150+
151+
- **macOS:** `~/Library/Logs/Claude/mcp*.log`
152+
153+
## Configuration
154+
155+
The installer adds this to Claude Desktop's config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
156+
157+
```json
158+
{
159+
"mcpServers": {
160+
"ui-cli": {
161+
"command": "/path/to/ui-cmd/scripts/mcp-server.sh",
162+
"args": [],
163+
"env": {
164+
"PYTHON_PATH": "/path/to/conda/envs/ui-cli/bin/python"
165+
}
166+
}
167+
}
168+
}
169+
```
170+
171+
## Security Notes
172+
173+
- Credentials are stored in `.env` file (not in Claude Desktop config)
174+
- Claude will ask for confirmation before performing destructive actions
175+
- All operations are logged
176+
177+
## Version
178+
179+
Current MCP Server version: **0.2.0** (Tools Layer Architecture)

‎docs/overrides/home.html‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -188,6 +188,16 @@ <h3>Analytics</h3>
188188
<h3>Firewall</h3>
189189
<p>Rules & port forwards</p>
190190
</div>
191+
<div class="feature">
192+
<div class="icon">🤖</div>
193+
<h3>Claude Desktop</h3>
194+
<p>AI-powered management</p>
195+
</div>
196+
<div class="feature">
197+
<div class="icon">📋</div>
198+
<h3>Guest Vouchers</h3>
199+
<p>Create WiFi codes</p>
200+
</div>
191201
<div class="install-cmd">
192202
git clone https://github.com/vedanta/ui-cli.git && cd ui-cli && pip install -e .
193203
</div>

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,7 @@ nav:
7474
- Overview: commands/index.md
7575
- Cloud API: commands/cloud.md
7676
- Local Controller: commands/local.md
77+
- Claude Desktop: commands/mcp.md
7778
- Examples: examples.md
7879
- Troubleshooting: troubleshooting.md
7980
- Changelog: changelog.md

0 commit comments

Comments
 (0)