海康工业相机 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

首次安装：

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

启动 MCP：

conda run -n ai python -m camera_mcp.server

真实相机冒烟测试：

conda run -n ai python scripts\hardware_smoke.py

CXP 相机真机冒烟测试：

conda run -n ai python scripts\cxp_hardware_smoke.py

MCP 客户端配置示例

{
  "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。