iux-aibuilder-mcp

HTML-TO-PIXSO-MCP-Service：一个基于 MCP（Model Context Protocol）的 WebSocket 推送服务，用于将本地 HTML 文件推送到 Pixso 等客户端。

服务架构

MCP 客户端          MCP Server (本服务)         ws-server (WebSocket)
   |                      |                            |
   |  tool call           |                            |
   |-------------------> |                            |
   |                      |--- WebSocket -----------> |  Pixso 客户端
   |                      |                            |

• MCP Server (index.mjs)：通过 STDIO 与 MCP 客户端通信，暴露 3 个工具
• WebSocket Server (scripts/ws-server.mjs)：常驻服务，监听端口（默认 9528），接收 HTML 并广播给已连接的客户端

环境准备

npm install

工具列表

1. open_push_server - 开启推送服务

前台启动 WebSocket 推送服务，监听 PORT（默认 9528，可通过环境变量 PORT 覆盖）。

• 参数：无
• 行为：阻塞到子进程退出；端口被占用则启动失败
• 适用场景：需要手动管理推送服务生命周期

2. push_html_to_pixso - 推送 HTML 到 Pixso

将本地 HTML 文件经 WebSocket 发出，供 Pixso 等客户端接收。

• 参数： | 参数名 | 类型 | 说明 | |--------|------|------| | html_path | string | UTF-8 HTML 文件的绝对路径 |

• 行为：

  • 若本机 WS 服务已在运行：直接推送，成功即返回
  • 若本机 WS 服务未运行：后台拉起服务，等待端口就绪（最多 20s）后重新推送
  • 路径校验：必须是绝对路径，否则返回错误

3. close_push_server - 关闭推送服务

向已运行的 ws-server 发送关闭指令，断开所有客户端并结束推送进程。

• 参数：无
• 行为：仅关闭已监听的服务，不会自动拉起
• 注意：若服务未在监听则调用失败

使用原则与推荐工作流

推荐方式：使用 push_html_to_pixso（自动管理）

push_html_to_pixso 内置了服务状态检测逻辑，推荐作为首选调用方式：

1. 调用 push_html_to_pixso，传入 HTML 文件的绝对路径
2. 工具内部自动检测 WS 服务是否运行：
   - 已运行 -> 直接推送
   - 未运行 -> 后台拉起服务 -> 等待就绪 -> 推送
3. 无需手动管理服务生命周期

手动管理方式：open_push_server + push_html_to_pixso + close_push_server

如需手动控制服务生命周期：

1. 调用 open_push_server 启动服务
2. （可选）等待 2 秒确保服务就绪
3. 调用 push_html_to_pixso 推送 HTML
4. 调用 close_push_server 关闭服务

基本原则

1. 先启动，后推送 - 使用 push_html_to_pixso 前，确保 WS 服务已运行（该工具会自动处理）
2. 推送前等待 - 服务启动后等待 2 秒再推送，确保端口已就绪
3. 用完即关 - 推送完成后调用 close_push_server 释放端口
4. 路径必须绝对 - html_path 参数必须为绝对路径，相对路径会返回错误
5. 服务未监听时 - close_push_server 不会自动拉起服务，调用前需确认服务状态

环境变量

| 变量 | 默认值 | 说明 | |------|--------|------| | PORT | 9528 | WebSocket 服务监听端口 | | WS_SEND_HOST | 127.0.0.1 | 推送目标主机地址 | | WS_SEND_TIMEOUT_MS | 8000 | 推送连接超时（毫秒） | | WS_SPAWN_WAIT_MS | 20000 | 后台拉起服务时的最大等待时间（毫秒） | | HEARTBEAT_INTERVAL_MS | 30000 | 心跳广播间隔（设为 0 关闭） |

MCP 客户端配置

在你的 MCP 客户端配置文件中添加：

{
  "mcpServers": {
    "iux-aibuilder-mcp": {
      "command": "node",
      "args": ["path/to/index.mjs"]
    }
  }
}

命令行调用示例

ws-server 直接调用

ws-server 支持直接从命令行调用，无需 MCP 客户端：

# 启动常驻服务（前台阻塞）
node scripts/ws-server.mjs

# 推送纯文本（若 WS 未运行则自动拉起，发完退出）
node scripts/ws-server.mjs "hello pixso"

# 推送 HTML 文件内容
node scripts/ws-server.mjs -html "C:\path\to\page.html"

# 推送超长 HTML（通过 @ 指定文件路径）
node scripts/ws-server.mjs @"C:\path\to\big.html"

# 关闭服务
node scripts/ws-server.mjs -command close

环境变量

# 指定端口
$env:PORT = "9529"
node scripts/ws-server.mjs

# 指定推送目标主机
$env:WS_SEND_HOST = "192.168.1.100"
node scripts/ws-server.mjs "hello"

MCP 工具调用示例

通过 MCP 客户端调用（以 Claude Desktop 为例）：

# 1. 推送 HTML（推荐，自动管理服务）
工具: push_html_to_pixso
参数: { "html_path": "C:/Users/me/page.html" }

# 2. 手动启动服务
工具: open_push_server
参数: {}

# 3. 手动关闭服务
工具: close_push_server
参数: {}

快速开始

# 安装依赖
npm install

# 直接运行（STDIO 模式，等待 MCP 客户端调用）
node index.mjs