w3c-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance for Claude Code when working on this project.

Project Overview

W3C MCP Server — an MCP (Model Context Protocol) server that exposes W3C/WHATWG/IETF web specifications (spec metadata, WebIDL, CSS properties, HTML elements) to AI assistants. Data comes from official npm packages (web-specs, @webref/*); this server adds caching, search, and MCP-shaped tools on top of them.

Common Commands

npm run build      # Compile TypeScript
npm run dev        # Watch mode compilation
npm test           # Run Vitest — run before committing
npm run check      # Biome lint + format (auto-fix)

Code Conventions

Error handling

Throw the custom error classes in src/errors/index.ts (SpecNotFoundError, WebIDLNotFoundError, CSSNotFoundError, ElementsNotFoundError) and let toolHandler() in src/index.ts format them via formatErrorResponse(). Not-found errors should include up to 10 spec-name suggestions generated by src/utils/suggestions.ts.

Tool registration (MCP SDK v2)

Tools are registered in createServer() (src/index.ts) with McpServer.registerTool(name, { description, inputSchema }, toolHandler(...)). inputSchema is the zod object from src/schemas/index.ts — the SDK validates arguments against it before the handler runs and generates the tools/list JSON Schema from it, so put parameter descriptions in .describe() on the zod fields rather than in a separate JSON Schema. Startup goes through serveStdio(), which serves both the initialize (2024-11-05 … 2025-11-25) and server/discover (2026-07-28) openings from the same factory.

Data mapping

Use toSpecSummary() / toSpecSummaries() from src/utils/mapper.ts for any SpecDetail → SpecSummary conversion. Do not reimplement this mapping inline.

Imports (ESM)

• Use the .js extension on local relative imports (e.g. from './foo.js') — this is required for Node ESM, even in .ts source.
• Use the node: prefix for built-ins (node:fs, node:path, ...).