dp100-mcp

# DP100 MCP Server This repository contains a local stdio MCP server for the ALIENTEK / 正点原子 DP100 digital power supply. It exposes DP100 status and output-control operations as MCP tools so an AI agent can safely read telemetry and control bench power during hardware bring-up. This README is written primarily for AI agents. Follow it as the source of truth when installing this MCP server on a Linux host. ## What this MCP does The server talks to the DP100 over USB HID and registers the following MCP tools: | Tool | Purpose | |---|---| | `dp100_get_device_info` | Read DP100 model, hardware/app/bootloader versions, serial metadata. | | `dp100_get_status` | Read live telemetry: input voltage, output voltage/current, temperature, output state. | | `dp100_get_active_settings` | Read active preset/setpoint: voltage, current, OVP, OCP. | | `dp100_get_system_info` | Read system settings such as backlight and over-temperature threshold. | | `dp100_set_output` | Set output enable state plus voltage/current/OVP/OCP in mV/mA. | | `dp100_output_on` | Convenience tool: enable output with explicit target voltage/current. | | `dp100_output_off` | Convenience tool: disable output while preserving the current setpoint. | Safety behavior in the server: - Uses a process-wide lock so concurrent MCP calls do not interleave HID transactions. - Rejects negative voltage/current/protection values. - Reads the device-reported max output voltage before applying a setpoint and rejects requests above that limit. - `dp100_output_off` turns output off without changing to an arbitrary high setpoint. ## Supported environment Known working environment: - Linux host - Python 3.10+ - DP100 connected over USB HID - USB VID/PID: `2e3c:af01` - Python dependencies: - `mcp` - `hidapi` - `crcmod` The device may appear as `/dev/hidrawN`. Do not hard-code `/dev/hidraw4`; the number can change across machines and reconnects. The server opens the device by VID/PID. ## Install from GitHub Use these commands on the machine that has the DP100 physically connected: ```bash cd ~/dev git clone https://github.com/lymzzyh/dp100-mcp.git cd dp100-mcp python3 -m venv .venv . .venv/bin/activate pip install -r requirements.txt ``` If `pip install hidapi` fails, install the system HID/libusb development packages first, then retry: ```bash sudo apt-get update sudo apt-get install -y python3-venv python3-dev build-essential pkg-config libhidapi-dev libusb-1.0-0-dev . .venv/bin/activate pip install -r requirements.txt ``` ## Linux USB permission setup If the AI agent is not running as root, install a udev rule so the agent user can open the DP100 HID device. Create `/etc/udev/rules.d/99-atk-dp100.rules`: ```bash sudo tee /etc/udev/rules.d/99-atk-dp100.rules >/dev/null <<'EOF' SUBSYSTEM=="hidraw", ATTRS{idVendor}=="2e3c", ATTRS{idProduct}=="af01", MODE="0660", GROUP="plugdev", TAG+="uaccess" EOF sudo udevadm control --reload-rules sudo udevadm trigger sudo usermod -aG plugdev "$USER" ``` Then unplug/replug the DP100. If the user was just added to `plugdev`, log out and log back in, or restart the agent service/session. Verify the device exists: ```bash lsusb | grep -i '2e3c:af01' || true ls -l /dev/hidraw* ``` ## Configure an AI agent MCP client This server uses stdio transport. Configure the MCP client to run the repository-local Python interpreter and `dp100_mcp.py`. ### Hermes Agent example Add this to `~/.hermes/config.yaml`: ```yaml mcp_servers: dp100: command: /home/YOUR_USER/dev/dp100-mcp/.venv/bin/python args: - /home/YOUR_USER/dev/dp100-mcp/dp100_mcp.py timeout: 30 connect_timeout: 15 ``` Replace `/home/YOUR_USER/dev/dp100-mcp` with the actual clone path. Restart Hermes Agent after editing the config. Hermes should then expose tools with names similar to: - `mcp_dp100_dp100_get_status` - `mcp_dp100_dp100_output_on` - `mcp_dp100_dp100_output_off` Tool prefixes vary by client. The underlying MCP tool names are the names listed in [What this MCP does](#what-this-mcp-does). ### Generic MCP stdio config shape For other MCP clients, use equivalent stdio configuration: ```json { "mcpServers": { "dp100": { "command": "/home/YOUR_USER/dev/dp100-mcp/.venv/bin/python", "args": ["/home/YOUR_USER/dev/dp100-mcp/dp100_mcp.py"] } } } ``` ## Manual verification for AI agents Before relying on the MCP tools, verify the server can start and talk to the hardware. ### 1. Syntax/import check ```bash cd ~/dev/dp100-mcp . .venv/bin/activate python -m py_compile dp100_mcp.py python - <<'PY' import dp100_mcp print('import-ok') PY ``` ### 2. List MCP tools with mcporter If Node.js is available, use `mcporter`: ```bash cd ~/dev/dp100-mcp npx -y mcporter list \ --stdio "$PWD/.venv/bin/python $PWD/dp100_mcp.py" \ --name dp100 \ --schema ``` Expected result: the listed tools should include `dp100_get_status`, `dp100_output_on`, and `dp100_output_off`. ### 3. Read status ```bash cd ~/dev/dp100-mcp npx -y mcporter call \ --stdio "$PWD/.venv/bin/python $PWD/dp100_mcp.py" \ dp100_get_status \ --output json ``` Expected result: JSON containing fields such as `vin_mv`, `vout_mv`, `iout_ma`, `output_enabled`, `vin_v`, `vout_v`, and `iout_a`. ### 4. Safe output control smoke test Only run this if a safe load or no sensitive target is connected. Example: enable 1.0 V / 0.1 A with conservative OVP/OCP, then turn off: ```bash cd ~/dev/dp100-mcp npx -y mcporter call \ --stdio "$PWD/.venv/bin/python $PWD/dp100_mcp.py" \ dp100_output_on \ voltage_mv:1000 current_ma:100 ovp_mv:5000 ocp_ma:500 \ --output json npx -y mcporter call \ --stdio "$PWD/.venv/bin/python $PWD/dp100_mcp.py" \ dp100_output_off \ --output json ``` ## Operational guidance for AI agents When using this MCP to control real hardware: 1. Always read `dp100_get_status` and `dp100_get_active_settings` before changing output. 2. Prefer `dp100_output_off` for emergency stop / power-down. 3. When enabling output, set explicit `voltage_mv`, `current_ma`, `ovp_mv`, and `ocp_ma` suitable for the attached target. 4. Use millivolts and milliamps. Do not pass volts/amps as floats. 5. Do not repeatedly toggle output in a tight loop; hardware targets may need discharge and boot timing margins. 6. If the device disappears, replug the DP100 and re-check udev permissions. 7. If multiple agents may access the same physical DP100, run only one MCP server instance or enforce external coordination. ## Troubleshooting ### `hid.HIDException` or permission denied Likely cause: the user cannot open `/dev/hidrawN`. Fix: - Install the udev rule from [Linux USB permission setup](#linux-usb-permission-setup). - Replug the DP100. - Ensure the agent process is running under a user in the `plugdev` group or a desktop session with `uaccess` permissions. ### `No such device` / device not found Check: ```bash lsusb | grep -i '2e3c:af01' ``` If not present, reconnect the DP100 USB cable and verify the cable supports data. ### MCP tools do not appear in the AI client Check: - The MCP config path is correct. - The `command` points to `.venv/bin/python` inside this repo. - The `args` path points to `dp100_mcp.py`. - The agent/client was restarted after config changes. - `python -m py_compile dp100_mcp.py` passes. ### Tool call hangs or fails intermittently The DP100 HID protocol is synchronous. Avoid concurrent calls from multiple processes. This server serializes calls within one process, but it cannot protect against another independent process opening the same HID device. ## Development notes Run basic local checks: ```bash cd ~/dev/dp100-mcp . .venv/bin/activate python -m py_compile dp100_mcp.py ``` The server entry point is: ```bash python dp100_mcp.py ``` It runs an MCP stdio server and should normally be launched by an MCP client, not by a human terminal session.