DLI Power Switch MCP Server

# DLI Power Switch MCP Server ## Overview This project implements a **Model Context Protocol (MCP)** server that allows an AI agent to control [**Digital Loggers (DLI)** Web Power Switches](https://www.digital-loggers.com/LPC9.html). The system provides tools for discovering hardware, querying outlet status, and performing power operations (On/Off/Cycle). **Crucial Constraint:** This system interacts with physical hardware. Strict safety protocols are enforced to prevent accidental power loss to critical infrastructure. ## Key Files * **`server.py`**: The main entry point. Contains the FastMCP server implementation, tool definitions, and hardware interaction logic using the [`power-switch-pro`](https://pypi.org/project/power-switch-pro/) library. * **`switches_config.json`**: The source of truth for device configuration. Defines IP addresses, authentication, outlet aliases, and safety types (`standard`, `critical`, `prohibited`). * **`requirements.txt`**: Python dependencies (`power-switch-pro`). * **`tests/`**: Unit tests for the server logic. ## Architecture & Performance This server is designed for responsiveness and safety: * **Asynchronous Core:** Built on Python's `asyncio` to handle multiple operations efficiently. * **Non-Blocking I/O:** Interactions with physical hardware (which can be slow) are offloaded to background threads, ensuring the main server loop remains responsive. * **Parallel Discovery:** The `get_inventory` tool fetches status from all configured switches concurrently, significantly reducing latency in systems with multiple devices. ## Installation Install this server from PyPI using pip: ```bash pip install dli-mcp-server ``` ### Configuring with Gemini CLI (and Antigravity) Once installed, register the server with the Gemini CLI (or Antigravity) using the `mcp add` command. This ensures the server starts automatically. ```bash gemini mcp add dli-mcp-server dli-mcp-server -e DLI_MCP_CONFIG="/path/to/your/config.json" ``` **Parameters:** * The first `dli-mcp-server` is the name you assign to this server instance. * The second `dli-mcp-server` is the command that runs the server (made available by `pip install`). * `-e DLI_MCP_CONFIG="..."`: (Optional) Sets the environment variable for the configuration file path. If omitted, it defaults to `switches_config.json` in the current directory. * `-s user` or `-s project`: (Optional) Sets the configuration scope. Defaults to `project`. ## Command-Line Usage The `server.py` script can be used directly from the command line to control the power switches. ### `inventory` Lists all switches and their outlet statuses. ```bash python server.py inventory ``` ### `power_action` Performs a power action (on, off, cycle) on a specific outlet. ```bash python server.py power_action <switch_id> <outlet_id> <action> [--confirmation YES] ``` - `switch_id`: Alias or IP address of the switch. * `outlet_id`: Index or name of the outlet. * `action`: `on`, `off`, or `cycle`. * `--confirmation`: Required for critical outlets. ### `group_power_action` Performs a power action on a group of outlets. ```bash python server.py group_power_action <group_id> <action> ``` ### `sync_config_from_hardware` Synchronizes outlet names from the hardware. ```bash python server.py sync_config_from_hardware <switch_id> ``` ### `list_outlets` Lists all outlets on a given switch. ```bash python server.py list_outlets <switch_id> ``` ### `add_switch` Adds a new DLI power switch to the configuration. If the configuration file does not exist, it will be automatically created. ```bash python server.py add_switch <ip_address> <username> <password> ``` - `ip_address`: IP address of the new switch. * `username`: Username for the new switch. * `password`: Password for the new switch. ### `remove_switch` Removes a DLI power switch from the configuration. ```bash python server.py remove_switch <switch_id> ``` - `switch_id`: Alias or IP address of the switch to remove. ### `update_outlet` Updates the definition of an outlet. ```bash python server.py update_outlet <switch_id> <outlet_id> [--name <new_name>] [--description <new_description>] [--type <new_type>] ``` - `switch_id`: Alias or IP address of the switch. * `outlet_id`: Index or name of the outlet (e.g., "Modem" or "1"). * `--name`: New name for the outlet. * `--description`: New description for the outlet. * `--type`: New type for the outlet (`standard`, `critical`, or `prohibited`). | Type | Agent Permission | Behavior | | :--- | :--- | :--- | | **`standard`** | **Full Access** | Can be turned On, Off, or Cycled immediately. | | **`critical`** | **Restricted** | "Off" or "Cycle" actions require explicit user confirmation (`confirmation="YES"`). | | **`prohibited`** | **No Access** | **NEVER** modify this outlet. The server will raise a `PermissionError`. | ## Available Tools ### 1. `get_inventory()` * **Purpose:** The "eyes" of the agent. Call this first to see what switches and outlets are available and their current state (ON/OFF). * **Returns:** A JSON object containing all switches, outlets, groups, and their descriptions. ### 2. `power_action(switch_id, outlet_id, action, confirmation="NO")` * **Purpose:** Controls a specific physical outlet. * **Inputs:** * `switch_id`: The Alias (e.g., "garage_rack") or IP. * `outlet_id`: The Name (e.g., "Modem") or Index (e.g., "1"). * `action`: "on", "off", or "cycle". * `confirmation`: Must be set to "YES" only if the user has explicitly approved a dangerous action on a `critical` outlet. ### 3. `group_power_action(target, action)` * **Purpose:** Controls a logical group of outlets (e.g., "Restart the Network Stack"). * **Behavior:** Executes sequentially. If *any* member of the group is `prohibited`, the entire operation aborts immediately. ### 4. `sync_config_from_hardware(switch_id)` * **Purpose:** Updates the `switches_config.json` file with the actual outlet names found on the device. * **Note:** This does not overwrite safety types (`critical`/`prohibited`) or descriptions. ### 5. `add_switch(ip_address, username, password)` * **Purpose:** Adds a new DLI power switch to the configuration. * **Inputs:** * `ip_address`: IP address of the new switch. * `username`: Username for the new switch. * `password`: Password for the new switch. ### 6. `remove_switch(switch_id)` * **Purpose:** Removes a DLI power switch from the configuration. * **Inputs:** * `switch_id`: Alias or IP address of the switch to remove. ### 7. `list_outlets(switch_id)` * **Purpose:** Lists all outlets and their status for a given switch. * **Inputs:** * `switch_id`: The Alias or IP address of the switch. * **Returns:** A JSON array of outlet information. ### 8. `update_outlet(switch_id, outlet_id, new_name=None, new_description=None, new_type=None)` * **Purpose:** Updates the definition of an outlet in the configuration file and writes the new name to the hardware. * **Inputs:** * `switch_id`: The Alias or IP address of the switch. * `outlet_id`: The Name or Index (e.g., "Modem" or "1"). * `new_name` (optional): The new name for the outlet. This is written to both the config file and the hardware. * `new_description` (optional): The new description for the outlet. This is only written to the config file. * `new_type` (optional): The new type for the outlet (`standard`, `critical`, or `prohibited`). This is only written to the config file. * **Returns:** A success message. ## Operational Guidelines for the Agent 1. **Always Check Inventory First:** Before assuming an outlet exists or knowing its status, run `get_inventory`. 2. **Respect "Prohibited" Outlets:** If a user asks to turn off a prohibited device (e.g., "Security DVR"), explain that you cannot do so because it is restricted in the configuration. 3. **Handle "Critical" Warnings:** If `power_action` returns a "SAFETY LOCK" message, stop and ask the user: *"This is a critical device. Are you sure you want to turn it off?"*. Only proceed if they say "Yes". 4. **Use Aliases:** Prefer using the friendly `alias` and `name` (e.g., "garage_rack", "Modem") over IP addresses and indices when communicating with the user. ## Testing The project includes a suite of unit tests to ensure the server logic is correct. The tests are located in the `tests/` directory. To run the tests, first install the testing dependencies: ```bash pip install -r tests/requirements.txt ``` Then, use the following command to run the tests: ```bash python tests/test_server.py ``` The tests are designed to run without a physical DLI power switch. They use mocking to simulate the hardware and its behavior. ### Automated Testing The project uses GitHub Actions for continuous integration. Tests are automatically executed on every push and pull request to the `main` branch. The workflow runs on: * **Operating Systems:** Windows, Linux (Ubuntu), and macOS. * **Python Versions:** 3.10, 3.11, and 3.12. This ensures cross-platform compatibility and stability across supported Python versions. ### Test Coverage To check the test coverage, you can use the `coverage` package (which is included in `tests/requirements.txt`). Run the tests with coverage and generate a report: ```bash coverage run tests/test_server.py coverage report -m ``` The project aims for a high test coverage to ensure reliability. ### Configuring with Gemini CLI (and Antigravity) You can easily register this MCP server with the Gemini CLI (or Antigravity) using the `mcp add` command. This ensures the server starts automatically. **Windows:** ```bash gemini mcp add dli-mcp-server python "C:\Path\To\dli-mcp-server\server.py" -e DLI_MCP_CONFIG="C:\Path\To\your\config.json" -s user ``` **Linux / macOS:** ```bash gemini mcp add dli-mcp-server python "/path/to/dli-mcp-server/server.py" -e DLI_MCP_CONFIG="/path/to/your/config.json" -s user ``` **Parameters:** * `dli-mcp-server`: The name you assign to the server. * `python "..."`: The command to start the server. Ensure you provide the full absolute path to `server.py`. * `-e DLI_MCP_CONFIG="..."`: (Optional) Sets the environment variable for the configuration file path. If omitted, it defaults to `switches_config.json` in the server's directory. * `-s user`: Saves the configuration to your user settings (global), making it available across all projects. * `-s project` (Default): Saves the configuration to the current project's `.gemini/settings.json`. Use this if you want the server configuration to be specific to the current workspace. ### Configuration By default, the server uses the `switches_config.json` file in the same directory. You can override this by setting the `DLI_MCP_CONFIG` environment variable to the path of your configuration file. **Example:** ```bash export DLI_MCP_CONFIG=/path/to/your/custom_config.json python server.py inventory ``` This is particularly useful for testing with different configurations without modifying the main `switches_config.json` file. ## Example Interactions **User:** "Turn off the Router." **Agent Action:** 1. Calls `get_inventory` (internal) -> sees Router is `critical`. 2. Calls `power_action("garage_rack", "Router", "off")`. 3. **Result:** Returns "SAFETY LOCK...". 4. **Agent Response:** "The Router is marked as a critical device. Are you sure you want to turn it off?" **User:** "Yes, do it." **Agent Action:** 1. Calls `power_action("garage_rack", "Router", "off", confirmation="YES")`. 2. **Result:** "Success..." 3. **Agent Response:** "The Router has been turned off." ## Development Information This MCP server was developed using Gemini CLI and Gemini 3.0 models.