yms-mcp 2.0.1

YMS MCP Server - ONVIF camera control and YMS query tools for Model Context Protocol

YMS MCP Server

YMS MCP 是一个集成了 ONVIF 摄像头控制和 YMS 后端查询功能的 MCP (Model Context Protocol) 服务器。该项目为 AI 助手提供标准化的工具接口，支持摄像头控制和物流管理系统查询。

功能特性

ONVIF 摄像头控制

• 设备发现：自动扫描局域网内符合 ONVIF 标准的设备
• PTZ 控制：云台旋转、镜头变焦等操作
• 媒体流管理：获取 RTSP 视频流 URL
• 设备信息：查询设备型号、固件版本等信息
• 图像抓拍：远程抓拍并上传到 MinIO
• 焦距控制：调整摄像头焦距

YMS 后端查询

• Entry Tickets 查询：查询工作空间入场记录，支持多种过滤条件
• Appointments 查询：查询预约记录，支持分页和过滤

安装

环境要求

• Python 3.11+
• pip 或 uv 包管理器

安装依赖

使用 pip:

pip install -r requirements.txt

使用 uv:

uv pip install -e .

配置

1. 创建配置文件

复制示例配置文件：

cp .env.example .env

2. 配置 YMS 后端

编辑 src/config/config.yaml 文件，配置 YMS 后端连接信息：

yms_backend:
  url: https://yms-staging.item.com/api/yms
  login_path: /auth/yms/login-by-password
  headers:
    tenant_id: LT
    yard_id: LT_F3
    timezone: America/Los_Angeles
    token_expire_seconds: 3000

server:
  host: 0.0.0.0
  port: 8020

3. 配置环境变量

在 .env 文件中设置 YMS 认证信息：

# YMS Backend Configuration
YMS_USERNAME=your_username
YMS_PASSWORD=your_password

# MinIO Configuration (optional)
MINIO_ENDPOINT=your_minio_endpoint
MINIO_ACCESS_KEY=your_access_key
MINIO_SECRET_KEY=your_secret_key

使用

启动服务器

python main.py --host 0.0.0.0 --port 8020

服务器将在 http://0.0.0.0:8020 启动，提供 SSE 传输的 MCP 服务。

使用 MCP CLI

mcp dev main.py

MCP 客户端配置

配置 Claude Desktop

方式一：SSE 传输（推荐用于远程访问）

1. 首先启动 YMS MCP 服务器：

python main.py --host 0.0.0.0 --port 8020

2. 编辑 Claude Desktop 配置文件：

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

3. 添加以下配置：

{
  "mcpServers": {
    "yms-mcp": {
      "url": "http://localhost:8020/sse"
    }
  }
}

方式二：stdio 传输（推荐用于本地开发）

编辑 Claude Desktop 配置文件，添加以下配置：

{
  "mcpServers": {
    "yms-mcp": {
      "command": "python",
      "args": [
        "C:/Users/YourUsername/PycharmProjects/yms-mcp/main_stdio.py"
      ]
    }
  }
}

注意：

• 将路径替换为你的实际项目路径
• Windows 路径使用正斜杠 / 或双反斜杠 \\
• 确保 Python 在系统 PATH 中，或使用完整的 Python 路径

配置其他 MCP 客户端

对于其他支持 MCP 的客户端，可以使用以下连接信息：

• SSE 端点: http://localhost:8020/sse
• 消息端点: http://localhost:8020/messages/
• 传输协议: Server-Sent Events (SSE)

验证配置

1. 重启 Claude Desktop
2. 在对话中输入类似 "查询预约记录" 或 "控制摄像头" 的请求
3. Claude 应该能够调用 YMS MCP 提供的工具

可用工具

ONVIF 摄像头工具

1. handle_discover_devices - 发现网络中的 ONVIF 设备
2. handle_ptz_control - 控制摄像头 PTZ 移动
3. get_rtsp - 获取摄像头 RTSP 地址
4. get_deviceInfo - 获取摄像头设备信息
5. snap_image_to_minio - 抓拍图像并上传到 MinIO
6. focus_move - 控制摄像头焦距
7. get_camera_list - 获取摄像头列表
8. get_camera_live - 获取摄像头直播流地址

YMS 查询工具

9. search_entry_tickets - 查询工作空间入场记录

   • 支持分页 (page_num, page_size)
   • 支持多种过滤条件 (entry_id, keyword, driver_id, vehicle_id, appointment_id, tractor_no, trailer_no, container_no, load_no, entry_status, appointment_status)

10. search_appointments - 查询预约记录

    • 支持分页 (page_num, page_size)
    • 支持多种过滤条件 (appointment_id, appointment_type, carrier_id, driver_id, appointment_status, customer_id, entry_id, reference_code, keyword, load_id, receipt_id)

使用示例

查询预约记录

# 查询第1页，每页20条记录
result = await search_appointments(page_num=1, page_size=20)

# 根据预约ID查询
result = await search_appointments(appointment_id="APT-12345")

# 根据司机ID查询
result = await search_appointments(driver_id="DRV-001")

查询入场记录

# 查询第1页，每页20条记录
result = await search_entry_tickets(page_num=1, page_size=20)

# 根据车牌号查询
result = await search_entry_tickets(tractor_no="ABC123")

# 根据预约ID查询
result = await search_entry_tickets(appointment_id="APT-12345")

控制摄像头

# PTZ 控制
result = await handle_ptz_control(
    host="192.168.1.100",
    port=80,
    usr="admin",
    pwd="admin123",
    direction="Up",
    speed=50
)

# 抓拍图像
result = await snap_image_to_minio(
    host="192.168.1.100",
    port=80,
    usr="admin",
    pwd="admin123"
)

项目结构

yms-mcp/
├── src/
│   ├── config/          # 配置模块
│   │   ├── settings.py  # 配置加载器
│   │   └── config.yaml  # YAML 配置文件
│   ├── managers/        # 管理器模块
│   │   └── token.py     # YMS Token 管理器
│   ├── services/        # 服务层
│   │   └── yms_query.py # YMS 查询服务
│   └── onvif_device_manage.py  # ONVIF 设备管理
├── main.py              # 主程序入口
├── pyproject.toml       # 项目配置
└── README.md            # 项目文档

技术栈

• FastMCP - MCP 服务器框架
• Starlette - ASGI Web 框架
• ONVIF-zeep - ONVIF 协议客户端
• httpx - 异步 HTTP 客户端
• loguru - 日志记录
• pydantic-settings - 配置管理
• MinIO - 对象存储

开发

运行测试

pytest tests/

代码格式化

black src/ main.py

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！