Web ページを AI エージェント向けに Markdown 変換する Web2MarkDown を Cloudflare Workers で作りました

ウィスキー、シガー、パイプをこよなく愛する大栗です。

Cloudflare のブログ「エージェント向けマークダウンの導入」を読んで、Workers AI の AI.toMarkdown() を使って Web サイトを Markdown として取得するツール「Web2MarkDown」を作りました。AI エージェントが Web ページを読む際のトークン消費を抑えることが目的です。一部機能を除きクレジットカード無しの Cloudflare の無料枠で使用できます。

• エージェント向けマークダウンの導入（Cloudflare ブログ）
• Workers AI toMarkdown()
• Browser Rendering
• maroon1st/Web2MarkDown

「MCP is dead」と言われる中で

最近、Eric Holmes 氏の「MCP is dead. Long live the CLI」という記事が話題になりました。LLM は CLI を使うのが既に得意だし、パイプや jq で組み合わせられるし、認証も既存の仕組みがそのまま使える。わざわざ新しいプロトコルを挟む必要はないのでは、という主張です。「MCPはなぜCLIに負けたのか」や「MCP はそんな簡単には死なない」など、様々な議論が続いています。

死んだと言われている MCP をあえて実装するのもどうかと思いましたが、Cloudflare Workers 上で動くのでリモート MCP サーバーとは相性が良いです。CLI 派の方向けに REST API も用意しているので、お好きな方をお使いください。

なぜ Markdown か

Cloudflare のブログによると、生の HTML を AI に送り込むのは非常に非効率です。例えば ## About Us という Markdown は約 3 トークンですが、HTML 版の <h2 class="section-title" id="about">About Us</h2> は 12〜15 トークンを消費します。

Cloudflare のブログ記事自体で検証した結果、HTML で 16,180 トークンのところ、Markdown に変換すると 3,150 トークンになったそうです。トークン使用量を約 80% 削減できます。

AI エージェントが Web を閲覧する時代において、HTML をそのまま読むのではなく Markdown に変換してスリムにすることは、コストの削減と処理効率の向上の両面で重要です。

Web2MarkDown の概要

Web2MarkDown は Cloudflare Worker 上で動作し、MCP（Streamable HTTP）と REST API の両方でアクセスできます。

3 つのツール

用途に応じて 3 つのツールを使い分けます。

fetch_markdown は Workers AI の AI.toMarkdown() で HTML を Markdown に変換します。JavaScript でレンダリングされるページには対応できないため、その場合は render_markdown を使います。こちらは Cloudflare の Browser Rendering で Puppeteer を起動し、JS 実行後の DOM を変換します。

convert_to_markdown は PDF や Office ドキュメントなどのファイルに対応しています。対応形式は以下の通りです。

画像変換は Workers AI のモデル（物体検出 + 要約）を使用するため Neurons を消費します。意図しない課金を防ぐために、環境変数 ALLOW_IMAGE_CONVERSION でオン・オフを切り替えられるようにしています。

使用技術

実装のポイント

MCP と REST API のサービス層共有

MCP サーバーと REST API の両方を提供していますが、ビジネスロジックは services/ ディレクトリに集約しています。fetch-markdown.ts、render-markdown.ts、convert-to-markdown.ts の各サービスが共通で使われ、MCP 側は mcp-server.ts から、REST API 側は routes/api.ts から同じサービスを呼び出す設計です。

これにより、機能の追加や修正が一箇所で済みます。

認証

Bearer Token 認証を MCP と REST API で共通化しています。トークンの比較には timing-safe な比較を使用し、タイミング攻撃を防止しています。

使い方

前提条件

• Cloudflare のアカウントを作成しておくこと
• ALLOW_IMAGE_CONVERSION を true にして画像変換を行わない限り、支払い情報の登録をしていなくても動作します

デプロイ

$ git clone https://github.com/maroon1st/Web2MarkDown.git
$ cd Web2MarkDown
$ npm install
$ npm run deploy
$ npx wrangler secret put AUTH_TOKEN   # コマンド実行後の入力欄で任意のトークン文字列を入力

デプロイ後に表示される URL（例: https://web2markdown-worker.<subdomain>.workers.dev）を控えておきます。

初めて Workers をデプロイする場合にエラーになることがあります。その場合は Cloudflare の Workers ダッシュボードで「アプリケーションを作成する」から「Hello World を開始する」で一度 Workers をデプロイした後に再度試してください。

MCP クライアントへの登録

Claude Code CLI で登録する場合は以下のコマンドを実行します。

$ claude mcp add --transport http web2markdown \
    https://web2markdown-worker.<subdomain>.workers.dev/mcp \
    --header "Authorization: Bearer <YOUR_AUTH_TOKEN>"

.mcp.json に直接記述する場合は以下のようになります。

{
  "mcpServers": {
    "web2markdown": {
      "type": "http",
      "url": "https://web2markdown-worker.<subdomain>.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_AUTH_TOKEN>"
      }
    }
  }
}

REST API での利用

MCP クライアントを使わない場合は、REST API で同じ機能を利用できます。

$ curl -X POST https://web2markdown-worker.<subdomain>.workers.dev/api/fetch \
    -H "Authorization: Bearer <YOUR_AUTH_TOKEN>" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://example.com", "maxLength": 5000}'

レスポンス例:

{
  "markdown": "# Example Domain ...",
  "metadata": {
    "originalLength": 12500,
    "truncated": false
  }
}

REST API のエンドポイントは以下の 3 つです。

環境変数

さいごに

Cloudflare Workers AI の AI.toMarkdown() と Browser Rendering を活用して、Web ページやドキュメントを Markdown に変換するツール Web2MarkDown を作りました。まあ Claude Code が作ってくれたわけですが。

AI エージェントが Web コンテンツを消費する方法は急速に変化しています。HTML をそのまま渡すのではなく、Markdown に変換してトークン消費を抑えることは、コスト面でも精度面でも有効です。Cloudflare の Markdown for Agents のように、Web サイト側がネイティブに Markdown を提供する動きもありますが、すべてのサイトが対応しているわけではありません。そのようなサイトに対しても、Web2MarkDown を使えば Markdown で取得できます。

「MCP is dead」の議論はありますが、MCP か API かの二者択一ではなく、両方を提供することで、AI エージェントからでも curl からでも使える柔軟なツールになったと思います。サーバーサイドでの変換処理が必要なユースケースでは、MCP の仕組みが自然にフィットする場面もあります。ドンドン使って行きたいですね。