WrapGuard MCP

WrapGuard MCP

WrapGuard は、Playwright でレスポンシブページをレンダリングし、視覚的な行の途中で分割されている韓国語または英語の単語を検出する MCP サーバー兼 CLI です。また、ソースの不変な証拠を書き換えることなく、업로↵드 のように単語の途中に埋め込まれたハード改行も報告します。

韓国語・英語の文章がレスポンシブ画面で単語の途中で切れる問題を、実際のブラウザー座標を使って検査します。表示名は自由に変更できますが、npm／GitHub／MCP Registry のパッケージ識別子は別途維持されます。

検査内容

• アポストロフィやハイフンを含む、韓国語の語節に相当するトークンと英単語のトークン
• デフォルトで 320、375、768、1024 px における実際の書記素の位置
• 回避可能な単語途中での折り返しと、回避できない長い識別子の折り返し
• 文字間にあるソース内のハード改行
• 適用されている折り返し CSS と同一オリジンの照合ルール
• 明示的な、ドライランを優先した CSS の提案

URL、コード、ハッシュ、不変の生の証拠は、パターンまたは data-wrapguard-ignore を使って除外できます。公開フィクスチャにプライベートデータは含まれていません。

インストールしてローカルで実行する

要件：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 では、コマンドのシムを解決できないクライアントの場合、npx の代わりに npx.cmd が必要になることがあります。

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 の書き込みは、明示的に有効にしない限り無効です。ホスト型インスタンスでは、制限のないブラウザーのナビゲーションに SSRF のリスクがあるため、allowedHosts のリストを絞り込んでください。

CSS のプレビュー、CSS の書き込み、スクリーンショットでは、allowedFileRoots を確認する前にファイルシステムのリンクを解決します。スクリーンショットのディレクトリは、既存の許可されたルート内にある必要があります。明示的に選択された設定ファイルは存在し、JSON オブジェクトを含んでいる必要があります。既定の wrapguard.config.json が見つからない場合は、デフォルト設定が使われます。実行時のバージョンと MCP のバージョンは package.json から読み取られます。

3 つの公開レイヤー

1. GitHub はソース、イシュー、ドキュメント、リリースを公開します。それ自体が MCP エンドポイントを実行するわけではありません。
2. npm は、ユーザーが npx -y wrapguard-mcp で実行できる stdio 実行ファイルを公開します。
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 はプラットフォームのシークレットとして保存してください。Cloud Run、Fly.io、Render、Railway など、Playwright/Chromium に対応したコンテナサービス、または同等のサービスを使用してください。エンドポイントが存在してから、最終的な HTTPS URL を server.json の remotes フィールドに追加してください。

このプロジェクトでは、ブラウザーのバイナリ、実行時間、メモリ制限によってブラウザー監査の予測可能性が長時間稼働するコンテナよりも低くなるため、Vercel Functions はデフォルトでは推奨していません。

開発

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

テストスイートでは、韓国語と英語の合成ページ、およびインメモリの MCP クライアント／サーバー接続を使用します。

ライセンス

MIT