# 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/npm-user-guide.md)
- 把宿主部署到远程服务器
  - 进阶/定制部署
  - [docs/remote-deploy-guide.md](./docs/remote-deploy-guide.md)
- 在源码仓库里开发、调试控制台和宿主
  - [docs/user-guide.md](./docs/user-guide.md)
- 产品目标和整体方案
  - [docs/product-spec.md](./docs/product-spec.md)

## 最短上手

### 本地宿主

```bash
npm install -g hydro-publisher
wph start
```

默认访问地址：

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

### MCP

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

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

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

## 运行模式

### 1. 本地宿主模式

适合：

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

命令：

```bash
wph start
```

### 2. 本地 MCP 模式

适合：

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

命令：

```bash
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 最终用户使用，可执行：

```bash
npm install
npm run dev:host
```

或构建后执行：

```bash
npm run build
node bin/wph.mjs start
```

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