wrapguard-mcp

WrapGuard MCP

WrapGuard is an MCP server and CLI that renders responsive pages with Playwright and finds Korean or English words split across visual lines. It also reports hard newlines embedded inside words, such as 업로↵드, without rewriting immutable source evidence.

한글·영어 문장이 반응형 화면에서 단어 중간에 잘리는 문제를 실제 브라우저 좌표로 검사합니다. 표시 이름은 자유롭게 바꿀 수 있지만 npm/GitHub/MCP Registry의 패키지 식별자는 별도로 유지됩니다.

What it checks

• Korean eojeol-like tokens and English word tokens, including apostrophes and hyphens
• Actual grapheme positions across 320, 375, 768, and 1024 px by default
• Avoidable mid-word wraps versus unavoidable long identifiers
• Hard source newlines between letters
• Applied wrapping CSS and same-origin matching rules
• Explicit, dry-run-first CSS suggestions

URLs, code, hashes, and immutable raw evidence can be excluded with patterns or data-wrapguard-ignore. Public fixtures contain no private data.

Install and run locally

Requirements: Node.js 22 or newer and a Playwright Chromium installation.

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

With browserChannel: "auto" (the default), WrapGuard tries Playwright Chromium first and then an installed Chrome or Microsoft Edge. Installing Playwright Chromium is the reproducible choice for CI.

After an npm release, an MCP client can launch it directly:

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

On Windows, clients that do not resolve command shims may need npx.cmd instead of npx.

Run it as a release gate without 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

Exit code 0 means no avoidable split, 1 means regression issues were found, and 2 means the audit could not run.

Change the displayed name

Copy wrapguard.config.example.json to wrapguard.config.json, then edit:

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

WRAPGUARD_SERVER_NAME overrides the JSON value. This changes the runtime MCP display name only. Before the first public release, change name, mcpName, repository URLs, and server.json together if you want a different permanent package identity.

MCP tools

• server_info
• audit_page
• detect_midword_breaks
• inspect_wrap_css
• suggest_wrap_fix
• verify_wrap_regression
• apply_wrap_fix — dry-run by default; real writes require allowWrites: true and an allowed root

Safe defaults

The default configuration audits local files under the configured roots and localhost only. Remote URL auditing, screenshots, and CSS writes are disabled unless explicitly enabled. A hosted instance should use a narrow allowedHosts list because unrestricted browser navigation creates an SSRF risk.

Three publication layers

• GitHub publishes source, issues, documentation, and releases. It does not by itself run an MCP endpoint.
• npm publishes the stdio executable so users can run npx -y wrapguard-mcp.
• Remote MCP hosts /mcp over Streamable HTTP for clients that do not run local processes.

Publish source and npm

After reviewing the repository name and public contents:

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

Then validate and publish server.json with the official mcp-publisher. The npm package must be published first and the mcpName in package.json must match server.json.

Host a remote endpoint

The included container starts the Streamable HTTP server at /mcp:

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

For a public host, set WRAPGUARD_HTTP_HOSTS to the deployed domain and store WRAPGUARD_HTTP_TOKEN as a platform secret. Use a container service that supports Playwright/Chromium, such as Cloud Run, Fly.io, Render, Railway, or an equivalent service. Add the final HTTPS URL to the remotes field in server.json only after the endpoint exists.

Vercel Functions are not the default recommendation for this project because browser binaries, execution duration, and memory limits make browser audits less predictable than a long-running container.

Development

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

The test suite uses synthetic Korean and English pages and an in-memory MCP client/server connection.

License

MIT