WrapGuard MCP

WrapGuard MCP

WrapGuard 是一个 MCP 服务和 CLI，可使用 Playwright 渲染响应式页面，并查找视觉行间被拆开的韩语或英语单词。它还会报告嵌在单词中的硬换行，例如 업로↵드，而不会改写不可变的源证据。

通过实际浏览器坐标检查韩语和英语句子在响应式屏幕上是否会从单词中间断开。显示名称可以自由更改，但 npm/GitHub/MCP Registry 中的包标识符会单独保留。

检查内容

• 类似韩语词组的词元和英语单词词元，包括撇号和连字符
• 默认在 320、375、768 和 1024 px 宽度下检查实际字素的位置
• 可避免的单词中间换行与无法避免的长标识符
• 字母之间的源代码硬换行
• 已应用的换行 CSS 和同源匹配规则
• 明确且默认先进行试运行的 CSS 建议

可通过模式或 data-wrapguard-ignore 排除 URL、代码、哈希和不可变的原始证据。公开测试样例不包含私人数据。

本地安装和运行

要求：Node.js 22 或更高版本，以及 Playwright Chromium 安装。

npm install
npx playwright install chromium
npm run build
node dist/stdio.js

使用 browserChannel: "auto"（默认值）时，WrapGuard 会先尝试 Playwright Chromium，然后尝试已安装的 Chrome 或 Microsoft Edge。在 CI 中，安装 Playwright Chromium 是可复现的选择。

npm 发布后，MCP 客户端可以直接启动它：

{
  "mcpServers": {
    "wrapguard": {
      "command": "npx",
      "args": ["-y", "wrapguard-mcp"],
      "env": {
        "WRAPGUARD_SERVER_NAME": "My Typography Inspector",
        "WRAPGUARD_CONFIG": "C:/absolute/path/wrapguard.config.json"
      }
    }
  }
}

在 Windows 上，无法解析命令 shim 的客户端可能需要使用 npx.cmd 而不是 npx。

不通过 MCP 将其作为发布门禁运行：

wrapguard audit ./dist/index.html --viewports 320,375,768,1024 --output wrap-report.json
wrapguard audit ./dist/index.html --format markdown --output wrap-report.md

退出代码 0 表示没有可避免的断词，1 表示发现回归问题，2 表示无法运行审计。

更改显示名称

将 wrapguard.config.example.json 复制为 wrapguard.config.json，然后编辑：

{
  "serverName": "우리집 문장 검사기"
}

WRAPGUARD_SERVER_NAME 会覆盖 JSON 值。这只会更改运行时的 MCP 显示名称。在首次公开发布之前，如果要更改永久包标识，请同时更改 name、mcpName、仓库 URL 和 server.json。

MCP 工具

• server_info
• audit_page
• detect_midword_breaks
• inspect_wrap_css
• suggest_wrap_fix
• verify_wrap_regression
• apply_wrap_fix — 默认进行试运行；实际写入需要设置 allowWrites: true 并指定允许的根目录

安全默认设置

默认配置仅审计已配置根目录下的本地文件和 localhost。除非明确启用，否则远程 URL 审计、屏幕截图和 CSS 写入均处于禁用状态。托管实例应使用范围严格的 allowedHosts 列表，因为不受限制的浏览器导航会带来 SSRF 风险。

CSS 预览、CSS 写入和屏幕截图会先解析文件系统链接，再检查 allowedFileRoots。屏幕截图目录必须位于现有的允许根目录内。明确选定的配置文件必须存在且包含 JSON 对象；缺失常规的 wrapguard.config.json 时仍会使用默认值。运行时版本和 MCP 版本均从 package.json 读取。

三个发布层

1. GitHub 用于发布源代码、问题、文档和版本。它本身不会运行 MCP 端点。
2. npm 用于发布 stdio 可执行程序，供用户运行 npx -y wrapguard-mcp。
3. 远程 MCP 通过 Streamable HTTP 托管 /mcp，供不运行本地进程的客户端使用。

发布源代码和 npm 包

检查仓库名称和公开内容后：

git init
git add .
git commit -m "feat: release WrapGuard MCP 0.1.1"
gh repo create wrapguard-mcp --public --source . --remote origin --push
npm login
npm publish --access public

然后使用官方的 mcp-publisher 验证并发布 server.json。必须先发布 npm 包，且 package.json 中的 mcpName 必须与 server.json 一致。

托管远程端点

随附的容器会在 /mcp 启动 Streamable HTTP 服务器：

docker build -t wrapguard-mcp:0.1.1 .
docker run --rm -p 8787:8787 \
  -e WRAPGUARD_HTTP_TOKEN="replace-with-a-long-random-value" \
  -e WRAPGUARD_HTTP_HOSTS="localhost,127.0.0.1" \
  wrapguard-mcp:0.1.1

对于公共主机，请将 WRAPGUARD_HTTP_HOSTS 设置为已部署的域名，并将 WRAPGUARD_HTTP_TOKEN 存储为平台密钥。请使用支持 Playwright/Chromium 的容器服务，例如 Cloud Run、Fly.io、Render、Railway 或同类服务。只有在端点可用后，才将最终 HTTPS URL 添加到 server.json 的 remotes 字段中。

对于本项目，默认不推荐使用 Vercel Functions，因为浏览器二进制文件、执行时长和内存限制会让浏览器审计的可预测性不如长期运行的容器。

开发

npm run check
npm test
npm run build
npm pack --dry-run

测试套件使用合成的韩语和英语页面，以及内存中的 MCP 客户端/服务器连接。

许可证

MIT