MCP HTML Sync Server

Name: MCP HTML Sync Server
Author: yujiosaka

ローカル

github.com/yujiosaka開発ツール179 週間前に更新

リポジトリ

MCP HTML Sync Server について

MCP HTML Sync Serverは、AIエージェントによるHTMLページの動的な作成・管理を可能にし、変更をWebSocket経由で接続中のブラウザーへ反映します。ページをすぐに確認したい開発ワークフロー向けです。

主な機能

01HTMLページの作成・更新・削除
02ブラウザーのリアルタイムホットリロード
03CDNまたはインラインJavaScriptの追加
04CDN経由でのCSSスタイルシート追加
05ページの有効期間と上限数の設定

活用シーン

01AIエージェントが生成したページのプレビュー
02ブラウザーで更新を確認しながらHTMLを編集
03既存ページへのスクリプトやスタイル追加

MCP 対応

AIエージェント向けに、ページの作成・更新・削除とスクリプトやスタイルシートの追加を行うMCPツールを提供します。ブラウザーはHTTPでページを取得し、WebSocketでリアルタイム更新を受け取ります。

#html #sync #server #mcp #static #hot-reload #mcp-server

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定

{
  "mcpServers": {
    "html-sync-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "pull"
      ]
    }
  }
}

起動コマンドdocker run -i --rm pull

ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ

ocipullstdio

ツール

ツール一覧はまだ取得されていません

ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。

詳細

MCP HTML Sync Server

行動規範 | コントリビューション | セキュリティ

Model Context Protocol（MCP）を使用して構築された、ホットリロード機能を備えたリアルタイム HTML 同期サーバーです。このサーバーを使用すると、AI エージェントが HTML ページを動的に作成、更新、削除でき、接続されているすべてのクライアントに更新がリアルタイムで配信されます。

特徴

リアルタイム HTML 同期：HTML コンテンツを作成、更新すると、接続されているすべてのクライアントに即座に反映されます
WebSocket ホットリロード：コンテンツが変更されると、接続されているすべてのブラウザーが自動的に再読み込みされます
スクリプト管理：CDN URL またはインラインコンテンツを使用して、JavaScript スクリプトをページに追加できます
スタイルシート管理：CDN URL を使用して、CSS スタイルシートをページに追加できます
MCP 連携：Model Context Protocol を使用する AI エージェント向けに特化して設計されています
ページのライフサイクル管理：設定可能な期間が経過すると、ページを自動的に期限切れにします
接続数の制限：ページの最大数を設定でき、最も古いページを自動的にクリーンアップします
シンプルな API：ページの作成、更新、削除に使いやすい MCP ツールを提供します
軽量：依存関係を最小限に抑え、リソースを効率的に使用します

アーキテクチャ

flowchart LR
    AI[AI Agent] -->|MCP Protocol| MCP[MCP HTML Sync Server]
    MCP -->|Create/Update/Destroy/AddScripts/AddStylesheets| PM[Page Manager]
    PM -->|Store| Pages[(HTML Pages, Scripts & Stylesheets)]
    User[User Browser] -->|HTTP Request| HTTP[HTTP Server]
    HTTP -->|Fetch Page, Scripts & Stylesheets| PM
    User <-->|WebSocket| WS[WebSocket Server]
    WS <-->|Real-time Updates| PM

インストール

Docker を使用する場合

docker pull yujiosaka/mcp-html-sync-server
docker run -p 3000:3000 yujiosaka/mcp-html-sync-server

Docker 環境変数

.env ファイルを使用する代わりに、実行時に環境変数を Docker コンテナへ直接渡すことができます。

docker run -p 3000:3000 \
  -e SERVER_PORT=3000 \
  -e BASE_URL=http://localhost:3000/ \
  -e PAGE_MAX_AGE=1h \
  -e PAGE_MAX_COUNT=1000 \
  yujiosaka/mcp-html-sync-server

この方法では、コンテナイメージを変更せずにサーバーを設定できるため、本番環境へのデプロイにおすすめです。

NPX を使用する場合

NODE_ENV=production npx mcp-html-sync-server

ソースからインストールする場合

# Clone the repository
git clone https://github.com/yujiosaka/mcp-html-sync-server.git
cd mcp-html-sync-server

# Install dependencies
bun install

# Copy the example environment file
bun run config

# Start the server
bun run start

設定

.env ファイルを編集して、サーバーを設定します。

# Host address for the HTTP server (used for binding the server)
SERVER_HOST=localhost
# Port number for the HTTP server (used for binding the server)
SERVER_PORT=3000
# Base URL for the application (used for generating view URLs)
BASE_URL=http://localhost:3000/
# Maximum age of pages before they expire (e.g., 1h = 1 hour, uses ms library format)
PAGE_MAX_AGE=1h
# Maximum number of pages that can be stored (oldest pages are removed when limit is reached)
PAGE_MAX_COUNT=1000

設定オプション

オプション	説明	デフォルト	形式
SERVER_HOST	HTTP サーバーをバインドするホストアドレス	localhost	ホスト名
SERVER_PORT	HTTP サーバーのポート番号	3000	数値
BASE_URL	ビュー URL の生成に使用するベース URL	http://localhost:3000/	URL
PAGE_MAX_AGE	ページが期限切れになるまでの最大期間	1h	時間文字列（例：1h、30m、1d）
PAGE_MAX_COUNT	保持するページの最大数	1000	数値

MCP での使用方法

Claude Desktop との連携

これを claude_desktop_config.json に追加します。

Docker

{
  "mcpServers": {
    "html-sync-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-p",
        "3000:3000",
        "-e", "SERVER_PORT=3000",
        "-e", "BASE_URL=http://localhost:3000/",
        "-e", "PAGE_MAX_AGE=1h",
        "-e", "PAGE_MAX_COUNT=1000",
        "yujiosaka/mcp-html-sync-server"
      ]
    }
  }
}

NPX

{
  "mcpServers": {
    "html-sync-server": {
      "command": "npx",
      "args": ["-y", "mcp-html-sync-server"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

VS Code との統合

すばやくインストールするには、以下のワンクリックインストールボタンのいずれかを使用してください。

手動インストール

手動でインストールするには、以下の JSON ブロックを VS Code のユーザー設定（JSON）ファイルに追加してください。Ctrl + Shift + P を押し、Preferences: Open Settings (JSON) と入力すると追加できます。

必要に応じて、ワークスペース内の .vscode/mcp.json というファイルに追加することもできます。これにより、設定をほかのユーザーと共有できます。

.vscode/mcp.json ファイルでは、mcp キーは必要ありません。

{
  "mcp": {
    "servers": {
      "html-sync-server": {
        "command": "npx",
        "args": ["-y", "mcp-html-sync-server"],
        "env": {
          "NODE_ENV": "production"
        }
      }
    }
  }
}

Docker でインストールする場合：

{
  "mcp": {
    "servers": {
      "html-sync-server": {
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-p", "3000:3000",
          "-e", "SERVER_PORT=3000",
          "-e", "BASE_URL=http://localhost:3000/",
          "-e", "PAGE_MAX_AGE=1h",
          "-e", "PAGE_MAX_COUNT=1000",
          "yujiosaka/mcp-html-sync-server"
        ]
      }
    }
  }
}

MCP ツール

このサーバーは、AI エージェントが使用できる以下の MCP ツールを提供します。

1. ページを作成する

指定したコンテンツで新しい HTML ページを作成します。

ツール名：create_page

入力スキーマ：

{
  "type": "object",
  "properties": {
    "body": {
      "type": "string",
      "description": "HTML content for the page body (only the inner content)"
    },
    "scripts": {
      "type": "array",
      "description": "Optional array of JavaScript scripts to include in the page",
      "items": {
        "type": "object",
        "properties": {
          "src": {
            "type": "string",
            "description": "URL for external script"
          },
          "content": {
            "type": "string",
            "description": "Content for inline script"
          }
        },
        "description": "Either src or content must be provided",
        "oneOf": [
          { "required": ["src"] },
          { "required": ["content"] }
        ]
      }
    },
    "stylesheets": {
      "type": "array",
      "description": "Optional array of CSS stylesheets to include in the page",
      "items": {
        "type": "object",
        "properties": {
          "href": {
            "type": "string",
            "description": "URL for external stylesheet"
          }
        },
        "required": ["href"]
      }
    }
  },
  "required": ["body"]
}

リクエスト例：

{
  "name": "create_page",
  "arguments": {
    "body": "<h1>Hello World</h1><p>This is my page content.</p><button id='confetti-btn'>Click for Confetti!</button>",
    "scripts": [
      { "src": "https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.bundle.min.js" }
    ],
    "stylesheets": [
      { "href": "https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css" }
    ]
  }
}

レスポンス例：

{
  "content": [
    {
      "type": "text",
      "text": "Page created successfully! A URL is provided below to view your page."
    },
    {
      "type": "text",
      "text": "View your HTML page in URL: http://localhost:3000/abc123"
    },
    {
      "type": "text",
      "text": "ID: abc123\nExpires at: 2023-04-15T12:34:56.789Z\n\nUse this ID for future updates before expiration."
    }
  ],
  "metadata": {
    "id": "abc123",
    "url": "http://localhost:3000/abc123",
    "expires_at": "2023-04-15T12:34:56.789Z"
  }
}

2. ページを更新する

既存のページを新しいコンテンツで更新します。接続されているすべてのクライアントに、更新がリアルタイムで表示されます。ページが存在しない場合（削除済みまたは有効期限切れの場合）は、エラーレスポンスが返されます。

ツール名：update_page

入力スキーマ：

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "ID of the page to update"
    },
    "body": {
      "type": "string",
      "description": "New HTML content for the page body (only the inner content)"
    }
  },
  "required": ["id", "body"]
}

リクエスト例：

{
  "name": "update_page",
  "arguments": {
    "id": "abc123",
    "body": "<h1>Updated Content</h1><p>This content has been updated.</p>"
  }
}

レスポンス例：

{
  "content": [
    {
      "type": "text",
      "text": "Page updated successfully! A URL is provided below to view your updated page."
    },
    {
      "type": "text",
      "text": "View your HTML page in URL: http://localhost:3000/abc123"
    },
    {
      "type": "text",
      "text": "ID: abc123\nExpires at: 2023-04-15T12:34:56.789Z\n\nUse this ID for future updates before expiration."
    }
  ],
  "metadata": {
    "id": "abc123",
    "url": "http://localhost:3000/abc123",
    "expires_at": "2023-04-15T12:34:56.789Z"
  }
}

3. ページを破棄する

ページを削除し、すべてのクライアントとの接続を切断します。

ツール名：destroy_page

入力スキーマ：

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "ID of the page to destroy"
    }
  },
  "required": ["id"]
}

リクエスト例：

{
  "name": "destroy_page",
  "arguments": {
    "id": "abc123"
  }
}

レスポンス例：

{
  "success": true
}

4. ページにスクリプトを追加する

既存のページに JavaScript スクリプトを追加します。接続されているすべてのクライアントに、スクリプトがリアルタイムで送信されます。

ツール名：add_scripts

入力スキーマ：

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "ID of the page to add scripts to"
    },
    "scripts": {
      "type": "array",
      "description": "Array of JavaScript scripts to add to the page",
      "items": {
        "type": "object",
        "properties": {
          "src": {
            "type": "string",
            "description": "URL for external script"
          },
          "content": {
            "type": "string",
            "description": "Content for inline script"
          }
        },
        "description": "Either src or content must be provided",
        "oneOf": [
          { "required": ["src"] },
          { "required": ["content"] }
        ]
      }
    }
  },
  "required": ["id", "scripts"]
}

リクエスト例：

{
  "name": "add_scripts",
  "arguments": {
    "id": "abc123",
    "scripts": [
      { "content": "alert('Hello World!')" }
    ]
  }
}

レスポンス例：

{
  "content": [
    {
      "type": "text",
      "text": "Scripts added successfully! A URL is provided below to view your page."
    },
    {
      "type": "text",
      "text": "View your HTML page in URL: http://localhost:3000/abc123"
    },
    {
      "type": "text",
      "text": "ID: abc123\nExpires at: 2023-04-15T12:34:56.789Z\n\nUse this ID for future updates before expiration."
    }
  ],
  "metadata": {
    "id": "abc123",
    "url": "http://localhost:3000/abc123",
    "expires_at": "2023-04-15T12:34:56.789Z"
  }
}

5. ページにスタイルシートを追加する

既存のページに CSS スタイルシートを追加します。接続されているすべてのクライアントに、スタイルシートがリアルタイムで送信されます。

ツール名：add_stylesheets

入力スキーマ：

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "ID of the page to add stylesheets to"
    },
    "stylesheets": {
      "type": "array",
      "description": "Array of CSS stylesheets to add to the page",
      "items": {
        "type": "object",
        "properties": {
          "href": {
            "type": "string",
            "description": "URL for external stylesheet"
          }
        },
        "required": ["href"]
      }
    }
  },
  "required": ["id", "stylesheets"]
}

リクエスト例：

{
  "name": "add_stylesheets",
  "arguments": {
    "id": "abc123",
    "stylesheets": [
      { "href": "https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css" }
    ]
  }
}

レスポンス例：

{
  "content": [
    {
      "type": "text",
      "text": "Stylesheets added successfully! A URL is provided below to view your page."
    },
    {
      "type": "text",
      "text": "View your HTML page in URL: http://localhost:3000/abc123"
    },
    {
      "type": "text",
      "text": "ID: abc123\nExpires at: 2023-04-15T12:34:56.789Z\n\nUse this ID for future updates before expiration."
    }
  ],
  "metadata": {
    "id": "abc123",
    "url": "http://localhost:3000/abc123",
    "expires_at": "2023-04-15T12:34:56.789Z"
  }
}

仕組み

AI エージェントは Model Context Protocol（MCP）を介してサーバーとやり取りします
MCP サーバーは、HTML ページの作成、更新、削除のリクエストを処理します
ユーザーは、AI エージェントが提供する URL を通じてこれらのページを表示します
WebSocket を介して、接続されているすべてのクライアントにリアルタイム更新が配信されます

手動テスト

このプロジェクトには、MCP サーバーの使い方を示す手動テストスクリプト（manual-test.ts）が含まれています。このスクリプトでは、次の操作を行います。

CDN の canvas-confetti を使って新しい HTML ページを作成します
ページのコンテンツを更新します
テキストアニメーションを実行するスタイルシートを追加します
紙吹雪のアニメーションを実行するスクリプトを追加します
ページを削除します

手動テストを実行するには、次のようにします。

# Run the test script
bun manual-test.ts

スクリプトは、ブラウザーで開いてページを確認し、リアルタイム更新を観察できる URL を表示します。各手順の間に確認プロンプトを表示する対話形式になっているため、次の手順に進む前にブラウザーで変更を確認できます。

このテストスクリプトは、特に次の用途に役立ちます。

MCP サーバーが正しく動作していることを確認する
ページの作成、更新、削除の流れを理解する
ブラウザーでリアルタイムの WebSocket 更新を確認する

開発

# Run in development mode with auto-reload
bun run dev

# Build the project
bun run build

# Run linting
bun run check

# Fix linting issues
bun run check:write

トラブルシューティング

ポートがすでに使用されています

サーバーの起動時に次のようなエラーが表示された場合：

[2025-04-28 18:28:48.370 +0900] ERROR: Error starting server
    err: {
      "type": "Error",
      "message": "Failed to start server. Is port 3000 in use?",
      "stack":
          Error
              at serve (unknown)
              at [kRealListen] (node:http:565:41)
              at listen (node:http:542:35)
              at <anonymous> (/Users/yujiisobe/work/mcp-html-sync-server/node_modules/fastify/lib/server.js:265:12)
              at processTicksAndRejections (unknown:7:39)
      "code": "EADDRINUSE",
      "syscall": "listen",
      "errno": 0
    }

これは、ポート 3000（または設定したポート）が別のアプリケーションによってすでに使用されていることを意味します。解決するには、次のいずれかを行います。

ポートを変更する：.env ファイルを編集し、SERVER_PORT を別の値（例：3001、8080 など）に変更します
別のアプリケーションを停止する：ポート 3000 を使用しているアプリケーションを見つけて停止します。次のいずれかのコマンドを使って、ポートを使用しているプロセスを見つけることができます。
```
# On macOS/Linux
lsof -i :3000

# On Windows
netstat -ano | findstr :3000
```
コンピューターを再起動する：場合によっては、再起動することで、ポートを占有している可能性のある孤立したプロセスを終了できます。

Claude Desktop または VS Code でサーバーを使用する際、ポートがすでに使用されていると JSON の解析エラーが表示されることもあります。これらのエラーは、サーバーを正常に起動できず、有効な JSON レスポンスの代わりにエラーメッセージを返すために発生します。

Docker イメージのビルド

docker build -t yujiosaka/mcp-html-sync-server .

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細については LICENSE を参照してください。

Markdown 対応

ログインしてコメント

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

入門ガイドを読む

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。

MCP HTML Sync Server

MCP HTML Sync Server について

主な機能

活用シーン

MCP 対応

設定

ツール

詳細

MCP HTML Sync Server

行動規範 | コントリビューション | セキュリティ

特徴

アーキテクチャ

インストール

Docker を使用する場合

Docker 環境変数

NPX を使用する場合

ソースからインストールする場合

設定

設定オプション

MCP での使用方法

Claude Desktop との連携

Docker

NPX

VS Code との統合

手動インストール

MCP ツール

1. ページを作成する

2. ページを更新する

3. ページを破棄する

4. ページにスクリプトを追加する

5. ページにスタイルシートを追加する

仕組み

手動テスト

開発

トラブルシューティング

ポートがすでに使用されています

Docker イメージのビルド

ライセンス

コメント

MCP は初めてですか？

MCP（Model Context Protocol）とは？

MCP サーバーとクライアントの違いは？

ローカルとリモート、どちらを選ぶべき？

Claude や Cursor にサーバーを導入するには？

掲載プロジェクトは審査されていますか？「認証済み」とは？

自分のプロジェクトが掲載されています。どう申請できますか？