browser-compat-mcp-server

---

概要

MDNの@mdn/browser-compat-data、web-features、caniuse-liteの利用状況データを基に、あらゆるウェブプラットフォーム機能のブラウザー対応状況とBaselineのステータスを確認できます。プロジェクトのbrowserslistターゲットに対して、機能を安全にリリースできるかどうかを確認できます。すべてのデータはパッケージに含まれているため、ネットワーク通信、APIキー、レート制限は不要です。

browser-compat-guideでは、プロジェクトのブラウザーポリシーに照らしたコードの評価と、過去のサポートに関する問題の診断について説明しています。プラグイン、npm、Docker、MCPBによるインストールに含まれており、MCP経由でskill://browser-compat-guide/SKILL.mdから利用できます。

ツール

ツール	説明
browsercompat_list_reference	他のツールが想定する参照用語を列挙します。BCDの名前空間とブラウザーID、browserslistのエージェント、Baselineの状態、グループ、ECMAScriptのスナップショットが含まれます。
browsercompat_get_feature	1つの機能について、Baselineの状態、標準化の状況、フラグやプレフィックスを含むブラウザーごとのバージョン、MDNおよび仕様へのリンクを含む互換性情報をすべて取得します。
browsercompat_check_baseline	1回の呼び出しで最大20個の機能についてリリース可否を確認します。Baselineの状態と日付、制約となるブラウザー、非推奨フラグ、およびその機能を必要とするユーザーを除外する場合のトラフィック割合を確認できます。
browsercompat_search_features	正式なキーが分からない場合に、一般名、キーワード、コード表記から機能を検索します。一致したフィールドに基づいて順位付けし、グループまたはECMAScriptのスナップショットで絞り込み、ページ分割して取得できます。
browsercompat_compare_support	明示的なbrowserslistターゲットクエリに対して機能を確認します。クエリ全体の判定、評価済みのカバレッジ、機能ごとに失敗するバージョンを取得できます。

---

機能リファレンス

browsercompat_list_reference _ツール

• 必須の topic：bcd_namespaces（12）、bcd_browsers（17）、browserslist_agents（19）、baseline_states（4）、groups（104）、または snapshots（11）。グループ ID とスナップショット ID は検索フィルターに使用します。
• エントリーには id、label、detail に加え、該当する場合は count、reported、bcd_browser、usage_percent、maps_from、または spec_url が含まれます。エージェントの bcd_browser: null は、サポート状況の比較で評価できず、unchecked_targets に報告されることを意味します。

---

browsercompat_get_feature _ツール

• feature は1～200文字で、BCD キー（css.selectors.has）または web-features ID（has）を指定します。resolve: true（デフォルトではオフ）にすると、名前または表記が1つの機能に正確に一致する場合も受け付けます。include_runtimes: true を指定すると、bun、deno、nodejs、oculus のサポート行が追加されます。
• outcome は found、no_compat_data、または miss です。miss の場合は found: false と guidance が返され、空白文字だけの入力では invalid_feature_input が返されます。各 support 行には、最新リリースの判定と、そのブラウザーに関するその他の BCD 判定を示す other_statements が含まれます。
• grid などの複数キー ID では、support、status、mdn_url、spec_urls の代わりに、Baseline のコアブラウザーごとに1行の feature_support が返されます。キー単位の結果を得るには、compat_keys のいずれかを呼び出してください。compat_keys と subkeys は、compat_keys_offset と subkeys_offset（デフォルトは0）を使って一度に100件ずつページ分割できます。limiting_browser は、必要なリリースが最も新しい Baseline コアブラウザーです。

---

browsercompat_check_baseline _ツール

• BCD キーまたは web-features ID は、それぞれ1～200文字です。最大100件まで指定でき、先頭から20件が入力順に評価されます。残りは変更されず omitted_features に返されます。100件を超えると拒否され、空白文字だけの項目では invalid_feature_input が返されます。
• 結果には、Baseline の状態と日付、limiting_browser、deprecated、experimental、discouraged が含まれます。また、caniuse がその機能を網羅している場合は usage_percent_excluded と usage_source も含まれます。利用状況データがない場合は省略され、ゼロとして報告されることはありません。
• all_widely_available が true になるのは、すべての項目が widely として解決され、かつ省略された項目がない場合のみです。非推奨かどうかは評価しません。

---

browsercompat_search_features _ツール

• query は1～100文字で、名前、キーワード、または Array.prototype.at、display: grid、<dialog> のような表記を指定できます。namespace（12種類の BCD 名前空間）、baseline（widely、newly、limited、not_mapped）、group（入れ子のグループを含む）、snapshot（ecmascript-2023 など）を組み合わせます。
• matched_on は結果がその順位になった理由を示し、support_summary は7つの Baseline コアブラウザーを対象とします。Firefox 33 (flagged)、Safari 3 (prefixed)、Chrome 94 (partial)、Edge ≤18 は、選択された判定と追加バージョンの上限を保持します。— は未サポート、削除済み、またはプレビューのみを意味し、? は不明を意味します。型付きエラーは invalid_query（検索可能なトークンが0件）、unknown_group、unknown_snapshot です。
• limit（デフォルトは10、最大50。より大きな値を指定した場合は50件が返され、cap に報告されます）と offset（デフォルトは0）でページ分割できます。totalCount と nextOffset を使ってページを進めます。ヒット数が0件の場合は、解除するフィルターを示す通知とともに成功します。

---

browsercompat_compare_support _ツール

• 必須の自己完結型 targets Browserslist クエリ（defaults や > 0.5%, last 2 versions など）に対して、1 回の呼び出しで最大 20 個の機能を比較できます。設定パッケージとカスタム設定は拒否され、ローカル設定の検索は無効になっています。最大 100 個の機能を受け付け、超過分は omitted_features に返されるため、all_clear は false になります。型付きエラー：invalid_target_query、no_targets_resolved、invalid_feature_input。
• 各 verdict は clears、fails、inconclusive、miss、ambiguous のいずれかです。クエリ内のすべてのターゲットが評価され、対応している場合に限り、機能はクリアと判定されます。そのため、defaults のように互換性データがないブラウザーを含むクエリでは、クリアになることはありません。すべての機能がクリアの場合に限り、all_clear は true になります。
• 結果には support_source、failing_ranges、failing_total、評価済みおよび未確認の合計数とカバー率が含まれます。ターゲット行は target_offset（既定値 0）と target_limit（既定値 10、最大 10。より大きい値は 10 として処理され、cap で報告）を使ってページ分割されます。判定と合計数はすべてのページで同じで、ページ分割には totalCount と nextOffset を使用します。

---

データソース

パッケージ	バージョン	ライセンス	提供内容
@mdn/browser-compat-data	^8.1.7	CC0-1.0	ブラウザーごとの対応状況、標準のステータス、MDN および仕様へのリンク
web-features	^3.44.0	Apache-2.0	Baseline の状態と日付、機能単位の主要ブラウザー対応状況、非推奨フラグ、グループ、ECMAScript スナップショット
caniuse-lite	^1.0.30001819	CC-BY-4.0	使用率の重み付けと、検索インデックス用の機能名
browserslist	^4.29.4	MIT	対象クエリの解決とカバー率の数値

CC BY 4.0 では、caniuse のデータが使用されるあらゆる場所で帰属表示が必要です。そのため、使用率の数値を含むすべてのレスポンスには、次の文字列が含まれます：Usage data from caniuse.com, © Can I Use contributors, CC BY 4.0. Figures are percentage points of global traffic. The bundled data tracks ~97.5% of global traffic; the remainder is untracked and unknown. 値は正規化されていない全世界の生のパーセンテージであり、追跡対象のトラフィックに対する正規化は行われていません。ライセンス全文と通知は THIRD_PARTY_NOTICES.md にあります。

---

機能

@cyanheads/mcp-ts-core を基盤としており、stdio と Streamable HTTP のトランスポート、差し替え可能な認証（none / jwt / oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレースを備えた構造化ログに対応しています。

ブラウザー互換性に関する機能：

• 4 つすべてのデータセットがバンドルされ、プロセス内に読み込まれます。実行時のネットワーク呼び出し、API キー、レート制限、設定は不要です。
• Baseline は、機能単位から集約せず、status.by_compat_key から browser-compat-data の各キーごとに読み取られます。同一機能内のキーでステータスが異なることが正当にあるためです。
• すべてのツールで、機能は同じ方法で解決されます。まず正確な BCD キー、次に web-features の ID、最後に moved リダイレクトを確認します。
• 対象バージョンは browser-compat-data のリリース順に従い、caniuse の表記は正規化されます（safari 16.0 ↔ 16）。

エージェントに使いやすい出力：

• すべてのレスポンスには、回答の根拠となる各バンドル済みデータセットのバージョンを示す data_version が含まれます。
• 評価されていないブラウザーについて、対応しているとは決して判定しません。データのないターゲットは unchecked_targets に入り、判定は inconclusive になります。
• 見つからない場合も失敗ではなく結果として扱います。found: false と、次の呼び出しを示す guidance が返され、型付きエラーには復旧のヒントが含まれます。
• 使用率の数値には、割合の対象となる母集団が示され、caniuse の帰属表示が付与されます。

---

はじめに

公開ホストインスタンス

公開インスタンスは https://browser-compat.caseyjhand.com/mcp で利用できます。インストールは不要です。Streamable HTTP 経由で任意の MCP クライアントから接続してください。

{
  "mcpServers": {
    "browser-compat-mcp-server": {
      "type": "streamable-http",
      "url": "https://browser-compat.caseyjhand.com/mcp"
    }
  }
}

セルフホスト／ローカル

MCP クライアントの設定ファイルに以下を追加してください。

{
  "mcpServers": {
    "browser-compat-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/browser-compat-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

または、npx を使用します（Bun は不要です）。

{
  "mcpServers": {
    "browser-compat-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/browser-compat-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

または、Docker を使用します。

{
  "mcpServers": {
    "browser-compat-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/browser-compat-mcp-server:latest"
      ]
    }
  }
}

Streamable HTTP の場合は、トランスポートを設定してサーバーを起動します。

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.0 以上（または Node.js v24 以降）。
• API キー、アカウント、ネットワークアクセスは不要です。すべてのデータセットはパッケージに含まれています。

インストール

1. リポジトリをクローンします。

git clone https://github.com/cyanheads/browser-compat-mcp-server.git

2. ディレクトリに移動します。

cd browser-compat-mcp-server

3. 依存関係をインストールします。

bun install

4. 環境を設定します（任意）。

cp .env.example .env
# edit .env if you want to override transport or logging defaults

---

設定

サーバー固有の環境変数はありません。API キーもベース URL もなく、意図的に browserslist 設定変数もありません。対象のクエリは、常に暗黙の状態ではなくツール入力として渡されます。フレームワークのトランスポート、ロギング、テレメトリー設定は引き続き構成できます。

変数	説明	デフォルト
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポート。	3010
MCP_SESSION_MODE	HTTP セッションモード。	stateless
OTEL_ENABLED	OpenTelemetry を有効にします。	false
OTEL_EXPORTER_OTLP_ENDPOINT	トレースとメトリクスのベース URL。	未設定
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	OTLP ログのエンドポイント。	未設定
LOG_TOOL_FAILURE_PAYLOADS	失敗した呼び出しの引数と結果をログに記録します。秘匿化はキー名のみを対象とするため、自由形式の値にシークレットが残ることがあります。	false
LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES	ログに記録するペイロードごとの UTF-8 バイト数の上限。	16384

任意のフレームワーク上書き設定の全一覧については、.env.example を参照してください。

---

サーバーの実行

ローカル開発

# One-time build
bun run rebuild

# Run the built server
bun run start:stdio
# or
bun run start:http

bun run devcheck   # Lint, format, typecheck, security
bun run test       # Vitest test suite
bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t browser-compat-mcp-server .
docker run --rm -p 3010:3010 browser-compat-mcp-server

Dockerfile のデフォルトは、HTTP トランスポート、ステートレスセッションモード、および /var/log/browser-compat-mcp-server へのログ出力です。OpenTelemetry のピア依存関係はデフォルトでインストールされます。これらを除外するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

---

プロジェクト構成

ディレクトリ	用途
src/index.ts	createApp() のエントリーポイントです。ツールを登録し、データセットをウォームアップします。
src/data/	browserslist エージェントから browser-compat-data へのブラウザーマップです。
src/mcp-server/tools/	ツール定義（*.tool.ts）と、各ツールで共有される出力形式です。
src/services/	同梱データセットを扱う bcd、baseline、targets、search、data-version の各サービスです。
src/types/	型定義を含まない caniuse-lite 用のアンビエントモジュール宣言です。
skills/	公開されているブラウザー互換性ワークフローガイドです。
tests/	src/ の構成に対応する Vitest テストスイートです。
docs/	design.md — 提供機能、その背後にあるデータ形式、決定事項の記録です。
changelog/	バージョンごとの変更履歴ファイルです。

生成されたファイルツリーは docs/tree.md を参照してください。

---

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.md を参照してください。要点は以下のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックで try/catch を使用しないでください
• リクエスト単位のロギングには ctx.log、テナント単位のストレージには ctx.state を使用します
• 新しいツールは src/index.ts に直接登録します
• データの整合性：同梱データセットをそのまま読み取り、不確実性を維持してください。データに含まれていないサポート状況を捏造してはいけません

---

コントリビューション

Issue を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

---

ライセンス

Apache-2.0 — 詳細は LICENSE を参照してください。