MCP HTML 部署服务器 (Nginx 静态文件托管)

这是一个企业级的 Model Context Protocol (MCP) 服务端，支持大语言模型 (LLM) 或客户端直接上传、部署、更新和管理服务器上的静态前端 HTML/CSS/JS/媒体文件。

本项目支持 API 密钥鉴权 以及 自定义静态网站存活时间 (TTL)，并在后台自动执行过期站点的清理。

架构设计

为了避免每次部署都动态生成 Nginx 配置文件并重新加载 Nginx 服务（这会带来复杂的权限安全隐患和 Nginx 重启开销），本项目采用了 共享 URL 前缀模式 (Shared URL Prefix Pattern)：

1. 一次性 Nginx 配置：在 Nginx 中配置一个固定的前缀路径（如 /sites/）并指向存放静态网站的根目录。

2. 动态文件夹部署：MCP 服务端直接在网站根目录下，为每次部署生成唯一的站点 ID（如 _J9EqMQT），解压并存放静态网页文件（如 /var/www/mcp-sites/_J9EqMQT/）。

3. 即时访问：网页上传后即可通过对应的公网 URL（如 http://yourdomain.com/sites/_J9EqMQT/）进行实时访问，无需修改任何 Nginx 配置。

LLM / 客户端 ---[MCP 协议]---> MCP 服务端 (Streamable HTTP 或 SSE)
                                        |
                                        v (解压/拷贝至子目录)
                               /var/www/mcp-sites/
                                    |-- _J9EqMQT/ (index.html, css/, js/)
                                    `-- k8mP9a/ (index.html)
                                        ^
Nginx ---[转发 /sites/]-----------------| (静态文件托管)

Related MCP server: AICre8 MCP Server

环境配置

您可以通过环境变量或在根目录下创建 .env 文件来定制配置：

如何部署到服务器上？

推荐使用 Docker Compose 部署。这样服务器不需要安装 Node.js、pnpm 或 PM2，只需要有 Docker 即可运行 MCP 服务。

方案一：Docker Compose 部署（推荐）

1. 环境准备

服务器需要安装 Docker 和 Docker Compose 插件：

docker --version
docker compose version

2. 准备静态站点目录

该目录需要同时被 MCP 容器写入、被 Nginx 读取：

sudo mkdir -p /var/www/mcp-sites
sudo chown -R 10001:10001 /var/www/mcp-sites

镜像内的默认运行用户 UID 是 10001。核心要求是：容器内 /sites 可写，Nginx 可读。

3. 克隆项目

git clone <您的仓库地址> mcp-html-mcp-nginx
cd mcp-html-mcp-nginx

4. 修改 Compose 配置

编辑 compose.yaml，至少修改以下配置：

environment:
  MCP_BASE_URL: "https://yourdomain.com/sites"
  MCP_API_KEY: "请改成一段足够长的随机密钥"
  MCP_DEFAULT_TTL: "24h"
  MCP_MAX_TTL: "30d"
volumes:
  - ./data:/data
  - /var/www/mcp-sites:/sites

其中：

• MCP_BASE_URL 必须与 Nginx 暴露给用户访问的共同前缀一致。

• MCP_API_KEY 是 MCP 访问密钥，生产环境必须修改。

• MCP_DEFAULT_TTL 是用户未指定时的默认站点存活时间。

• MCP_MAX_TTL 是允许用户设置的最大站点存活时间。

• /var/www/mcp-sites:/sites 表示容器将网页部署到宿主机 /var/www/mcp-sites。

5. 启动服务

docker compose up -d --build

查看运行状态：

docker compose ps
docker compose logs -f

健康检查：

curl http://127.0.0.1:3000/health

6. 配置 Nginx 一次性静态目录

在您的 Nginx 配置文件（例如 /etc/nginx/sites-available/default）中添加以下 location 块：

server {
    listen 80;
    server_name yourdomain.com;

    # MCP 协议入口，可选：如果您希望通过域名访问 MCP，而不是直接开放 3000 端口
    location /mcp/ {
        proxy_pass http://127.0.0.1:3000/;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
    }

    # 所有部署网页共用这个前缀
    location /sites/ {
        alias /var/www/mcp-sites/;
        index index.html;
        try_files $uri $uri/ =404;
        expires 1h;
        add_header Cache-Control "public, no-transform";
    }
}

重新加载 Nginx：

sudo nginx -t && sudo systemctl reload nginx

如果配置了上面的 /mcp/ 代理，则客户端连接地址通常是：

• Streamable HTTP: https://yourdomain.com/mcp/mcp

• SSE: https://yourdomain.com/mcp/sse?apiKey=your_super_secret_key

如果不通过 Nginx 代理 MCP，只开放 3000 端口，则连接地址是：

• Streamable HTTP: http://<服务器IP>:3000/mcp

• SSE: http://<服务器IP>:3000/sse?apiKey=your_super_secret_key

方案二：Node.js + PM2 部署（备选）

如果您希望直接在服务器上运行 Node.js，可以使用下面的方式。

1. 环境准备

确保服务器已安装 Node.js >= 20.0.0 及包管理器 pnpm。

2. 克隆项目与安装依赖

git clone <您的仓库地址> mcp-html-mcp-nginx
cd mcp-html-mcp-nginx
pnpm install

3. 编译项目

pnpm run build

编译后的入口文件将生成在 dist/index.js。

4. 编写配置文件

在项目根目录下创建 .env 文件，填入您的配置参数：

MCP_PORT=3000
MCP_HOST=0.0.0.0
MCP_BASE_URL=https://yourdomain.com/sites
MCP_SITES_DIR=/var/www/mcp-sites
MCP_API_KEY=your_super_secret_key
MCP_DEFAULT_TTL=24h
MCP_MAX_TTL=30d
MCP_CLEANUP_INTERVAL=60000

确保运行 Node.js 进程的用户有权读写 MCP_SITES_DIR 和 MCP_DATA_DIR。

5. 使用 PM2 进行守护运行

在生产环境中，建议使用 PM2 启动和守护该服务，以便于开机自启和故障恢复。

# 全局安装 PM2
npm install -g pm2

# 启动服务
pm2 start dist/index.js --name "mcp-html-nginx" --update-env

# 保存当前列表以实现开机自启
pm2 save
pm2 startup

用户怎么用？

由于该服务是一个 MCP 服务，用户一般不需要直接调用其 API，而是通过 大语言模型客户端 (Cursor / Claude Desktop 等) 间接使用。

1. 在 Cursor 中配置 (SSE 模式)

1. 打开 Cursor 客户端，进入设置界面：Settings -> Features -> MCP。

2. 点击 + Add New MCP Server。

3. 在弹出的对话框中进行配置：

   • Name: mcp-html-nginx

   • Type: SSE

   • URL: http://<您的服务器IP>:3000/sse?apiKey=your_super_secret_key (请替换为您的实际 IP 和密钥)

4. 点击 Save。如果连接成功，Cursor 面板中会显示绿色的连接状态，并列出可用的工具列表。

如果 MCP 客户端支持自定义请求头，生产环境建议使用 Authorization: Bearer your_super_secret_key 或 x-api-key: your_super_secret_key，避免密钥出现在 URL、代理日志或浏览器历史中。SSE 初始化认证成功后，服务端会按 session 放行后续 /messages 请求，不会再把密钥写回 SSE endpoint 事件。

2. 在 Claude Desktop 中配置 (SSE 模式)

1. 编辑 Claude Desktop 的配置文件：

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

2. 在 mcpServers 字段下添加 SSE 连接配置：

   {
     "mcpServers": {
       "mcp-html-nginx": {
         "sse": {
           "url": "http://<您的服务器IP>:3000/sse?apiKey=your_super_secret_key"
         }
       }
     }
   }

3. 重启 Claude Desktop。

3. LLM 交互与实战

当客户端连接上此 MCP 服务后，您的 AI 助手便拥有了自动部署网页的能力。您只需在对话框中像平常一样和 AI 交流，例如：

• 用户: "帮我写一个倒计时网页，然后把它部署到我的服务器上。"

• AI (自动分析):

  1. 生成 HTML/CSS/JS 代码。

  2. 将网页文件编码为 Base64。

  3. 自动调用 deploy_site 工具，将文件上传至服务器。

  4. 最终返回访问地址给您，例如：https://yourdomain.com/sites/XoGd51_w/。

• 用户: "把这个网站的存活时间缩短到 30 分钟，并更新一下标题。"

• AI (自动分析):

  1. 自动调用 update_site，传入 site_id 并将 ttl 设为 "30m"。

  2. 报告更新成功。

MCP 工具接口详细说明

1. deploy_site (部署静态站点)

部署静态网页。接受三种部署源模式之一（互斥，三选一）：

• files: 文件对象数组，每个对象包含 path（相对路径）和 content（Base64 编码的文本或二进制内容），适合单页应用或少量文件。

• zip_base64: 整个站点的 Base64 编码 ZIP 压缩包，适合复杂的完整网站及带有多媒体资源的站点。

• source_path: 服务器本地已存在的静态文件夹绝对路径。

输入参数：

• name (string, 可选): 网站的友好名称。若缺省则自动生成。

• files (array, 可选): [{ path: "index.html", content: "..." }]

• zip_base64 (string, 可选): Base64 编码的 ZIP 压缩包。

• source_path (string, 可选): 服务器本地的绝对路径。

• ttl (number | string, 可选): 网站的存活时间（生命周期）。例如：3600（代表3600秒）、"30m"（30分钟）、"12h"（12小时）、"7d"（7天）、"never"（永久）。若不填，则遵循默认存活时间（若未配置默认值，则永久存活）。若服务端配置了 MCP_MAX_TTL，则不能超过该上限。

2. update_site (更新静态站点)

更新一个已经存在的站点，支持增量更新或清空覆盖。

输入参数：

• site_id (string, 必填): 目标站点的唯一 ID。

• files (array, 可选): 要更新或新增的文件列表。

• zip_base64 (string, 可选): 用于更新的 Base64 ZIP 包（可解包覆盖或追加）。

• clean (boolean, 可选, 默认 false): 设置为 true 时，会在写入新文件前清空该站点的旧目录。

• ttl (number | string, 可选): 更新或延长网站的存活时间。可以只传 site_id 和 ttl 来续期，也可以传 "never" 取消过期时间。若服务端配置了 MCP_MAX_TTL，则不能超过该上限。

3. list_sites (列出静态站点)

列出当前所有已部署的静态网站信息（包括 ID、名称、URL、文件数量等）。

输入参数：

• keyword (string, 可选): 站点 ID 或站点名称的模糊匹配过滤关键字（不区分大小写）。

4. delete_site (删除静态站点)

完全删除一个站点。从磁盘上移除对应文件夹，并从数据库中删除该条记录。

输入参数：

• site_id (string, 必填): 目标站点的唯一 ID。

自动化测试

项目中提供了一个完整的集成测试脚本，模拟了标准的 SSE 协议交互与全部工具链调用：

node test_mcp.cjs