W3c Mcp Server

W3C MCP 服务

日文版 README

用于访问 W3C/WHATWG/IETF Web 规范的 MCP 服务。为 AI 助手提供官方 Web 标准数据，包括规范、WebIDL 定义、CSS 属性和 HTML 元素。

安装

npm install -g @shuji-bonji/w3c-mcp

也可以直接通过 npx 使用：

npx @shuji-bonji/w3c-mcp

配置

Claude Desktop

将以下内容添加到 Claude Desktop 配置文件中：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json Linux：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "w3c": {
      "command": "npx",
      "args": ["-y", "@shuji-bonji/w3c-mcp"]
    }
  }
}

Claude Code

使用 claude mcp CLI 添加服务：

claude mcp add w3c -- npx -y @shuji-bonji/w3c-mcp

或者手动编辑 ~/.claude.json / 项目级 .mcp.json，添加上文所示的相同 mcpServers 配置块。

Cursor

将以下内容添加到 Cursor MCP 设置中（项目中的 .cursor/mcp.json 或全局设置）：

{
  "mcpServers": {
    "w3c": {
      "command": "npx",
      "args": ["-y", "@shuji-bonji/w3c-mcp"]
    }
  }
}

可用工具

规范发现

list_w3c_specs

列出 W3C/WHATWG/IETF Web 规范，并可选择筛选条件。

参数：

• organization（可选）：按组织筛选——"W3C"、"WHATWG"、"IETF" 或 "all"
• keyword（可选）：按标题或短名称中的关键词筛选
• category（可选）：按类别筛选
• limit（可选）：结果数量上限（默认值：50）

get_w3c_spec

获取特定 Web 规范的详细信息。

参数：

• shortname（必填）：规范短名称（例如 "service-workers"、"appmanifest"、"fetch"）

search_w3c_specs

根据查询字符串搜索 Web 规范。

参数：

• query（必填）：搜索查询（例如 "service worker"、"manifest"、"storage"）
• limit（可选）：结果数量上限（默认值：20）

WebIDL

get_webidl

获取某个规范的 WebIDL 接口定义。WebIDL 定义了 JavaScript API。

参数：

• shortname（必填）：规范短名称（例如 "service-workers"、"fetch"、"dom"）

list_webidl_specs

列出所有提供 WebIDL 定义的规范。

CSS

get_css_properties

获取特定规范或所有规范中的 CSS 属性定义。

参数：

• spec（可选）：规范短名称（例如 "css-grid-1"、"css-flexbox-1"）
• property（可选）：按名称搜索特定 CSS 属性

list_css_specs

列出所有提供属性定义的 CSS 规范。

HTML 元素

get_html_elements

获取特定规范或所有规范中的 HTML 元素定义。

参数：

• spec（可选）：规范短名称（例如 "html"、"svg"）
• element（可选）：按名称搜索特定元素（例如 "video"、"canvas"）

list_element_specs

列出所有提供 HTML 元素定义的规范。

PWA

get_pwa_specs

获取所有渐进式 Web 应用（PWA）相关规范。

参数：

• coreOnly（可选）：如果为 true，则仅返回核心 PWA 规范（Service Worker、Manifest、Push、Notifications）
• includeRelated（可选）：如果为 true，则还包含标题中提及存储、缓存、离线等内容的相关规范（Storage、Storage Buckets、Storage Access API 等）。当 coreOnly 为 true 时，此参数会被忽略。

默认情况下，仅返回 PWA_SHORTNAMES（src/constants/index.ts）中列出的规范，并按完全匹配的短名称筛选。

使用示例

查找 Service Worker API

Use the get_webidl tool with shortname "service-workers" to see the ServiceWorker interface definitions.

探索 PWA 技术

Use get_pwa_specs to see all PWA-related specifications, then use get_w3c_spec for details on each one.

查询 CSS Grid 属性

Use get_css_properties with spec "css-grid-1" to see all CSS Grid layout properties.

搜索存储 API

Use search_w3c_specs with query "storage" to find all storage-related specifications.

数据源

此 MCP 服务使用以下 W3C/webref 数据包：

Package	Description
web-specs	所有 Web 规范的元数据
@webref/idl	WebIDL 接口定义
@webref/css	CSS 属性和值
@webref/elements	HTML 元素定义

这些数据包由 W3C 维护，提供从官方规范中提取的机器可读数据。

GitHub 仓库：

• https://github.com/w3c/browser-specs
• https://github.com/w3c/webref

调试模式

使用环境变量启用调试日志：

# Enable debug logging
W3C_MCP_DEBUG=true npx @shuji-bonji/w3c-mcp

# Enable performance logging only
W3C_MCP_PERF=true npx @shuji-bonji/w3c-mcp

调试输出包括：

• 工具调用参数
• 执行耗时
• 数据加载性能

架构

src/
├── index.ts           # MCP server entry point
├── constants/
│   └── index.ts       # Centralized configuration constants
├── data/
│   └── loader.ts      # Data loading with caching
├── tools/             # Tool implementations
│   ├── list-specs.ts
│   ├── get-spec.ts
│   ├── search-specs.ts
│   ├── get-webidl.ts
│   ├── get-css.ts
│   ├── get-elements.ts
│   └── get-pwa-specs.ts
├── schemas/
│   └── index.ts       # Zod validation schemas
├── errors/
│   └── index.ts       # Custom error classes
├── utils/
│   ├── logger.ts      # Debug logging utilities
│   ├── mapper.ts      # Spec data mapping utilities
│   ├── search.ts      # Generic search utilities
│   └── suggestions.ts # Suggestion generation utilities
└── types/
    └── index.ts       # TypeScript type definitions

tests/
├── setup.ts           # Test setup
├── data/              # Data loader tests
├── tools/             # Tool tests
└── integration/       # MCP server integration tests

性能

• 启动：约 70ms，并行预加载所有数据
• 规范查询：使用基于 Map 的索引，复杂度为 O(1)
• 搜索：针对精确匹配进行优化，找到后立即终止

开发

# Clone the repository
git clone https://github.com/shuji-bonji/w3c-mcp.git
cd w3c-mcp

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

# Run with debug logging
W3C_MCP_DEBUG=true npm start

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Format code
npm run format

# Lint + format (auto-fix)
npm run check

许可证

MIT