Sensecraft Hmi MCP

SenseCraft HMI MCP Server

一个用于 SenseCraft HMI 服务的 MCP (Model Context Protocol) 服务器，提供 AI 生图并自动添加到用户播放列表的功能。

A MCP (Model Context Protocol) server for SenseCraft HMI service, providing AI image generation and automatic addition to user playlists.

概述 | Overview

本项目实现了 MCP 协议服务器，允许 AI 助手通过 MCP 协议调用 SenseCraft HMI 服务的功能，特别是：

• 🎨 AI 图片生成: 根据提示词生成图片
• 📋 自动添加到播放列表: 将生成的图片自动添加到用户的默认播放列表
• 🔌 WebSocket 连接: 支持通过 WebSocket 连接到 MCP 服务器
• 🔄 自动重连: 具有指数退避的自动重连机制

This project implements a MCP protocol server that allows AI assistants to call SenseCraft HMI service functions through the MCP protocol, specifically:

• 🎨 AI Image Generation: Generate images based on prompts
• 📋 Auto-add to Playlist: Automatically add generated images to user's default playlist
• 🔌 WebSocket Connection: Support connecting to MCP server via WebSocket
• 🔄 Auto Reconnection: Automatic reconnection with exponential backoff

特性 | Features

• ✅ 基于 FastMCP 的简单易用接口 | Simple interface based on FastMCP
• ✅ 支持 WebSocket 和 stdio 传输 | Support WebSocket and stdio transport
• ✅ 完整的错误处理和日志记录 | Complete error handling and logging
• ✅ 自动重连机制 | Automatic reconnection mechanism
• ✅ 支持环境变量配置 | Support environment variable configuration

快速开始 | Quick Start

1. 安装依赖 | Install Dependencies

pip install -r requirements.txt

2. 配置环境变量 | Configure Environment Variables

复制示例配置文件：

cp .env.example .env

然后编辑 .env 文件，设置以下变量：

# SenseCraft HMI 服务的基础 URL
SENSECRAFT_API_BASE_URL=https://test-sensecraft-hmi-api.seeed.cc

# MCP WebSocket 端点（用于 mcp_pipe.py）
MCP_ENDPOINT=wss://api.xiaozhi.me/mcp/?token=your_token_here

SENSECRAFT_API_TOKEN=your_token_here

SENSECRAFT_MAC_ADDRES=B8:F8:62:F8:E4:64

3. 运行 MCP 服务器 | Run MCP Server

方式 1: 直接运行（stdio 模式）

export MCP_ENDPOINT=wss://api.xiaozhi.me/mcp/?token=your_token_here
python mcp_pipe.py sensecraft_mcp.py

重要提示: mcp_pipe.py 会将 sensecraft_mcp.py 的 stdio 输出连接到 WebSocket 端点，实现双向通信。

项目结构 | Project Structure

sensecraft-hmi-mcp/
├── sensecraft_mcp.py      # MCP 服务器主文件（FastMCP 实现）
├── mcp_pipe.py            # WebSocket 管道脚本（连接 stdio 到 WebSocket）
├── requirements.txt       # Python 依赖
├── README.md              # 项目文档
├── EXAMPLES.md            # 使用示例
├── CHANGELOG.md           # 更新日志
├── LICENSE                # 许可证文件
├── .env.example           # 环境变量示例
└── .gitignore             # Git 忽略文件

工具说明 | Tools

generate_image_to_playlist

根据提示词生成 AI 图片，并将生成的图片添加到用户的默认播放列表中。

参数:

• prompt (str, 必填): AI 生图的提示词
• user_id (int, 必填): 用户 ID
• device_id (int, 可选): 设备 ID，如果不提供则使用用户的第一个设备
• mac_address (str, 可选): 设备 MAC 地址
• page_name (str, 可选): 页面名称，默认使用 prompt 的前50个字符
• resolution (str, 可选): 图片分辨率，默认 "800x480"

返回:

{
    "success": True,
    "image_url": "https://...",
    "page_id": 123,
    "playlist_id": 456,
    "playlist_name": "默认播放列表",
    "message": "成功生成图片并添加到播放列表 '默认播放列表'"
}

工作原理 | How It Works

1. MCP 服务器 (sensecraft_mcp.py):

- 使用 FastMCP 框架实现 MCP 协议服务器 - 通过 stdio 与外部通信 - 内部通过 HTTP 调用 Go 服务的 MCP API (/api/v1/mcp/)

1. WebSocket 管道 (mcp_pipe.py):

- 连接到用户提供的 WebSocket MCP 端点 - 启动 sensecraft_mcp.py 作为子进程 - 在 WebSocket 和 stdio 之间建立双向通信管道 - 支持自动重连机制

1. 通信流程:

   WebSocket 端点  mcp_pipe.py  stdio  sensecraft_mcp.py  HTTP API (Go 服务)

使用示例 | Usage Examples

通过 mcp_pipe.py 连接到 WebSocket 端点

# 设置 WebSocket 端点
export MCP_ENDPOINT=wss://api.xiaozhi.me/mcp/?token=your_token_here

# 启动管道
python mcp_pipe.py sensecraft_mcp.py

在 Python 中使用

from sensecraft_mcp import mcp

# 工具已经通过装饰器注册，可以直接通过 MCP 协议调用
# Tools are already registered via decorators and can be called via MCP protocol

开发 | Development

添加新工具

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("SenseCraftHMI")

@mcp.tool()
def your_new_tool(param: str) -> dict:
    """工具描述"""
    # 实现你的逻辑
    # 可以调用 Go 服务的 API
    return {"success": True, "result": "..."}

if __name__ == "__main__":
    mcp.run(transport="stdio")

依赖 | Dependencies

• mcp>=1.8.1 - MCP 协议实现
• pydantic>=2.11.4 - 数据验证
• websockets>=11.0.3 - WebSocket 支持
• python-dotenv>=1.0.0 - 环境变量管理
• requests>=2.31.0 - HTTP 请求

故障排除 | Troubleshooting

连接问题

1. 检查 WebSocket 端点: 确保 MCP_ENDPOINT 环境变量设置正确
2. 检查网络连接: 确保能够访问 WebSocket 端点
3. 检查日志: 查看 mcp_pipe.py 的输出日志

API 调用问题

1. 检查 API 基础 URL: 确保 SENSECRAFT_API_BASE_URL 设置正确
2. 检查 API Token: 如果需要认证，确保 SENSECRAFT_API_TOKEN 设置正确
3. 查看日志: sensecraft_mcp.py 会输出详细的请求和响应日志

许可证 | License

本项目采用 MIT 许可证 - 详情请查看 LICENSE 文件。

This project is licensed under the MIT License - see the LICENSE file for details.

贡献 | Contributing

欢迎贡献代码！请随时提交 Pull Request。

Contributions are welcome! Please feel free to submit a Pull Request.

致谢 | Acknowledgments

• 感谢 MCP 协议的设计者和维护者
• 感谢 FastMCP 项目的贡献者
• 灵感来源于对可扩展 AI 能力的需求