@shuji-bonji/w3c-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 shuji-bonji
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ja.md

@@ -0,0 +1,246 @@
+# W3C MCP Server
+
+[![npm version](https://img.shields.io/npm/v/@shuji-bonji/w3c-mcp.svg)](https://www.npmjs.com/package/@shuji-bonji/w3c-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)
+[![MCP](https://img.shields.io/badge/MCP-Compatible-blue.svg)](https://modelcontextprotocol.io/)
+[![Built with Claude Code](https://img.shields.io/badge/Built%20with-Claude%20Code-blueviolet?logo=anthropic)](https://claude.ai/code)
+
+W3C/WHATWG/IETF の Web 仕様にアクセスするための MCP Server です。AI アシスタントに公式 Web 標準データ（仕様、WebIDL 定義、CSS プロパティ、HTML 要素）へのアクセスを提供します。
+
+## インストール
+
+```bash
+npm install -g @shuji-bonji/w3c-mcp
+```
+
+または npx で直接実行:
+
+```bash
+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`
+
+```json
+{
+  "mcpServers": {
+    "w3c": {
+      "command": "npx",
+      "args": ["-y", "@shuji-bonji/w3c-mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Cursor の MCP 設定（プロジェクトの `.cursor/mcp.json` またはグローバル設定）に追加:
+
+```json
+{
+  "mcpServers": {
+    "w3c": {
+      "command": "npx",
+      "args": ["-y", "@shuji-bonji/w3c-mcp"]
+    }
+  }
+}
+```
+
+## 利用可能なツール
+
+### 仕様の検索・取得
+
+#### `list_w3c_specs`
+W3C/WHATWG/IETF の Web 仕様一覧を取得します。
+
+パラメータ:
+- `organization` (任意): 組織でフィルタ - `"W3C"`, `"WHATWG"`, `"IETF"`, `"all"`
+- `keyword` (任意): タイトルまたは shortname でフィルタ
+- `category` (任意): カテゴリでフィルタ
+- `limit` (任意): 最大件数 (デフォルト: 50)
+
+#### `get_w3c_spec`
+特定の Web 仕様の詳細情報を取得します。
+
+パラメータ:
+- `shortname` (必須): 仕様の shortname (例: `"service-workers"`, `"appmanifest"`, `"fetch"`)
+
+#### `search_w3c_specs`
+クエリ文字列で Web 仕様を検索します。
+
+パラメータ:
+- `query` (必須): 検索クエリ (例: `"service worker"`, `"manifest"`, `"storage"`)
+- `limit` (任意): 最大件数 (デフォルト: 20)
+
+### WebIDL
+
+#### `get_webidl`
+仕様の WebIDL インターフェース定義を取得します。WebIDL は JavaScript API を定義しています。
+
+パラメータ:
+- `shortname` (必須): 仕様の shortname (例: `"service-workers"`, `"fetch"`, `"dom"`)
+
+#### `list_webidl_specs`
+WebIDL 定義がある仕様の一覧を取得します。
+
+### CSS
+
+#### `get_css_properties`
+特定の仕様または全仕様から CSS プロパティ定義を取得します。
+
+パラメータ:
+- `spec` (任意): 仕様の shortname (例: `"css-grid-1"`, `"css-flexbox-1"`)
+- `property` (任意): 特定の CSS プロパティを名前で検索
+
+#### `list_css_specs`
+CSS プロパティ定義がある仕様の一覧を取得します。
+
+### HTML 要素
+
+#### `get_html_elements`
+特定の仕様または全仕様から HTML 要素定義を取得します。
+
+パラメータ:
+- `spec` (任意): 仕様の shortname (例: `"html"`, `"svg"`)
+- `element` (任意): 特定の要素を名前で検索 (例: `"video"`, `"canvas"`)
+
+#### `list_element_specs`
+HTML 要素定義がある仕様の一覧を取得します。
+
+### PWA
+
+#### `get_pwa_specs`
+Progressive Web App (PWA) 関連の全仕様を取得します。
+
+パラメータ:
+- `coreOnly` (任意): true の場合、コア PWA 仕様のみ返す (Service Worker, Manifest, Push, Notifications)
+
+#### `get_spec_dependencies`
+仕様の依存関係情報を取得します。
+
+パラメータ:
+- `shortname` (必須): 仕様の shortname
+
+## 使用例
+
+### Service Worker API を調べる
+
+```
+get_webidl ツールで shortname "service-workers" を指定して ServiceWorker インターフェース定義を取得
+```
+
+### PWA 技術を探索する
+
+```
+get_pwa_specs で PWA 関連の全仕様を取得し、get_w3c_spec で各仕様の詳細を確認
+```
+
+### CSS Grid プロパティを調べる
+
+```
+get_css_properties で spec "css-grid-1" を指定して CSS Grid レイアウトの全プロパティを取得
+```
+
+### ストレージ API を検索する
+
+```
+search_w3c_specs で query "storage" を指定してストレージ関連の仕様を検索
+```
+
+## データソース
+
+この MCP サーバーは以下の W3C/webref データパッケージを使用しています:
+
+| パッケージ | 説明 |
+|-----------|------|
+| [web-specs](https://www.npmjs.com/package/web-specs) | 全 Web 仕様のメタデータ |
+| [@webref/idl](https://www.npmjs.com/package/@webref/idl) | WebIDL インターフェース定義 |
+| [@webref/css](https://www.npmjs.com/package/@webref/css) | CSS プロパティと値 |
+| [@webref/elements](https://www.npmjs.com/package/@webref/elements) | HTML 要素定義 |
+
+これらのパッケージは W3C によってメンテナンスされており、公式仕様から抽出された機械可読データを提供しています。
+
+**GitHub リポジトリ**:
+- https://github.com/w3c/browser-specs
+- https://github.com/w3c/webref
+
+## デバッグモード
+
+環境変数でデバッグログを有効化できます:
+
+```bash
+# デバッグログを有効化
+W3C_MCP_DEBUG=true npx @shuji-bonji/w3c-mcp
+
+# パフォーマンスログのみ有効化
+W3C_MCP_PERF=true npx @shuji-bonji/w3c-mcp
+```
+
+デバッグ出力には以下が含まれます:
+- ツール呼び出しの引数
+- 実行時間
+- データロードのパフォーマンス
+
+## アーキテクチャ
+
+```
+src/
+├── index.ts          # MCP サーバーエントリポイント
+├── data/
+│   └── loader.ts     # キャッシュ付きデータロード
+├── tools/            # ツール実装
+│   ├── 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 バリデーションスキーマ
+├── errors/
+│   └── index.ts      # カスタムエラークラス
+├── utils/
+│   └── logger.ts     # デバッグログユーティリティ
+└── types/
+    └── index.ts      # TypeScript 型定義
+```
+
+### パフォーマンス
+
+- **起動時間**: 約70ms（全データの並列プリロード）
+- **仕様検索**: O(1)（Map ベースのインデックス使用）
+- **テキスト検索**: 完全一致時の早期終了で最適化
+
+## 開発
+
+```bash
+# リポジトリをクローン
+git clone https://github.com/shuji-bonji/w3c-mcp.git
+cd w3c-mcp
+
+# 依存関係をインストール
+npm install
+
+# ビルド
+npm run build
+
+# 開発モードで実行
+npm run dev
+
+# デバッグログ付きで実行
+W3C_MCP_DEBUG=true npm start
+```
+
+## ライセンス
+
+MIT

package/README.md

@@ -0,0 +1,246 @@
+# W3C MCP Server
+
+[![npm version](https://img.shields.io/npm/v/@shuji-bonji/w3c-mcp.svg)](https://www.npmjs.com/package/@shuji-bonji/w3c-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)
+[![MCP](https://img.shields.io/badge/MCP-Compatible-blue.svg)](https://modelcontextprotocol.io/)
+[![Built with Claude Code](https://img.shields.io/badge/Built%20with-Claude%20Code-blueviolet?logo=anthropic)](https://claude.ai/code)
+
+MCP Server for accessing W3C/WHATWG/IETF web specifications. Provides AI assistants with access to official web standards data including specifications, WebIDL definitions, CSS properties, and HTML elements.
+
+## Installation
+
+```bash
+npm install -g @shuji-bonji/w3c-mcp
+```
+
+Or use directly with npx:
+
+```bash
+npx @shuji-bonji/w3c-mcp
+```
+
+## Configuration
+
+### Claude Desktop
+
+Add to your Claude Desktop configuration file:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "w3c": {
+      "command": "npx",
+      "args": ["-y", "@shuji-bonji/w3c-mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to your Cursor MCP settings (`.cursor/mcp.json` in your project or global settings):
+
+```json
+{
+  "mcpServers": {
+    "w3c": {
+      "command": "npx",
+      "args": ["-y", "@shuji-bonji/w3c-mcp"]
+    }
+  }
+}
+```
+
+## Available Tools
+
+### Specification Discovery
+
+#### `list_w3c_specs`
+List W3C/WHATWG/IETF web specifications with optional filtering.
+
+Parameters:
+- `organization` (optional): Filter by organization - `"W3C"`, `"WHATWG"`, `"IETF"`, or `"all"`
+- `keyword` (optional): Filter by keyword in title or shortname
+- `category` (optional): Filter by category
+- `limit` (optional): Maximum number of results (default: 50)
+
+#### `get_w3c_spec`
+Get detailed information about a specific web specification.
+
+Parameters:
+- `shortname` (required): Specification shortname (e.g., `"service-workers"`, `"appmanifest"`, `"fetch"`)
+
+#### `search_w3c_specs`
+Search web specifications by query string.
+
+Parameters:
+- `query` (required): Search query (e.g., `"service worker"`, `"manifest"`, `"storage"`)
+- `limit` (optional): Maximum number of results (default: 20)
+
+### WebIDL
+
+#### `get_webidl`
+Get WebIDL interface definitions for a specification. WebIDL defines the JavaScript APIs.
+
+Parameters:
+- `shortname` (required): Specification shortname (e.g., `"service-workers"`, `"fetch"`, `"dom"`)
+
+#### `list_webidl_specs`
+List all specifications that have WebIDL definitions available.
+
+### CSS
+
+#### `get_css_properties`
+Get CSS property definitions from a specific spec or all specs.
+
+Parameters:
+- `spec` (optional): Specification shortname (e.g., `"css-grid-1"`, `"css-flexbox-1"`)
+- `property` (optional): Search for a specific CSS property by name
+
+#### `list_css_specs`
+List all CSS specifications that have property definitions available.
+
+### HTML Elements
+
+#### `get_html_elements`
+Get HTML element definitions from a specific spec or all specs.
+
+Parameters:
+- `spec` (optional): Specification shortname (e.g., `"html"`, `"svg"`)
+- `element` (optional): Search for a specific element by name (e.g., `"video"`, `"canvas"`)
+
+#### `list_element_specs`
+List all specifications that have HTML element definitions available.
+
+### PWA
+
+#### `get_pwa_specs`
+Get all Progressive Web App (PWA) related specifications.
+
+Parameters:
+- `coreOnly` (optional): If true, return only the core PWA specs (Service Worker, Manifest, Push, Notifications)
+
+#### `get_spec_dependencies`
+Get dependency information for a specification.
+
+Parameters:
+- `shortname` (required): Specification shortname
+
+## Usage Examples
+
+### Find Service Worker APIs
+
+```
+Use the get_webidl tool with shortname "service-workers" to see the ServiceWorker interface definitions.
+```
+
+### Explore PWA Technologies
+
+```
+Use get_pwa_specs to see all PWA-related specifications, then use get_w3c_spec for details on each one.
+```
+
+### Look up CSS Grid Properties
+
+```
+Use get_css_properties with spec "css-grid-1" to see all CSS Grid layout properties.
+```
+
+### Search for Storage APIs
+
+```
+Use search_w3c_specs with query "storage" to find all storage-related specifications.
+```
+
+## Data Sources
+
+This MCP server uses the following W3C/webref data packages:
+
+| Package | Description |
+|---------|-------------|
+| [web-specs](https://www.npmjs.com/package/web-specs) | Metadata for all web specifications |
+| [@webref/idl](https://www.npmjs.com/package/@webref/idl) | WebIDL interface definitions |
+| [@webref/css](https://www.npmjs.com/package/@webref/css) | CSS properties and values |
+| [@webref/elements](https://www.npmjs.com/package/@webref/elements) | HTML element definitions |
+
+These packages are maintained by the W3C and provide machine-readable data extracted from official specifications.
+
+**GitHub Repositories**:
+- https://github.com/w3c/browser-specs
+- https://github.com/w3c/webref
+
+## Debug Mode
+
+Enable debug logging with environment variables:
+
+```bash
+# 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
+```
+
+Debug output includes:
+- Tool call arguments
+- Execution timing
+- Data loading performance
+
+## Architecture
+
+```
+src/
+├── index.ts          # MCP server entry point
+├── 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
+└── types/
+    └── index.ts      # TypeScript type definitions
+```
+
+### Performance
+
+- **Startup**: ~70ms parallel preloading of all data
+- **Spec Lookup**: O(1) using Map-based index
+- **Search**: Optimized with early termination on exact matches
+
+## Development
+
+```bash
+# 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
+```
+
+## License
+
+MIT

package/dist/data/loader.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Data loader for web-specs and webref packages
+ *
+ * Performance improvements:
+ * - Lazy loading with singleton pattern
+ * - Promise-based caching to prevent duplicate loads
+ * - Parallel loading support
+ * - Memory-efficient data structures
+ */
+import type { SpecDetail } from '../types/index.js';
+/**
+ * Load specs with singleton promise pattern
+ * Multiple simultaneous calls share the same loading promise
+ */
+export declare function loadSpecs(): Promise<SpecDetail[]>;
+/**
+ * Find a spec by shortname - O(1) with index
+ */
+export declare function findSpec(shortname: string): Promise<SpecDetail | undefined>;
+/**
+ * Load WebIDL with singleton promise pattern
+ */
+export declare function loadWebIDLRaw(): Promise<Record<string, string>>;
+export interface CSSPropertyDef {
+    name: string;
+    href?: string;
+    syntax?: string;
+    initial?: string;
+    inherited?: string;
+    animationType?: string;
+    values?: Array<{
+        name: string;
+        href?: string;
+        value?: string;
+    }>;
+    styleDeclaration?: string[];
+    [key: string]: unknown;
+}
+export interface CSSData {
+    properties: CSSPropertyDef[];
+    functions: Array<{
+        name: string;
+        href?: string;
+        value?: string;
+    }>;
+    types: Array<{
+        name: string;
+        href?: string;
+        value?: string;
+    }>;
+    selectors: Array<{
+        name: string;
+        href?: string;
+    }>;
+    atrules: Array<{
+        name: string;
+        href?: string;
+        value?: string;
+    }>;
+}
+/**
+ * Load CSS data with singleton promise pattern
+ */
+export declare function loadCSS(): Promise<CSSData>;
+export interface ElementDef {
+    name: string;
+    href?: string;
+    interface?: string;
+    [key: string]: unknown;
+}
+export interface ElementSpecData {
+    spec: {
+        title: string;
+        url: string;
+    };
+    elements: ElementDef[];
+}
+/**
+ * Load elements data with singleton promise pattern
+ */
+export declare function loadElements(): Promise<Record<string, ElementSpecData>>;
+/**
+ * Preload all data in parallel
+ * Call this at server startup for better first-request performance
+ */
+export declare function preloadAll(): Promise<void>;
+export declare function clearCache(): void;
+//# sourceMappingURL=loader.d.ts.map

package/dist/data/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/data/loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAkBpD;;;GAGG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC,CAUvD;AAoBD;;GAEG;AACH,wBAAsB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAmBjF;AAED;;GAEG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAwBrE;AAMD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChE,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,OAAO;IACtB,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,SAAS,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClE,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC9D,SAAS,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClD,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjE;AAED;;GAEG;AACH,wBAAsB,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,CAchD;AAMD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE;QACJ,KAAK,EAAE,MAAM,CAAC;QACd,GAAG,EAAE,MAAM,CAAC;KACb,CAAC;IACF,QAAQ,EAAE,UAAU,EAAE,CAAC;CACxB;AAED;;GAEG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAc7E;AAMD;;;GAGG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAOhD;AAMD,wBAAgB,UAAU,IAAI,IAAI,CAOjC"}