# 海康工业相机 MCP

这是一个基于海康 MVS SDK 的 Python MCP 服务，面向本机工业相机控制。当前版本使用 `MvCameraControl`，覆盖枚举、打开、关闭、采集、保存图片、常用参数读写，并已经拆分出后端、会话、服务、GenICam 特性和长任务登记层。CXP 与第一版 XoF 采集卡相机接入复用 `MvCameraControl` 的 GenTL 能力；独立 `MVFGControl` 后端仍作为后续高级采集卡能力方向。

## 运行环境

- MVS 安装目录：`C:\Program Files (x86)\MVS`
- Python 环境：conda `ai`
- 测试相机：
  - IP：`10.22.114.138`
  - 型号：`MV-CL042-91GM`
  - 序列号：`DA6216078`
- CXP 测试设备：
  - 采集卡：`MV-GY1004`
  - 相机：`MV-CL08T5-500Y4M`
  - 相机序列号：`202606235`

首次安装：

```powershell
conda run -n ai python -m pip install -e .
```

启动 MCP：

```powershell
conda run -n ai python -m camera_mcp.server
```

真实相机冒烟测试：

```powershell
conda run -n ai python scripts\hardware_smoke.py
```

CXP 相机真机冒烟测试：

```powershell
conda run -n ai python scripts\cxp_hardware_smoke.py
```

## MCP 客户端配置示例

```json
{
  "mcpServers": {
    "hikrobot-camera": {
      "command": "conda",
      "args": ["run", "-n", "ai", "python", "-m", "camera_mcp.server"],
      "cwd": "e:\\myworkstation\\05ai\\02camera_mcp"
    }
  }
}
```

## 工具列表

- `list_cameras()`：枚举在线相机。
- `list_cameras(backend="cxp")`：枚举 CXP 采集卡下的在线相机。
- `list_cameras(backend="xof")`：枚举 XoFLink 采集卡下的在线相机。
- `list_frame_grabbers(interface_type="cxp")`：枚举 CXP 采集卡。
- `list_frame_grabbers(interface_type="xof")`：枚举 XoFLink 采集卡。
- `open_camera(index=0, ip=None, serial=None)`：打开相机，未指定时优先匹配测试相机。
- `open_camera(backend="cxp", session_id="cxp", serial=None)`：打开 CXP 采集卡下的相机，建议使用独立 `cxp` 会话。
- `open_camera(backend="xof", session_id="xof", serial=None)`：打开 XoFLink 采集卡下的相机，建议使用独立 `xof` 会话。
- `close_camera()`：关闭相机并释放句柄。
- `get_camera_status()`：查看 SDK、打开和采集状态。
- `start_grabbing()` / `stop_grabbing()`：开始或停止采集。
- `capture_image(format="jpg", timeout_ms=1000)`：采集一帧，保存到 `captures/`，返回图片路径和元数据。
- `get_parameter(name)` / `set_parameter(name, value)`：读写 `ExposureTime`、`Gain`、`AcquisitionFrameRate`、`Width`、`Height`、`PixelFormat`。
- `list_camera_sessions()`：查看当前服务内维护的相机会话。
- `get_node(name)` / `set_node(name, value)`：基于 GenICam 节点类型动态读写节点。
- `execute_command_node(name)`：执行 Command 类型节点。
- `read_memory(address, length)`：按原始地址读取设备内存，返回 `data_hex` 十六进制字节串，单次最多 1 MiB。
- `write_memory(address, data_hex)`：将十六进制字节串写入原始地址，成功后尝试清除 GenICam 节点缓存，单次最多 1 MiB。
- `describe_feature(name)`：读取节点类型、访问模式和读写能力。
- `export_genicam_xml()`：导出相机内部 GenICam XML 到 `diagnostics/genicam/`。
- `list_genicam_features()`：解析 GenICam XML 并列出能力节点。
- `start_firmware_upgrade(firmware_path, confirm=true)`：异步升级已打开相机的固件，调用前必须停止采集。
- `get_job(job_id)`：查询单个长任务的状态、进度和结果。
- `list_jobs()`：查看固件升级等长任务的状态、进度和结果。

## 固件升级

固件升级通过 MVS SDK 的 `MV_CC_LocalUpgrade` 执行，并在后台线程中持续查询升级进度，不会阻塞 MCP 主调用。建议按以下顺序调用：

1. 使用 `open_camera(...)` 打开目标相机，并核对返回的型号和序列号。
2. 如果相机正在采集，调用 `stop_grabbing(...)`。
3. 调用 `start_firmware_upgrade(firmware_path="C:\\firmware\\camera.bin", confirm=true)`，保存返回的 `job_id`。
4. 使用 `get_job(job_id)` 查询进度，直到状态变为 `succeeded` 或 `failed`。
5. 升级成功后等待相机重启，再调用 `list_cameras()` 核对版本并重新打开相机。

固件必须与相机型号和硬件版本完全匹配。升级期间不得断电、拔线或退出 MVS 驱动环境。厂商 Python 接口仅接受 ASCII 文件路径，因此固件路径不能包含中文。`timeout_seconds` 只限制固件发送完成后的进度等待阶段，无法安全中断正在执行的 SDK 固件传输。

## 架构分层

- `backends/`：SDK 后端适配层。当前实现 `MvsCameraBackend`，后续可增加 `MvFgBackend` 或其他厂商后端。
- `sessions.py`：相机会话管理。MCP 和未来 UI 都通过 `session_id` 访问相机。
- `service.py`：应用服务层，集中编排采图、节点读写、XML 导出和长任务登记。
- `features.py`：GenICam XML 解析层，用于分析相机能力节点。
- `jobs.py`：线程安全的长任务登记层，用于升级、抓包、诊断分析等耗时任务。
- `server.py`：MCP 适配层，只负责注册工具和转换响应。

## 注意事项

- MCP 响应只返回图片路径和元数据，不返回 base64 大图。
- 原始内存读写会绕过 GenICam 节点的类型、范围和访问模式检查；地址应从设备 XML 的寄存器地址定义获取，并按设备传输协议要求处理字节序。
- 当前默认使用 `default` 会话；多会话边界已建立，但还没有做多相机并发压力测试。
- 当前 CXP 和 XoF v1 通过 `MvCameraControl` 的 GenTL 设备类型接入，不包含采集卡高级缓存、驱动日志或独立 `MVFGControl` 绑定。
- 若同时使用普通 MVS、CXP 和 XoF 相机，建议分别使用 `session_id="default"`、`session_id="cxp"` 和 `session_id="xof"`。
- 如果启动时提示找不到 `MvCameraControl.dll`，请确认 MVS 运行环境已安装，且相关目录已加入系统 `PATH`。