Hydro Publisher

Hydro Publisher 是一个页面发布宿主，包含两部分能力：

• wph start
  • 启动 Web 宿主与 HTTP API
• wph mcp
  • 启动 stdio MCP server，由模型客户端调用

页面、模板、业务目录、已发布路由和自定义 HTML 都由同一个宿主管理。

默认推荐使用方式是：

• 本地宿主
• 本地 MCP

也就是：

• wph start 跑在用户自己电脑上
• wph mcp 也跑在本机
• 页面默认发布到本地宿主

远程服务器部署不是默认用户路径，而是进阶/定制方案。它通常需要额外处理：

• 域名
• HTTPS / SSL
• 反向代理
• 上传超时
• 运维与备份

如果用户只是想稳定地创建、预览和发布页面，应优先选择本地宿主模式。

先看哪份文档

按你的使用场景直接进入对应文档：

• 通过 npm 安装并在本机使用
  • docs/npm-user-guide.md
• 把宿主部署到远程服务器
  • 进阶/定制部署
  • docs/remote-deploy-guide.md
• 在源码仓库里开发、调试控制台和宿主
  • docs/user-guide.md
• 产品目标和整体方案
  • docs/product-spec.md

最短上手

本地宿主

npm install -g hydro-publisher
wph start

默认访问地址：

• Web 宿主：http://localhost:3900
• 健康检查：http://localhost:3900/api/health

MCP

如果要在 MCP 客户端里使用，推荐在客户端配置中调用：

{
  "mcpServers": {
    "hydro-publisher": {
      "command": "npm.cmd",
      "args": [
        "exec",
        "--yes",
        "--package=hydro-publisher",
        "--",
        "wph",
        "mcp"
      ]
    }
  }
}

Windows 用 npm.cmd，macOS / Linux 改成 npm。

运行模式

1. 本地宿主模式

适合：

• 人工打开浏览器操作
• 本地管理业务、页面、预览和发布
• 默认推荐给最终用户

命令：

wph start

2. 本地 MCP 模式

适合：

• 在支持 MCP 的客户端里通过自然语言管理页面
• 让模型创建业务、创建页面、发布页面、导入 custom HTML
• 与本地宿主一起组成默认推荐方案

命令：

wph mcp

说明：

• MCP 通过 HTTP API 调用宿主
• 当 WPH_BASE_URL 指向本机 localhost 或 127.0.0.1 时，MCP 可按配置自动拉起本地宿主
• 当 WPH_BASE_URL 指向远程站点时，WPH_MCP_AUTOSTART 必须为 0

3. 远程宿主模式

适合：

• 把 Web 宿主部署到单独服务器
• 本地 MCP 客户端连接远程站点
• 有明确运维能力或项目定制需求的场景

这种模式下：

• 远程服务器只运行 wph start
• 本地 MCP 客户端运行 wph mcp
• 远程宿主不能由本地 MCP 进程拉起

注意：

• 远程模式不是默认推荐路径
• 大文件 custom HTML 导入的稳定性会受到网络、CDN、反向代理和超时配置影响
• 如果要对外发布为公网网站，建议作为专门部署项目处理

当前实现范围

当前仓库已经实现：

• apps/server
  • Fastify + SQLite + Drizzle 宿主服务
• apps/mcp-server
  • stdio MCP server
• apps/web
  • React + Vite 控制台与宿主页
• packages/shared-schema
  • 共享 zod schema 与领域类型
• templates/
  • 模板 manifest

当前已接通能力：

• 业务管理
• 模板查询
• 页面创建、修改、删除、发布、撤回
• custom HTML 页面创建与更新
• 本地 .html/.htm 文件导入
• local <img src> 图片导入、复制与链接改写

当前 custom HTML 本地资源处理范围保持收敛：

• 已支持：本地 <img src>
• 未覆盖：srcset、CSS url(...)、视频、字体

源码仓库启动

如果你是在仓库里开发，而不是作为 npm 最终用户使用，可执行：

npm install
npm run dev:host

或构建后执行：

npm run build
node bin/wph.mjs start

源码开发的说明见 docs/user-guide.md。