MCP HTML Sync Server

Name: MCP HTML Sync Server
Author: yujiosaka

本地服务

github.com/yujiosaka开发工具179 周前更新

代码仓库

关于 MCP HTML Sync Server

MCP HTML Sync Server 供 AI Agent 动态创建和管理 HTML 页面，并通过 WebSocket 将变更同步到浏览器。它适合需要即时预览页面内容的开发流程。

主要功能

01创建、更新和删除 HTML 页面
02浏览器实时热重载
03添加 CDN 或内联 JavaScript
04通过 CDN 添加 CSS 样式表
05配置页面过期和数量上限

适用场景

01让 AI Agent 生成可即时查看的页面
02迭代 HTML 内容并观察浏览器更新
03向现有页面追加脚本或样式

MCP 相关

它通过 MCP 向 AI Agent 提供创建、更新、删除页面及添加脚本和样式表的工具。浏览器通过 HTTP 获取页面，并通过 WebSocket 接收实时更新。

#html #sync #server #mcp #static #hot-reload #mcp-server

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "html-sync-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "pull"
      ]
    }
  }
}

启动命令docker run -i --rm pull

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

ocipullstdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

MCP HTML Sync Server

行为准则 | 贡献指南 | 安全

基于模型上下文协议（MCP）构建的实时 HTML 同步服务，支持热重载。该服务支持 AI Agent 动态创建、更新和销毁 HTML 页面，并向所有已连接的客户端实时推送更新。

功能

实时 HTML 同步：创建和更新 HTML 内容，并立即向所有已连接的客户端推送更新
WebSocket 热重载：内容发生变化时，所有已连接的浏览器都会自动刷新
脚本管理：通过 CDN URL 或内联内容向页面添加 JavaScript 脚本
样式表管理：通过 CDN URL 向页面添加 CSS 样式表
MCP 集成：专为使用模型上下文协议的 AI Agent 设计
页面生命周期管理：页面会在可配置的时间段后自动过期
连接数限制：可配置页面数量上限，并自动清理最早创建的页面
简单的 API：通过易于使用的 MCP 工具创建、更新和销毁页面
轻量级：依赖项少，资源利用高效

架构

flowchart LR
    AI[AI Agent] -->|MCP Protocol| MCP[MCP HTML Sync Server]
    MCP -->|Create/Update/Destroy/AddScripts/AddStylesheets| PM[Page Manager]
    PM -->|Store| Pages[(HTML Pages, Scripts & Stylesheets)]
    User[User Browser] -->|HTTP Request| HTTP[HTTP Server]
    HTTP -->|Fetch Page, Scripts & Stylesheets| PM
    User <-->|WebSocket| WS[WebSocket Server]
    WS <-->|Real-time Updates| PM

安装

使用 Docker

docker pull yujiosaka/mcp-html-sync-server
docker run -p 3000:3000 yujiosaka/mcp-html-sync-server

Docker 环境变量

你可以在运行时直接向 Docker 容器传递环境变量，而不是使用 .env 文件：

docker run -p 3000:3000 \
  -e SERVER_PORT=3000 \
  -e BASE_URL=http://localhost:3000/ \
  -e PAGE_MAX_AGE=1h \
  -e PAGE_MAX_COUNT=1000 \
  yujiosaka/mcp-html-sync-server

生产环境部署推荐使用此方法，因为这样可以在不修改容器镜像的情况下配置服务。

使用 NPX

NODE_ENV=production npx mcp-html-sync-server

从源代码安装

# Clone the repository
git clone https://github.com/yujiosaka/mcp-html-sync-server.git
cd mcp-html-sync-server

# Install dependencies
bun install

# Copy the example environment file
bun run config

# Start the server
bun run start

配置

编辑 .env 文件以配置服务：

# Host address for the HTTP server (used for binding the server)
SERVER_HOST=localhost
# Port number for the HTTP server (used for binding the server)
SERVER_PORT=3000
# Base URL for the application (used for generating view URLs)
BASE_URL=http://localhost:3000/
# Maximum age of pages before they expire (e.g., 1h = 1 hour, uses ms library format)
PAGE_MAX_AGE=1h
# Maximum number of pages that can be stored (oldest pages are removed when limit is reached)
PAGE_MAX_COUNT=1000

配置选项

选项	描述	默认值	格式
SERVER_HOST	HTTP 服务的绑定主机地址	localhost	主机名
SERVER_PORT	HTTP 服务的端口号	3000	数字
BASE_URL	用于生成查看 URL 的基础 URL	http://localhost:3000/	URL
PAGE_MAX_AGE	页面过期前的最长存续时间	1h	时间字符串（例如，1h、30m、1d）
PAGE_MAX_COUNT	要保留的页面数量上限	1000	数字

在 MCP 中使用

与 Claude Desktop 集成

将以下内容添加到你的 claude_desktop_config.json 中：

Docker

{
  "mcpServers": {
    "html-sync-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-p",
        "3000:3000",
        "-e", "SERVER_PORT=3000",
        "-e", "BASE_URL=http://localhost:3000/",
        "-e", "PAGE_MAX_AGE=1h",
        "-e", "PAGE_MAX_COUNT=1000",
        "yujiosaka/mcp-html-sync-server"
      ]
    }
  }
}

NPX

{
  "mcpServers": {
    "html-sync-server": {
      "command": "npx",
      "args": ["-y", "mcp-html-sync-server"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

与 VS Code 集成

如需快速安装，请使用以下一键安装按钮之一：

手动安装

如需手动安装，请将以下 JSON 代码块添加到 VS Code 的 User Settings (JSON) 文件中。按下 Ctrl + Shift + P 并输入 Preferences: Open Settings (JSON) 即可打开该文件。

也可以将其添加到工作区中名为 .vscode/mcp.json 的文件中。这样便可以与他人共享配置。

请注意，.vscode/mcp.json 文件中不需要 mcp 键。

{
  "mcp": {
    "servers": {
      "html-sync-server": {
        "command": "npx",
        "args": ["-y", "mcp-html-sync-server"],
        "env": {
          "NODE_ENV": "production"
        }
      }
    }
  }
}

Docker 安装：

{
  "mcp": {
    "servers": {
      "html-sync-server": {
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-p", "3000:3000",
          "-e", "SERVER_PORT=3000",
          "-e", "BASE_URL=http://localhost:3000/",
          "-e", "PAGE_MAX_AGE=1h",
          "-e", "PAGE_MAX_COUNT=1000",
          "yujiosaka/mcp-html-sync-server"
        ]
      }
    }
  }
}

MCP 工具

该服务提供以下 MCP 工具，供 AI Agent 使用：

1. 创建页面

使用指定内容创建新的 HTML 页面。

工具名称：create_page

输入架构：

{
  "type": "object",
  "properties": {
    "body": {
      "type": "string",
      "description": "HTML content for the page body (only the inner content)"
    },
    "scripts": {
      "type": "array",
      "description": "Optional array of JavaScript scripts to include in the page",
      "items": {
        "type": "object",
        "properties": {
          "src": {
            "type": "string",
            "description": "URL for external script"
          },
          "content": {
            "type": "string",
            "description": "Content for inline script"
          }
        },
        "description": "Either src or content must be provided",
        "oneOf": [
          { "required": ["src"] },
          { "required": ["content"] }
        ]
      }
    },
    "stylesheets": {
      "type": "array",
      "description": "Optional array of CSS stylesheets to include in the page",
      "items": {
        "type": "object",
        "properties": {
          "href": {
            "type": "string",
            "description": "URL for external stylesheet"
          }
        },
        "required": ["href"]
      }
    }
  },
  "required": ["body"]
}

请求示例：

{
  "name": "create_page",
  "arguments": {
    "body": "<h1>Hello World</h1><p>This is my page content.</p><button id='confetti-btn'>Click for Confetti!</button>",
    "scripts": [
      { "src": "https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.bundle.min.js" }
    ],
    "stylesheets": [
      { "href": "https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css" }
    ]
  }
}

响应示例：

{
  "content": [
    {
      "type": "text",
      "text": "Page created successfully! A URL is provided below to view your page."
    },
    {
      "type": "text",
      "text": "View your HTML page in URL: http://localhost:3000/abc123"
    },
    {
      "type": "text",
      "text": "ID: abc123\nExpires at: 2023-04-15T12:34:56.789Z\n\nUse this ID for future updates before expiration."
    }
  ],
  "metadata": {
    "id": "abc123",
    "url": "http://localhost:3000/abc123",
    "expires_at": "2023-04-15T12:34:56.789Z"
  }
}

2. 更新页面

使用新内容更新现有页面。所有已连接的客户端都会实时看到更新。如果页面不存在（已被移除或过期），则会返回错误响应。

工具名称：update_page

输入架构：

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "ID of the page to update"
    },
    "body": {
      "type": "string",
      "description": "New HTML content for the page body (only the inner content)"
    }
  },
  "required": ["id", "body"]
}

请求示例：

{
  "name": "update_page",
  "arguments": {
    "id": "abc123",
    "body": "<h1>Updated Content</h1><p>This content has been updated.</p>"
  }
}

响应示例：

{
  "content": [
    {
      "type": "text",
      "text": "Page updated successfully! A URL is provided below to view your updated page."
    },
    {
      "type": "text",
      "text": "View your HTML page in URL: http://localhost:3000/abc123"
    },
    {
      "type": "text",
      "text": "ID: abc123\nExpires at: 2023-04-15T12:34:56.789Z\n\nUse this ID for future updates before expiration."
    }
  ],
  "metadata": {
    "id": "abc123",
    "url": "http://localhost:3000/abc123",
    "expires_at": "2023-04-15T12:34:56.789Z"
  }
}

3. 销毁页面

移除页面并断开所有客户端的连接。

工具名称：destroy_page

输入架构：

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "ID of the page to destroy"
    }
  },
  "required": ["id"]
}

请求示例：

{
  "name": "destroy_page",
  "arguments": {
    "id": "abc123"
  }
}

响应示例：

{
  "success": true
}

4. 向页面添加脚本

向现有页面添加 JavaScript 脚本。所有已连接的客户端都会实时收到这些脚本。

工具名称：add_scripts

输入架构：

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "ID of the page to add scripts to"
    },
    "scripts": {
      "type": "array",
      "description": "Array of JavaScript scripts to add to the page",
      "items": {
        "type": "object",
        "properties": {
          "src": {
            "type": "string",
            "description": "URL for external script"
          },
          "content": {
            "type": "string",
            "description": "Content for inline script"
          }
        },
        "description": "Either src or content must be provided",
        "oneOf": [
          { "required": ["src"] },
          { "required": ["content"] }
        ]
      }
    }
  },
  "required": ["id", "scripts"]
}

请求示例：

{
  "name": "add_scripts",
  "arguments": {
    "id": "abc123",
    "scripts": [
      { "content": "alert('Hello World!')" }
    ]
  }
}

响应示例：

{
  "content": [
    {
      "type": "text",
      "text": "Scripts added successfully! A URL is provided below to view your page."
    },
    {
      "type": "text",
      "text": "View your HTML page in URL: http://localhost:3000/abc123"
    },
    {
      "type": "text",
      "text": "ID: abc123\nExpires at: 2023-04-15T12:34:56.789Z\n\nUse this ID for future updates before expiration."
    }
  ],
  "metadata": {
    "id": "abc123",
    "url": "http://localhost:3000/abc123",
    "expires_at": "2023-04-15T12:34:56.789Z"
  }
}

5. 向页面添加样式表

向现有页面添加 CSS 样式表。所有已连接的客户端都会实时收到这些样式表。

工具名称：add_stylesheets

输入架构：

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "ID of the page to add stylesheets to"
    },
    "stylesheets": {
      "type": "array",
      "description": "Array of CSS stylesheets to add to the page",
      "items": {
        "type": "object",
        "properties": {
          "href": {
            "type": "string",
            "description": "URL for external stylesheet"
          }
        },
        "required": ["href"]
      }
    }
  },
  "required": ["id", "stylesheets"]
}

请求示例：

{
  "name": "add_stylesheets",
  "arguments": {
    "id": "abc123",
    "stylesheets": [
      { "href": "https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css" }
    ]
  }
}

响应示例：

{
  "content": [
    {
      "type": "text",
      "text": "Stylesheets added successfully! A URL is provided below to view your page."
    },
    {
      "type": "text",
      "text": "View your HTML page in URL: http://localhost:3000/abc123"
    },
    {
      "type": "text",
      "text": "ID: abc123\nExpires at: 2023-04-15T12:34:56.789Z\n\nUse this ID for future updates before expiration."
    }
  ],
  "metadata": {
    "id": "abc123",
    "url": "http://localhost:3000/abc123",
    "expires_at": "2023-04-15T12:34:56.789Z"
  }
}

工作原理

AI Agent 通过 Model Context Protocol（MCP）与服务交互
MCP 服务处理创建、更新或销毁 HTML 页面的请求
用户通过 AI Agent 提供的 URL 查看这些页面
实时更新通过 WebSockets 发送给所有已连接的客户端

手动测试

项目包含一个手动测试脚本（manual-test.ts），演示如何使用 MCP 服务。该脚本会：

使用 CDN 中的 canvas-confetti 创建一个新的 HTML 页面
更新页面内容
添加样式表以触发文本动画
添加脚本以触发彩纸动画
删除页面

运行手动测试：

# Run the test script
bun manual-test.ts

该脚本会提供一些 URL，你可以在浏览器中打开它们来查看页面并观察实时更新。它采用交互式方式，在每个步骤之间显示确认提示，让你可以先在浏览器中验证更改，再继续下一步。

此测试脚本尤其适用于：

验证 MCP 服务是否正常工作
了解创建、更新和销毁页面的流程
在浏览器中观察实时 WebSocket 更新

开发

# Run in development mode with auto-reload
bun run dev

# Build the project
bun run build

# Run linting
bun run check

# Fix linting issues
bun run check:write

故障排除

端口已被占用

如果启动服务时看到如下错误：

[2025-04-28 18:28:48.370 +0900] ERROR: Error starting server
    err: {
      "type": "Error",
      "message": "Failed to start server. Is port 3000 in use?",
      "stack":
          Error
              at serve (unknown)
              at [kRealListen] (node:http:565:41)
              at listen (node:http:542:35)
              at <anonymous> (/Users/yujiisobe/work/mcp-html-sync-server/node_modules/fastify/lib/server.js:265:12)
              at processTicksAndRejections (unknown:7:39)
      "code": "EADDRINUSE",
      "syscall": "listen",
      "errno": 0
    }

这表示端口 3000（或你配置的其他端口）已被另一个应用程序占用。解决方法如下：

更改端口：编辑 .env 文件，将 SERVER_PORT 改为其他值（例如 3001、8080 等）。
停止另一个应用程序：找到并停止占用端口 3000 的应用程序。你可以使用以下命令之一查找占用该端口的进程：
```
# On macOS/Linux
lsof -i :3000

# On Windows
netstat -ano | findstr :3000
```
重启计算机：某些情况下，重启可以清除可能占用该端口的孤立进程。

在 Claude Desktop 或 VS Code 中使用该服务时，如果端口已被占用，也可能会看到 JSON 解析错误。这些错误是因为服务无法正常启动，返回的是错误消息，而不是有效的 JSON 响应。

构建 Docker 镜像

docker build -t yujiosaka/mcp-html-sync-server .

许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE。

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

MCP HTML Sync Server

关于 MCP HTML Sync Server

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

MCP HTML Sync Server

行为准则 | 贡献指南 | 安全

功能

架构

安装

使用 Docker

Docker 环境变量

使用 NPX

从源代码安装

配置

配置选项

在 MCP 中使用

与 Claude Desktop 集成

Docker

NPX

与 VS Code 集成

手动安装

MCP 工具

1. 创建页面

2. 更新页面

3. 销毁页面

4. 向页面添加脚本

5. 向页面添加样式表

工作原理

手动测试

开发

故障排除

端口已被占用

构建 Docker 镜像

许可证

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？