内容
# DP100 MCP 服务器
本仓库包含一个用于 ALIENTEK / 正点原子 DP100 数字电源的本地 stdio MCP 服务器。它将 DP100 状态和输出控制操作作为 MCP 工具公开，以便 AI 代理可以安全地读取遥测数据并在硬件启动期间控制台式电源。
本 README 主要为 AI 代理编写。在 Linux 主机上安装此 MCP 服务器时，请将其作为真实来源。
## MCP 服务器功能
服务器通过 USB HID 与 DP100 通信，并注册了以下 MCP 工具：
| 工具 | 用途 |
|---|---|
| `dp100_get_device_info` | 读取 DP100 型号、硬件/应用程序/引导程序版本、序列号元数据。 |
| `dp100_get_status` | 读取实时遥测数据：输入电压、输出电压/电流、温度、输出状态。 |
| `dp100_get_active_settings` | 读取活动预设/设定点：电压、电流、OVP、OCP。 |
| `dp100_get_system_info` | 读取系统设置，例如背光和过温阈值。 |
| `dp100_set_output` | 设置输出使能状态以及电压/电流/OVP/OCP（单位：mV/mA）。 |
| `dp100_output_on` | 便捷工具：启用输出并显式设置目标电压/电流。 |
| `dp100_output_off` | 便捷工具：禁用输出，同时保留当前设定点。 |
服务器的安全行为：
- 使用进程范围的锁，以防止并发 MCP 调用交织 HID 事务。
- 拒绝负电压/电流/保护值。
- 读取设备报告的最大输出电压，然后应用设定点并拒绝超过该限制的请求。
- `dp100_output_off` 关闭输出而不更改为任意高设定点。
## 支持的环境
已知的有效环境：
- Linux 主机
- Python 3.10+
- DP100 通过 USB HID 连接
- USB VID/PID：`2e3c:af01`
- Python 依赖项：
- `mcp`
- `hidapi`
- `crcmod`
设备可能显示为 `/dev/hidrawN`。请勿硬编码 `/dev/hidraw4`；该编号可能会在不同机器和重新连接时更改。服务器通过 VID/PID 打开设备。
## 从 GitHub 安装
在物理连接 DP100 的机器上使用以下命令：
```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
```
如果 `pip install hidapi` 失败，请先安装系统 HID/libusb 开发包，然后重试：
```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 权限设置
如果 AI 代理不是以 root 用户身份运行，请安装 udev 规则，以便代理用户可以打开 DP100 HID 设备。
创建 `/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"
```
然后拔出/重新插入 DP100。如果用户刚刚被添加到 `plugdev`，请注销并重新登录，或重启代理服务/会话。
验证设备是否存在：
```bash
lsusb | grep -i '2e3c:af01' || true
ls -l /dev/hidraw*
```
## 配置 AI 代理 MCP 客户端
服务器使用 stdio 传输。配置 MCP 客户端以运行仓库本地的 Python 解释器和 `dp100_mcp.py`。
### Hermes Agent 示例
将以下内容添加到 `~/.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
```
将 `/home/YOUR_USER/dev/dp100-mcp` 替换为实际的克隆路径。
在编辑配置后重启 Hermes Agent。 Hermes 应该会公开工具名称，类似于：
- `mcp_dp100_dp100_get_status`
- `mcp_dp100_dp100_output_on`
- `mcp_dp100_dp100_output_off`
工具前缀因客户端而异。底层 MCP 工具名称是 [MCP 服务器功能](#mcp-服务器功能) 中列出的名称。
### 通用 MCP stdio 配置格式
对于其他 MCP 客户端，请使用等效的 stdio 配置：
```json
{
"mcpServers": {
"dp100": {
"command": "/home/YOUR_USER/dev/dp100-mcp/.venv/bin/python",
"args": ["/home/YOUR_USER/dev/dp100-mcp/dp100_mcp.py"]
}
}
}
```
## AI 代理手动验证
在依赖 MCP 工具之前，请验证服务器可以启动并与硬件通信。
### 1. 语法/导入检查
```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. 使用 mcporter 列出 MCP 工具
如果有 Node.js，请使用 `mcporter`：
```bash
cd ~/dev/dp100-mcp
npx -y mcporter list \
--stdio "$PWD/.venv/bin/python $PWD/dp100_mcp.py" \
--name dp100 \
--schema
```
预期结果：列出的工具应包括 `dp100_get_status`、`dp100_output_on` 和 `dp100_output_off`。
### 3. 读取状态
```bash
cd ~/dev/dp100-mcp
npx -y mcporter call \
--stdio "$PWD/.venv/bin/python $PWD/dp100_mcp.py" \
dp100_get_status \
--output json
```
预期结果：JSON 包含 `vin_mv`、`vout_mv`、`iout_ma`、`output_enabled`、`vin_v`、`vout_v` 和 `iout_a` 等字段。
### 4. 安全输出控制烟雾测试
仅在连接安全负载或无敏感目标时运行此测试。示例：启用 1.0 V / 0.1 A，并具有保守的 OVP/OCP，然后关闭：
```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
```
## AI 代理操作指南
使用此 MCP 控制实际硬件时：
1. 始终在更改输出之前读取 `dp100_get_status` 和 `dp100_get_active_settings`。
2. 优先使用 `dp100_output_off` 进行紧急停止/断电。
3. 启用输出时，设置适合连接目标的显式 `voltage_mv`、`current_ma`、`ovp_mv` 和 `ocp_ma`。
4. 使用毫伏和毫安培。不要将伏特/安培作为浮点数传入。
5. 不要在紧密循环中重复切换输出；硬件目标可能需要放电和启动时间裕度。
6. 如果设备消失，请拔出 DP100 并重新检查 udev 权限。
7. 如果多个代理可以访问同一个物理 DP100，请运行一个 MCP 服务器实例或强制外部协调。
## 故障排除
### `hid.HIDException` 或权限被拒绝
可能原因：用户无法打开 `/dev/hidrawN`。
解决方法：
- 从 [Linux USB 权限设置](#linux-usb-权限设置) 安装 udev 规则。
- 重新插入 DP100。
- 确保代理进程在 `plugdev` 组的用户或具有 `uaccess` 权限的桌面会话下运行。
### `No such device` / 设备未找到
检查：
```bash
lsusb | grep -i '2e3c:af01'
```
如果不存在，请重新连接 DP100 USB 线缆并验证线缆是否支持数据。
### MCP 工具在 AI 客户端中不显示
检查：
- MCP 配置路径是否正确。
- `command` 是否指向此仓库内的 `.venv/bin/python`。
- `args` 路径是否指向 `dp100_mcp.py`。
- 配置更改后是否重启了代理/客户端。
- `python -m py_compile dp100_mcp.py` 是否通过。
### 工具调用间歇性挂起或失败
DP100 HID 协议是同步的。避免来自多个进程的并发调用。此服务器在一个进程内序列化调用，但无法保护另一个独立进程打开同一个 HID 设备。
## 开发说明
运行基本的本地检查：
```bash
cd ~/dev/dp100-mcp
. .venv/bin/activate
python -m py_compile dp100_mcp.py
```
服务器入口点是：
```bash
python dp100_mcp.py
```
它运行一个 MCP stdio 服务器，通常应由 MCP 客户端启动，而不是由人类终端会话启动。
