# dp100-mcp

**Repository Path**: bbindong/dp100-mcp

## Basic Information

- **Project Name**: dp100-mcp
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-18
- **Last Updated**: 2026-09-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 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.