wrapguard-mcp

<!-- mcp-name: io.github.Yuni9959/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.

```bash
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:

```json
{
  "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:

```bash
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:

```json
{
  "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

1. **GitHub** publishes source, issues, documentation, and releases. It does not by itself run an MCP endpoint.
2. **npm** publishes the stdio executable so users can run `npx -y wrapguard-mcp`.
3. **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:

```bash
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`:

```bash
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

```bash
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