ui-cli 1.2.1__py3-none-any.whl

ui_cli-1.2.1.dist-info/RECORD

@@ -0,0 +1,46 @@
+ui_cli/__init__.py,sha256=ElAkVLqmlJpn6L_aK_TtTFzckYBjgET0lPq-0An6xn0,999
+ui_cli/client.py,sha256=mDM56BZbDsiOGrk0gQd-whAMQTQWUstOcSMaIukI2c0,9753
+ui_cli/config.py,sha256=GKasdbPeSAobbRx6f5d89hIfod_8ycpgLR5T5gFC3Mo,3212
+ui_cli/groups.py,sha256=cb6W3pVxf9pTVmozY9yWkwJPZ5olh0djs-G8HZ277DU,18786
+ui_cli/local_client.py,sha256=IOJEOONgtrE3kmOCvp1jtqziALyOzcCrVEitRBgKQKM,33855
+ui_cli/main.py,sha256=h__Koxw2dB6ZMq5c7pDIf9142BuUgy-GXgZIjVDFGA4,1593
+ui_cli/models.py,sha256=e_RzeVDRrhKZFtH38MhtjfcwUgtgAxooWYad4rdU7iQ,5394
+ui_cli/output.py,sha256=MzsLj8LoWlK8sjaQ4qJF3VESAZaoJiE1ny0yj62YI10,7267
+ui_cli/commands/__init__.py,sha256=gQ6tnU0Rvm0-ESWFUBU-KDl5dpNOpUTG509hXOQQjwY,27
+ui_cli/commands/devices.py,sha256=vaJuln0gapuytX_sqXGk_haguOnQvYvD4ob5ct-RqBA,4689
+ui_cli/commands/groups.py,sha256=Ol4gY16uzAvyoa6Ltv4-RXUhOpDpOBVATGB4rd3jhuk,16668
+ui_cli/commands/hosts.py,sha256=mD8hq8Z7uweVJ7FeVylJONb282_YTXCVaaCEC-UyzK4,2749
+ui_cli/commands/isp.py,sha256=GCy2GdxU8tAhVjsjVQuiCBuAUPnWts2O_p6hjTUR8Q8,2524
+ui_cli/commands/mcp.py,sha256=55IQ63X-4OWAw3foTQpuhpTx36u9s3gidlQVUP52Bm8,12749
+ui_cli/commands/sdwan.py,sha256=dVR626mSKU2QFFohPZ7-Hr-8lEXPbY6UBBCC7oy9El8,4157
+ui_cli/commands/sites.py,sha256=ku-_tTJkkKTDiUntQnSk3DlMEHLKdMBOtAb-Y55EaPw,1535
+ui_cli/commands/speedtest.py,sha256=ZuE_mYvpFdq4iDhDY6hUUe9ueAdnZZtlys2ToDMP_7k,5929
+ui_cli/commands/status.py,sha256=LBnLTc5xZjoTu4u_ZOStvipQUKySaHkfSsr0GoFH-gE,13955
+ui_cli/commands/version.py,sha256=wQXH3XevQZ9ModtrUohDdHZ_mPyBiMmQ6NEyZUP288s,289
+ui_cli/commands/local/__init__.py,sha256=fow1tALkbwnA6O840hKVpw-t7vslaA6sAvc4i6TTlTA,1927
+ui_cli/commands/local/apgroups.py,sha256=K8JeU4mqI9i9VtqCwwb47W03ddwA-Y6dkiba1q_fbG8,13305
+ui_cli/commands/local/clients.py,sha256=uqHPCNbOOKIEktIJAi-yNWlN3kY6bvgb6hxa7PjyKFI,52192
+ui_cli/commands/local/config.py,sha256=_-O2YUdXcY4HzSGjESLg40Kwt9n8bjWcw7IjmOp9LbA,29259
+ui_cli/commands/local/devices.py,sha256=KObxnioTlk1Di-MMWSWyEIwNcGYJ9oXGU1ZkEXa2N3o,17075
+ui_cli/commands/local/dpi.py,sha256=ThaEACK8iaE7NJx5f6FUMOMav7j9jlmVyaTMUSFQs58,10613
+ui_cli/commands/local/events.py,sha256=lsJGUBYqOtxMQiOuPV3M8B2oxY8X6_tflTqxENudPpo,8696
+ui_cli/commands/local/firewall.py,sha256=bA3MyJFrqVQpKSj88PIEpiTbGw04IMYw3Pk_t4D_mbk,8785
+ui_cli/commands/local/health.py,sha256=Z-kJx_ZQrywnORLQfNoqYvGgTiu3bb2JmPDTKTB9qN8,6680
+ui_cli/commands/local/networks.py,sha256=Teyf7BixuFaVQ3crRUhBfoHKLyyulpMAiPeNbak1T68,14087
+ui_cli/commands/local/portfwd.py,sha256=CmZ88UEpdfwDRBAsOg_VOhLvqXYjrPFE01gLLriuTAg,4501
+ui_cli/commands/local/stats.py,sha256=6A683uz16a9-fXlad1RGvD_WiHPzZMbm2U6OmxRrMmc,7274
+ui_cli/commands/local/utils.py,sha256=-sowKlYXCIiScaOXs45EVXAwUPe7aPzpzhQm6BPHXSI,2203
+ui_cli/commands/local/vouchers.py,sha256=TuojX6q_02nnHyF2P_UYnBCpSz3RvvZ3F_3PsU0Shug,11935
+ui_cli/commands/local/wan.py,sha256=3RzeHKuemvQ-XWyW-0AfvlI4CiK6soTDeZBvG1UiMTE,9574
+ui_cli/commands/local/wlans.py,sha256=88pnv1V5kE8tN1PF3ux8jYw0L-bGje0Gkxr7WJdcXb4,7577
+ui_mcp/ARCHITECTURE.md,sha256=LWjvPn-YFppCdWN2s1cF4ayfe0WbkVGbFNLXb70thEI,7654
+ui_mcp/README.md,sha256=IE_ughPVMrabxh5zJVWkl4lfHBymKrmW4usGGpJR04M,6322
+ui_mcp/__init__.py,sha256=7nDXTY6bZDjiO2VMNNb5dMmtqJBW3ETpolCN7Z13Grc,192
+ui_mcp/__main__.py,sha256=SyBy7DcPJg7Ez1896oFy5-PehWxcMMwCPW4XYGCt_uQ,147
+ui_mcp/cli_runner.py,sha256=pZf9GtF8-N1UCRHPwwVp7nFdDw5rqKvo5FDWhENxDiY,3498
+ui_mcp/server.py,sha256=RtKjOzfs5PbTfzTaSov3Ex_rJA-VlPsBkwBphKGMNmU,13248
+ui_cli-1.2.1.dist-info/METADATA,sha256=ynwy0qVWWDYk9SrlPqrYftaPPeuQxOngRFQ5vJcWeWg,39465
+ui_cli-1.2.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+ui_cli-1.2.1.dist-info/entry_points.txt,sha256=h9ftzR21tqilO9dmjFTI_TZ9o8IdP_OdEBsNSc0AMb4,67
+ui_cli-1.2.1.dist-info/licenses/LICENSE,sha256=zjnj_JPLbOweq-uYSCSb8KympcCNzxZQS0ndAaaqEMQ,1072
+ui_cli-1.2.1.dist-info/RECORD,,

ui_cli-1.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ui_cli-1.2.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+ui = ui_cli.main:app
+ui-mcp = ui_mcp.server:main

ui_cli-1.2.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Vedanta Barooah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ui_mcp/ARCHITECTURE.md

@@ -0,0 +1,243 @@
+# MCP Server Architecture
+
+## Design Principles
+
+### 1. CLI as Source of Truth
+
+The MCP server is a **thin wrapper** around the UI CLI. All business logic, API calls, and formatting live in the CLI. This ensures:
+
+- Consistent behavior between terminal and Claude Desktop
+- Single place to fix bugs
+- Easy to test (just run the CLI)
+
+### 2. Friendly Tool Names
+
+Tools use natural names that map to user intent:
+
+| User Intent | Tool Name | CLI Command |
+|-------------|-----------|-------------|
+| "How many clients?" | `client_count` | `./ui lo clients count` |
+| "Block a device" | `block_client` | `./ui lo clients block` |
+| "Network health" | `network_health` | `./ui lo health` |
+
+### 3. Structured Responses
+
+All tools return JSON with a consistent structure:
+
+```json
+{
+  "summary": "Human-readable one-liner for Claude",
+  "data": { ... },
+  "count": 10
+}
+```
+
+This helps Claude generate natural responses without dumping raw JSON.
+
+## Component Details
+
+### FastMCP Server (`server.py`)
+
+```python
+from mcp.server.fastmcp import FastMCP
+
+server = FastMCP(
+    "ui-cli",
+    instructions="Manage UniFi network infrastructure"
+)
+
+@server.tool()
+async def network_health() -> str:
+    """Tool docstring becomes the description Claude sees."""
+    result = run_cli(["lo", "health"])
+    return format_result(result, "Health summary")
+```
+
+Key points:
+- Uses official Anthropic MCP SDK (`mcp.server.fastmcp`)
+- Tools are async but call sync subprocess
+- Returns JSON strings (FastMCP requirement)
+- Docstrings are shown to Claude as tool descriptions
+
+### CLI Runner (`cli_runner.py`)
+
+```python
+def run_cli(args: list[str], timeout: int = 30) -> dict:
+    """Execute UI CLI and return parsed JSON."""
+
+    # Use same Python as MCP server (conda env)
+    python_path = sys.executable
+    cmd = [python_path, "-m", "ui_cli.main"] + args
+
+    # Auto-add JSON output flag
+    if "-o" not in args:
+        cmd.extend(["-o", "json"])
+
+    # Auto-add -y for actions (skip confirmation)
+    if any(action in args for action in ["block", "restart"]):
+        cmd.append("-y")
+
+    result = subprocess.run(cmd, capture_output=True, ...)
+    return json.loads(result.stdout)
+```
+
+Key points:
+- Uses `sys.executable` to ensure correct conda Python
+- Auto-adds `--output json` flag
+- Auto-adds `-y` flag for action commands
+- Handles timeouts and errors gracefully
+
+### Entry Point (`__main__.py`)
+
+```python
+from ui_mcp.server import main
+
+if __name__ == "__main__":
+    main()
+```
+
+Allows running as: `python -m ui_mcp`
+
+### Wrapper Script (`scripts/mcp-server.sh`)
+
+```bash
+#!/bin/bash
+# Load .env for credentials
+source .env
+
+# Set PYTHONPATH
+export PYTHONPATH="$PROJECT_ROOT/src"
+
+# Run with specified Python
+exec "$PYTHON" -m ui_mcp "$@"
+```
+
+Claude Desktop calls this script, which:
+1. Changes to project directory
+2. Loads `.env` file (API credentials)
+3. Sets `PYTHONPATH` for imports
+4. Runs the MCP server
+
+## Data Flow
+
+### Read Operation (e.g., `client_count`)
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│   Claude    │     │  FastMCP    │     │ CLI Runner  │     │   UI CLI    │
+│   Desktop   │     │  Server     │     │             │     │             │
+└──────┬──────┘     └──────┬──────┘     └──────┬──────┘     └──────┬──────┘
+       │                   │                   │                   │
+       │ MCP: client_count │                   │                   │
+       │──────────────────>│                   │                   │
+       │                   │                   │                   │
+       │                   │ run_cli(["lo",    │                   │
+       │                   │  "clients","count"])                  │
+       │                   │──────────────────>│                   │
+       │                   │                   │                   │
+       │                   │                   │ subprocess:       │
+       │                   │                   │ python -m ui_cli  │
+       │                   │                   │ lo clients count  │
+       │                   │                   │ -o json           │
+       │                   │                   │──────────────────>│
+       │                   │                   │                   │
+       │                   │                   │   {"counts":      │
+       │                   │                   │    {"Wired":17,   │
+       │                   │                   │     "Wireless":70}│
+       │                   │                   │<──────────────────│
+       │                   │                   │                   │
+       │                   │ {"summary": "...",│                   │
+       │                   │  "counts": {...}} │                   │
+       │                   │<──────────────────│                   │
+       │                   │                   │                   │
+       │ {"summary":       │                   │                   │
+       │  "Total: 87..."}  │                   │                   │
+       │<──────────────────│                   │                   │
+       │                   │                   │                   │
+```
+
+### Write Operation (e.g., `block_client`)
+
+Same flow, but:
+1. CLI Runner adds `-y` flag to skip confirmation
+2. CLI returns `{"success": true, "action": "blocked", ...}`
+3. Summary becomes "Blocked client: iPhone"
+
+## Error Handling
+
+### CLI Errors
+
+```python
+# CLI returns non-zero exit code
+{
+    "error": True,
+    "message": "Client not found: xyz",
+    "exit_code": 1
+}
+```
+
+### Timeout Errors
+
+```python
+# Command exceeds timeout
+{
+    "error": True,
+    "message": "Command timed out after 30s"
+}
+```
+
+### API Errors
+
+```python
+# UniFi API returns error
+{
+    "error": True,
+    "message": "Authentication failed: Invalid API key"
+}
+```
+
+All errors include `"error": True` so Claude can respond appropriately.
+
+## Security Considerations
+
+### Credentials
+
+- Stored in `.env` file (not in repo)
+- Loaded by wrapper script before MCP server starts
+- Never exposed in tool responses
+
+### Action Confirmation
+
+- CLI normally prompts for confirmation on destructive actions
+- MCP server adds `-y` flag to skip prompts
+- Claude should confirm with user before calling action tools
+
+### Network Access
+
+- Local controller access via HTTPS (self-signed cert OK)
+- Cloud API access via `api.ui.com`
+- No inbound connections required
+
+## Performance
+
+### Typical Response Times
+
+| Operation | Time |
+|-----------|------|
+| `network_health` | ~500ms |
+| `client_count` | ~800ms |
+| `device_list` | ~1s |
+| `run_speedtest` | 30-60s |
+
+### Optimization
+
+- CLI caches controller connection
+- JSON output avoids table rendering overhead
+- Subprocess overhead is minimal (~50ms)
+
+## Future Improvements
+
+1. **Caching** - Cache expensive queries like device list
+2. **Streaming** - Stream progress for long operations
+3. **Batch operations** - Block/unblock multiple clients
+4. **Webhooks** - React to network events

ui_mcp/README.md

@@ -0,0 +1,235 @@
+# UI-CLI MCP Server
+
+Model Context Protocol (MCP) server for managing UniFi network infrastructure through Claude Desktop.
+
+## Overview
+
+This MCP server exposes UniFi management tools to Claude Desktop, allowing natural language interaction with your network. Ask questions like:
+
+- "How many devices are connected to my network?"
+- "What's my network health status?"
+- "Block the kids iPad"
+- "Restart the garage access point"
+
+## Architecture
+
+```mermaid
+flowchart TB
+    subgraph Claude Desktop
+        CD[Claude Desktop App]
+    end
+
+    subgraph MCP Server
+        FS[FastMCP Server<br/>server.py]
+        CR[CLI Runner<br/>cli_runner.py]
+    end
+
+    subgraph UI CLI
+        CLI[ui_cli.main]
+        LC[Local Client<br/>UniFi Controller API]
+        CC[Cloud Client<br/>UniFi Cloud API]
+    end
+
+    subgraph UniFi Infrastructure
+        UDM[UDM / Controller]
+        CLOUD[UniFi Cloud API]
+    end
+
+    CD <-->|MCP Protocol<br/>stdio| FS
+    FS --> CR
+    CR -->|subprocess<br/>python -m ui_cli.main| CLI
+    CLI --> LC
+    CLI --> CC
+    LC <-->|HTTPS| UDM
+    CC <-->|HTTPS| CLOUD
+```
+
+## How It Works
+
+1. **Claude Desktop** connects to the MCP server via stdio
+2. **FastMCP Server** (`server.py`) registers 21 tools with friendly names
+3. **CLI Runner** (`cli_runner.py`) executes `./ui` commands via subprocess
+4. **UI CLI** performs the actual API calls and returns JSON
+5. **Results** flow back through the chain to Claude
+
+### Why Subprocess?
+
+The v2 architecture uses subprocess calls instead of direct Python imports because:
+
+- **Single source of truth** - CLI handles all logic, formatting, error handling
+- **Consistent behavior** - Same output as terminal usage
+- **Easier debugging** - Test tools by running CLI directly
+- **Simpler maintenance** - Add MCP tool = call existing CLI command
+
+## Installation
+
+### Prerequisites
+
+- Python 3.11+ with conda environment `ui-cli`
+- Claude Desktop installed
+- UniFi credentials configured in `.env`
+
+### Setup
+
+```bash
+# Install MCP server to Claude Desktop
+./ui mcp install
+
+# Verify installation
+./ui mcp check
+
+# View current config
+./ui mcp show
+```
+
+### Configuration
+
+The installer adds this to Claude Desktop's config:
+
+```json
+{
+  "mcpServers": {
+    "ui-cli": {
+      "command": "/path/to/ui-cmd/scripts/mcp-server.sh",
+      "args": [],
+      "env": {
+        "PYTHON_PATH": "/path/to/conda/envs/ui-cli/bin/python"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+### Status & Health
+
+| Tool | Description | Example Prompt |
+|------|-------------|----------------|
+| `network_status` | Check API connectivity | "Is my network API working?" |
+| `network_health` | Site health summary | "What's my network health?" |
+| `internet_speed` | Last speed test result | "What's my internet speed?" |
+| `run_speedtest` | Run new speed test | "Run a speed test" |
+| `isp_performance` | ISP metrics over time | "How's my ISP been performing?" |
+
+### Counts & Lists
+
+| Tool | Description | Example Prompt |
+|------|-------------|----------------|
+| `client_count` | Count clients by category | "How many devices are connected?" |
+| `device_list` | List UniFi devices | "What UniFi devices do I have?" |
+| `network_list` | List networks/VLANs | "Show my networks" |
+
+### Lookups
+
+| Tool | Description | Example Prompt |
+|------|-------------|----------------|
+| `find_client` | Find client by name/MAC | "Find my iPhone" |
+| `find_device` | Find device by name/MAC/IP | "Show the living room AP" |
+| `client_status` | Check if client is online/blocked | "Is the TV online?" |
+
+### Actions
+
+| Tool | Description | Example Prompt |
+|------|-------------|----------------|
+| `block_client` | Block from network | "Block the kids iPad" |
+| `unblock_client` | Restore access | "Unblock the kids iPad" |
+| `kick_client` | Force disconnect | "Disconnect my laptop" |
+| `restart_device` | Reboot device | "Restart the garage AP" |
+| `create_voucher` | Create guest WiFi code | "Create a guest WiFi voucher" |
+
+### Groups
+
+| Tool | Description | Example Prompt |
+|------|-------------|----------------|
+| `list_groups` | List all client groups | "What groups do I have?" |
+| `get_group` | Get group details | "Show the kids devices group" |
+| `block_group` | Block all clients in group | "Block all kids devices" |
+| `unblock_group` | Unblock all clients in group | "Unblock the kids devices" |
+| `group_status` | Live status of group members | "Are the kids devices online?" |
+
+## File Structure
+
+```
+src/ui_mcp/
+├── __init__.py       # Package init, version
+├── __main__.py       # Entry point: python -m ui_mcp
+├── server.py         # FastMCP server + 16 tool definitions
+├── cli_runner.py     # Subprocess wrapper for CLI calls
+└── README.md         # This file
+```
+
+## Development
+
+### Testing Tools
+
+Run the test script to validate all tools:
+
+```bash
+python scripts/test-mcp-tools.py
+```
+
+### Adding a New Tool
+
+1. Add CLI command with `--json` output support
+2. Add tool function in `server.py`:
+
+```python
+@server.tool()
+async def my_new_tool(param: str) -> str:
+    """Tool description shown to Claude.
+
+    Args:
+        param: Parameter description
+    """
+    result = run_cli(["lo", "mycommand", param])
+    if "error" in result:
+        return format_result(result)
+    return format_result(result, "Human-readable summary")
+```
+
+3. Test with `python scripts/test-mcp-tools.py`
+
+### Debugging
+
+Check MCP server logs in Claude Desktop:
+- macOS: `~/Library/Logs/Claude/mcp*.log`
+
+Test CLI runner directly:
+
+```python
+from ui_mcp.cli_runner import run_cli
+result = run_cli(["lo", "health"])
+print(result)
+```
+
+## Troubleshooting
+
+### "Conda environment not found"
+
+The wrapper script couldn't find the `ui-cli` conda environment. Ensure:
+
+```bash
+conda activate ui-cli
+./ui mcp install  # Re-install with correct Python path
+```
+
+### "No output" in Claude Desktop
+
+1. Restart Claude Desktop after config changes
+2. Check that `.env` file exists with credentials
+3. Run `./ui mcp check` to verify setup
+
+### Tools timeout
+
+Increase timeout in `cli_runner.py` for slow operations:
+
+```python
+result = run_cli(["lo", "health"], timeout=60)
+```
+
+## Version History
+
+- **v0.3.0** - Tools layer architecture with quick timeout support
+- **v0.2.0** - Tools layer architecture (subprocess-based)
+- **v0.1.0** - Direct API calls (deprecated)

ui_mcp/__init__.py

@@ -0,0 +1,7 @@
+"""UI-CLI MCP Server v2.
+
+Model Context Protocol server for managing UniFi infrastructure
+through Claude Desktop. Uses a tools layer that calls the UI CLI.
+"""
+
+from ui_cli import __version__

ui_mcp/__main__.py

@@ -0,0 +1,10 @@
+"""Entry point for running the MCP server.
+
+Usage:
+    python -m ui_mcp
+"""
+
+from ui_mcp.server import main
+
+if __name__ == "__main__":
+    main()

ui_mcp/cli_runner.py

@@ -0,0 +1,112 @@
+"""CLI runner for MCP tools.
+
+Executes UI CLI commands via subprocess and returns parsed JSON output.
+"""
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+# Project root is parent of src/
+PROJECT_ROOT = Path(__file__).parent.parent.parent
+
+
+def run_cli(
+    args: list[str],
+    timeout: int = 30,
+    skip_confirmation: bool = True,
+) -> dict:
+    """Run UI CLI command and return parsed output.
+
+    Args:
+        args: Command arguments (e.g., ["lo", "health", "-o", "json"])
+        timeout: Command timeout in seconds
+        skip_confirmation: Add -y flag to skip confirmations for actions
+
+    Returns:
+        Parsed JSON output or error dict with 'error' key
+    """
+    # Use the same Python that's running the MCP server
+    # This ensures we're in the correct conda environment
+    python_path = sys.executable
+    cmd = [python_path, "-m", "ui_cli.main"] + args
+
+    # Add JSON output flag if not present
+    if "-o" not in args and "--output" not in args:
+        cmd.extend(["-o", "json"])
+
+    # Add -y for action commands to skip confirmation
+    if skip_confirmation and any(
+        action in args for action in ["block", "unblock", "kick", "restart", "create"]
+    ):
+        if "-y" not in args and "--yes" not in args:
+            cmd.append("-y")
+
+    # Set up environment with PYTHONPATH
+    env = os.environ.copy()
+    env["PYTHONPATH"] = str(PROJECT_ROOT / "src")
+
+    try:
+        result = subprocess.run(
+            cmd,
+            cwd=PROJECT_ROOT,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            env=env,
+        )
+
+        # Try to parse stdout as JSON
+        stdout = result.stdout.strip()
+        if stdout:
+            try:
+                return json.loads(stdout)
+            except json.JSONDecodeError:
+                # Not JSON, return as raw output
+                if result.returncode == 0:
+                    return {"output": stdout}
+                else:
+                    return {
+                        "error": True,
+                        "message": result.stderr.strip() or stdout,
+                        "exit_code": result.returncode,
+                    }
+
+        # No stdout, check for errors
+        if result.returncode != 0:
+            return {
+                "error": True,
+                "message": result.stderr.strip() or "Command failed with no output",
+                "exit_code": result.returncode,
+            }
+
+        return {"output": ""}
+
+    except subprocess.TimeoutExpired:
+        return {"error": True, "message": f"Command timed out after {timeout}s"}
+    except FileNotFoundError:
+        return {"error": True, "message": "CLI not found. Run from project root."}
+    except Exception as e:
+        return {"error": True, "message": str(e)}
+
+
+def format_result(data: dict | list, summary: str | None = None) -> str:
+    """Format result dict/list as JSON string for MCP response.
+
+    Args:
+        data: Result data from CLI (dict or list)
+        summary: Optional human-readable summary to prepend
+
+    Returns:
+        JSON string suitable for MCP tool response
+    """
+    if isinstance(data, list):
+        # Wrap list in dict with summary
+        output = {"summary": summary, "data": data, "count": len(data)} if summary else {"data": data, "count": len(data)}
+    elif summary and "error" not in data:
+        output = {"summary": summary, **data}
+    else:
+        output = data
+    return json.dumps(output, indent=2)