browser-compat-mcp-server

---

概述

查询任意 Web 平台功能的浏览器支持情况和 Baseline 状态，数据来自 MDN 的 @mdn/browser-compat-data、web-features 和 caniuse-lite 使用数据。检查某项功能是否适合在目标 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	查询单项功能的完整兼容性记录：Baseline 状态、标准状态、各浏览器版本及其标志和前缀，以及 MDN 和规范链接。
browsercompat_check_baseline	一次调用检查最多 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、label 和 detail，并根据具体情况包含 count、reported、bcd_browser、usage_percent、maps_from 或 spec_url。如果某个 Agent 的 bcd_browser: null，则无法评估其支持情况对比，并会将其列在 unchecked_targets 中。

---

browsercompat_get_feature _工具

• 一个 feature，长度为 1–200 个字符：BCD 键（css.selectors.has）或 web-features ID（has）。resolve: true（默认关闭）还会在名称或表示法与某个特性完全匹配时接受该输入。include_runtimes: true 会添加 bun、deno、nodejs 和 oculus 的支持行。
• outcome 为 found、no_compat_data 或 miss；未找到时会返回 found: false 和 guidance，仅含空白字符的输入则会返回 invalid_feature_input。每个 support 行都提供最新版本的说明，该浏览器的其他 BCD 说明列在 other_statements 中。
• 像 grid 这样的多键 ID 会返回 feature_support（每个 Baseline 核心浏览器一行），而不返回 support、status、mdn_url 和 spec_urls；如需获取键级别的结果，请调用其中一个 compat_keys。compat_keys 和 subkeys 每次分页 100 项，使用 compat_keys_offset 和 subkeys_offset（默认值为 0）。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。如果用量数据不可用，则不会提供用量信息，绝不会报告为零。
• 只有当每个条目的结果均为 widely 且没有条目被省略时，all_widely_available 才为 true；它不会评估弃用情况。

---

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 涵盖七个 Baseline 核心浏览器：Firefox 33 (flagged)、Safari 3 (prefixed)、Chrome 94 (partial) 和 Edge ≤18 会保留所选判定及新增版本上限；— 表示不支持、已移除或仅预览，? 表示未知。类型化错误包括：invalid_query（没有可搜索的词元）、unknown_group、unknown_snapshot。
• 使用 limit（默认值为 10，最多 50；更大的值会按 50 处理，并在 cap 中报告）和 offset（默认值为 0）分页；totalCount 和 nextOffset 用于控制分页。未找到结果时会成功返回，并提示可移除哪个筛选条件。

---

browsercompat_compare_support _工具

• 每次调用最多查询 20 个功能，并且必须提供自包含的 targets browserslist 查询，例如 defaults 或 > 0.5%, last 2 versions；不接受配置包和自定义配置，并且会禁用本地配置发现。最多接受 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 跟踪的结构化日志记录。

浏览器兼容性专属功能：

• 所有四个数据集都打包在程序中并在进程内加载——无需运行时网络调用、API 密钥或速率限制，也无需任何配置
• Baseline 按浏览器兼容数据键从 status.by_compat_key 读取，不会从功能级别汇总，因为同一功能下的各个键可能存在差异
• 每个工具都以相同方式解析功能：先查找精确的 BCD 键，再查找 web-features id，最后查找 moved 重定向
• 目标版本遵循 browser-compat-data 的发布顺序，并将 caniuse 的写法规范化（safari 16.0 ↔ 16）

便于 Agent 使用的输出：

• 每个响应都会回显 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 中直接注册新工具
• 数据完整性：按原样读取随附数据集并保留其不确定性；绝不编造数据中未包含的支持情况

---

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

---

许可证

Apache-2.0——详情请参阅 LICENSE。