@monoharada/wcf-mcp 0.1.1 → 0.1.2

package/core.mjs

@@ -14,6 +14,9 @@ import { z } from 'zod';
 // ---------------------------------------------------------------------------
 
 export const CANONICAL_PREFIX = 'dads';
+export const MAX_PREFIX_LENGTH = 64;
+export const STRUCTURED_CONTENT_DISABLE_FLAG = 'WCF_MCP_DISABLE_STRUCTURED_CONTENT';
+export const MAX_TOOL_RESULT_BYTES = 100 * 1024;
 
 export const CATEGORY_MAP = {
   'dads-input-text': 'Form',
@@ -79,6 +82,128 @@ export const CATEGORY_MAP = {
   'dads-loading-icon': 'Display',
 };
 
+const TOKEN_MISUSE_ALLOWED_TYPES = Object.freeze(new Set(['color', 'spacing']));
+const STRUCTURED_CONTENT_DISABLE_TRUE_VALUES = Object.freeze(new Set(['1', 'true', 'yes', 'on']));
+const WCAG_LEVELS = Object.freeze(new Set(['A', 'AA', 'AAA', 'all']));
+const A11Y_CATEGORY_LEVEL_MAP = Object.freeze({
+  semantics: 'A',
+  keyboard: 'A',
+  labels: 'A',
+  states: 'AA',
+  zoom: 'AA',
+  motion: 'AA',
+  callouts: 'AA',
+  guideline: 'A',
+});
+const NPX_TEMPLATE = Object.freeze({
+  command: 'npx',
+  args: ['@monoharada/wcf-mcp'],
+});
+export const IDE_SETUP_TEMPLATES = Object.freeze([
+  {
+    ide: 'Claude Desktop',
+    configPath: 'claude_desktop_config.json',
+    snippet: {
+      mcpServers: {
+        wcf: NPX_TEMPLATE,
+      },
+    },
+  },
+  {
+    ide: 'Claude Code',
+    configPath: '.mcp.json',
+    snippet: {
+      mcpServers: {
+        wcf: NPX_TEMPLATE,
+      },
+    },
+  },
+  {
+    ide: 'Cursor',
+    configPath: '.cursor/mcp.json',
+    snippet: {
+      mcpServers: {
+        wcf: NPX_TEMPLATE,
+      },
+    },
+  },
+]);
+
+export function isStructuredContentDisabled(env = process.env) {
+  const raw = String(env?.[STRUCTURED_CONTENT_DISABLE_FLAG] ?? '').trim().toLowerCase();
+  return STRUCTURED_CONTENT_DISABLE_TRUE_VALUES.has(raw);
+}
+
+export function toStructuredContent(data) {
+  return {
+    type: 'application/json',
+    data,
+  };
+}
+
+export function measureToolResultBytes(result) {
+  return Buffer.byteLength(JSON.stringify(result), 'utf8');
+}
+
+export function buildJsonToolResponse(payload, { env = process.env } = {}) {
+  const content = [{
+    type: 'text',
+    text: JSON.stringify(payload, null, 2),
+  }];
+
+  if (isStructuredContentDisabled(env)) {
+    return { content };
+  }
+
+  const withStructuredContent = {
+    content,
+    structuredContent: toStructuredContent(payload),
+  };
+
+  // Keep response size under the 100KB guardrail even when structuredContent is enabled.
+  if (measureToolResultBytes(withStructuredContent) > MAX_TOOL_RESULT_BYTES) {
+    return { content };
+  }
+
+  return withStructuredContent;
+}
+
+export function normalizeTokenValue(value) {
+  if (typeof value === 'string') return value.trim().toLowerCase().replace(/\s+/g, ' ');
+  if (typeof value === 'number') return String(value);
+  return '';
+}
+
+export function normalizeCssVariable(value) {
+  if (typeof value !== 'string') return '';
+
+  const raw = value.trim();
+  if (!raw) return '';
+  if (raw.startsWith('--')) return raw;
+
+  const varMatch = /^var\(\s*(--[^,\s)]+)\s*(?:,\s*[^)]+)?\)$/.exec(raw);
+  if (varMatch) return varMatch[1];
+
+  return '';
+}
+
+export function buildTokenSuggestionMap(designTokensData) {
+  if (!Array.isArray(designTokensData?.tokens)) return new Map();
+
+  const out = new Map();
+  for (const token of designTokensData.tokens) {
+    const type = String(token?.type ?? '').toLowerCase();
+    if (!TOKEN_MISUSE_ALLOWED_TYPES.has(type)) continue;
+
+    const cssVariable = normalizeCssVariable(token?.cssVariable);
+    if (!cssVariable) continue;
+
+    const normalized = normalizeTokenValue(token?.value);
+    if (normalized && !out.has(normalized)) out.set(normalized, cssVariable);
+  }
+  return out;
+}
+
 // ---------------------------------------------------------------------------
 // Helpers (exported for testing)
 // ---------------------------------------------------------------------------
@@ -87,11 +212,15 @@ export function getCategory(tagName) {
   return CATEGORY_MAP[tagName] ?? 'Other';
 }
 
-export function normalizePrefix(prefix) {
+function normalizePrefixRaw(prefix) {
   if (typeof prefix !== 'string' || prefix.trim() === '') return CANONICAL_PREFIX;
   return prefix.trim().toLowerCase();
 }
 
+export function normalizePrefix(prefix) {
+  return normalizePrefixRaw(prefix).slice(0, MAX_PREFIX_LENGTH);
+}
+
 export function withPrefix(tagName, prefix) {
   if (typeof tagName !== 'string') return tagName;
   const p = normalizePrefix(prefix);
@@ -107,14 +236,89 @@ export function toCanonicalTagName(tagName, prefix) {
   if (!raw) return undefined;
   if (raw.startsWith(`${CANONICAL_PREFIX}-`)) return raw;
 
-  const p = normalizePrefix(prefix);
-  if (p !== CANONICAL_PREFIX && raw.startsWith(`${p}-`)) {
-    return `${CANONICAL_PREFIX}-${raw.slice(p.length + 1)}`;
+  const candidates = [...new Set([normalizePrefix(prefix), normalizePrefixRaw(prefix)])];
+  for (const p of candidates) {
+    if (p !== CANONICAL_PREFIX && raw.startsWith(`${p}-`)) {
+      return `${CANONICAL_PREFIX}-${raw.slice(p.length + 1)}`;
+    }
   }
 
   return raw;
 }
 
+export function levenshteinDistance(left, right) {
+  const a = String(left ?? '');
+  const b = String(right ?? '');
+  if (a === b) return 0;
+  if (!a.length) return b.length;
+  if (!b.length) return a.length;
+
+  const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  const curr = Array.from({ length: b.length + 1 }, () => 0);
+
+  for (let i = 1; i <= a.length; i += 1) {
+    curr[0] = i;
+    for (let j = 1; j <= b.length; j += 1) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(
+        curr[j - 1] + 1,
+        prev[j] + 1,
+        prev[j - 1] + cost,
+      );
+    }
+    for (let j = 0; j <= b.length; j += 1) prev[j] = curr[j];
+  }
+
+  return prev[b.length];
+}
+
+export function suggestUnknownElementTagName(tagName, cemIndex) {
+  const target = String(tagName ?? '').trim().toLowerCase();
+  if (!target || !target.includes('-')) return undefined;
+
+  let bestTag;
+  let bestDistance = Number.POSITIVE_INFINITY;
+  const candidateSource = cemIndex instanceof Map ? cemIndex.keys() : [];
+  for (const rawCandidate of candidateSource) {
+    const candidate = String(rawCandidate ?? '').toLowerCase();
+    if (!candidate || !candidate.includes('-') || candidate === target) continue;
+    const distance = levenshteinDistance(target, candidate);
+    if (distance < bestDistance) {
+      bestDistance = distance;
+      bestTag = candidate;
+    }
+  }
+
+  if (!bestTag) return undefined;
+  const maxDistance = Math.max(1, Math.ceil(target.length * 0.3));
+  if (bestDistance > maxDistance) return undefined;
+  return bestTag;
+}
+
+export function buildDiagnosticSuggestion({ diagnostic, cemIndex }) {
+  const code = String(diagnostic?.code ?? '');
+  if (!code) return undefined;
+
+  if (code === 'unknownElement') {
+    const tagName = suggestUnknownElementTagName(diagnostic?.tagName, cemIndex);
+    return tagName ? `Did you mean "${tagName}"?` : undefined;
+  }
+
+  if (code === 'forbiddenAttribute' && String(diagnostic?.attrName ?? '').toLowerCase() === 'placeholder') {
+    return 'Use aria-label or aria-describedby support text instead of placeholder.';
+  }
+
+  if (code === 'ariaLiveNotRecommended') {
+    return 'Remove aria-live and connect support or error text via aria-describedby.';
+  }
+
+  if (code === 'roleAlertNotRecommended') {
+    return 'Use role="alert" only for urgent live updates; otherwise use static text associated via aria-describedby.';
+  }
+
+  return undefined;
+}
+
 export function findCustomElementDeclarations(manifest) {
   const modules = Array.isArray(manifest?.modules) ? manifest.modules : [];
   const decls = [];
@@ -327,6 +531,387 @@ export function resolveComponentClosure({ installRegistry }, componentIds) {
   return [...out];
 }
 
+export function buildComponentSummaries(indexes, { category, query, limit, offset, prefix } = {}) {
+  const p = normalizePrefix(prefix);
+  const q = typeof query === 'string' ? query.trim().toLowerCase() : '';
+  const pageSize = Number.isInteger(limit) ? Math.max(1, Math.min(limit, 200)) : Number.MAX_SAFE_INTEGER;
+  const pageOffset = Number.isInteger(offset) ? Math.max(0, offset) : 0;
+
+  let items = indexes.decls.map(({ decl, tagName, modulePath }) => ({
+    tagName: withPrefix(tagName, p),
+    className: typeof decl?.name === 'string' ? decl.name : undefined,
+    description: typeof decl?.description === 'string' ? decl.description : undefined,
+    category: getCategory(tagName),
+    modulePath,
+  }));
+
+  if (category) {
+    items = items.filter((item) => item.category === category);
+  }
+
+  if (q) {
+    items = items.filter((item) => {
+      const haystacks = [
+        item.tagName,
+        item.className,
+        item.description,
+        item.category,
+        item.modulePath,
+      ];
+      return haystacks.some((value) => String(value ?? '').toLowerCase().includes(q));
+    });
+  }
+
+  const total = items.length;
+  const paged = items.slice(pageOffset, pageOffset + pageSize);
+
+  return {
+    total,
+    limit: pageSize,
+    offset: pageOffset,
+    hasMore: pageOffset + paged.length < total,
+    items: paged,
+  };
+}
+
+export function parseIconNamesFromDescription(description) {
+  if (typeof description !== 'string' || description.trim() === '') return [];
+
+  const markerMatch = description.match(/iconPathsのキー[:：]\s*([^)）\n]+)/u);
+  if (!markerMatch) return [];
+
+  return [...new Set(
+    markerMatch[1]
+      .split(/[,、]/)
+      .map((name) => name.trim())
+      .map((name) => name.replace(/[`'"]/g, ''))
+      .filter(Boolean),
+  )];
+}
+
+export function parseIconNamesFromType(typeText) {
+  if (typeof typeText !== 'string' || typeText.trim() === '') return [];
+  const out = [];
+  const regex = /'([^']+)'|"([^"]+)"|`([^`]+)`/g;
+  let match;
+  while ((match = regex.exec(typeText)) !== null) {
+    const value = match[1] ?? match[2] ?? match[3];
+    if (typeof value === 'string' && value.trim() !== '') out.push(value.trim());
+  }
+  return [...new Set(out)];
+}
+
+export function extractIconNames(indexes) {
+  const decl = indexes.byTag.get('dads-icon');
+  if (!decl) return [];
+
+  const attributes = Array.isArray(decl?.attributes) ? decl.attributes : [];
+  const nameAttr = attributes.find((attr) => String(attr?.name ?? '') === 'name');
+  if (!nameAttr) return [];
+
+  const fromDescription = parseIconNamesFromDescription(nameAttr?.description);
+  const fromType = parseIconNamesFromType(nameAttr?.type?.text);
+
+  return [...new Set([...fromDescription, ...fromType])];
+}
+
+export function buildIconCatalog(indexes, prefix) {
+  const p = normalizePrefix(prefix);
+  const tag = withPrefix('dads-icon', p);
+  const names = extractIconNames(indexes).sort((left, right) => left.localeCompare(right));
+
+  return names.map((name) => ({
+    name,
+    variants: ['default'],
+    usageExample: `<${tag} name="${name}" size="20"></${tag}>`,
+  }));
+}
+
+export function searchIconCatalog(indexes, { query, limit, offset, prefix } = {}) {
+  const q = typeof query === 'string' ? query.trim().toLowerCase() : '';
+  const pageSize = Number.isInteger(limit) ? Math.max(1, Math.min(limit, 100)) : 20;
+  const pageOffset = Number.isInteger(offset) ? Math.max(0, offset) : 0;
+
+  let icons = buildIconCatalog(indexes, prefix);
+  if (q) {
+    icons = icons.filter((icon) => icon.name.toLowerCase().includes(q));
+  }
+
+  const total = icons.length;
+  const paged = icons.slice(pageOffset, pageOffset + pageSize);
+
+  return {
+    total,
+    limit: pageSize,
+    offset: pageOffset,
+    hasMore: pageOffset + paged.length < total,
+    icons: paged,
+  };
+}
+
+export function buildRelatedComponentMap(installRegistry, patterns) {
+  const components = installRegistry?.components && typeof installRegistry.components === 'object' ? installRegistry.components : {};
+  const patternList = Object.values(patterns ?? {});
+  const related = new Map();
+
+  const addRelation = (fromId, toId, via) => {
+    const from = String(fromId ?? '').trim();
+    const to = String(toId ?? '').trim();
+    if (!from || !to || from === to) return;
+
+    if (!related.has(from)) related.set(from, new Map());
+    const relMap = related.get(from);
+    if (!relMap.has(to)) relMap.set(to, new Set());
+    relMap.get(to).add(via);
+  };
+
+  for (const pattern of patternList) {
+    const patternId = String(pattern?.id ?? '').trim() || 'pattern';
+    const requires = [...new Set((Array.isArray(pattern?.requires) ? pattern.requires : []).map((id) => String(id ?? '').trim()).filter(Boolean))];
+
+    for (const fromId of requires) {
+      for (const toId of requires) {
+        addRelation(fromId, toId, patternId);
+      }
+    }
+  }
+
+  for (const [componentId, meta] of Object.entries(components)) {
+    const deps = Array.isArray(meta?.deps) ? meta.deps : [];
+    for (const dep of deps) {
+      const depId = String(dep ?? '').trim();
+      addRelation(componentId, depId, 'dependency');
+      addRelation(depId, componentId, 'dependencyOf');
+    }
+  }
+
+  return related;
+}
+
+export function getRelatedComponentsForTag({ canonicalTagName, installRegistry, relatedMap, prefix, maxResults = 12 }) {
+  const tags = installRegistry?.tags && typeof installRegistry.tags === 'object' ? installRegistry.tags : {};
+  const components = installRegistry?.components && typeof installRegistry.components === 'object' ? installRegistry.components : {};
+  const componentId = typeof canonicalTagName === 'string' ? tags[canonicalTagName] : undefined;
+  if (typeof componentId !== 'string' || componentId === '') return [];
+
+  const relMap = relatedMap?.get(componentId);
+  if (!relMap) return [];
+
+  const out = [];
+  for (const [relatedId, via] of relMap.entries()) {
+    const relatedMeta = components[relatedId];
+    if (!relatedMeta || typeof relatedMeta !== 'object') continue;
+
+    const canonicalTags = Array.isArray(relatedMeta.tags)
+      ? relatedMeta.tags.map((tag) => String(tag ?? '').toLowerCase()).filter(Boolean)
+      : [];
+
+    out.push({
+      componentId: relatedId,
+      tagNames: canonicalTags.map((tag) => withPrefix(tag, prefix)),
+      via: [...via],
+    });
+  }
+
+  out.sort((left, right) => String(left.componentId).localeCompare(String(right.componentId)));
+  return out.slice(0, Math.max(1, maxResults));
+}
+
+export function normalizeWcagLevel(level) {
+  const raw = typeof level === 'string' ? level.trim().toUpperCase() : '';
+  if (!raw || raw === 'ALL') return 'all';
+  return WCAG_LEVELS.has(raw) ? raw : 'all';
+}
+
+function getWcagLevelForA11yTopic(topic) {
+  const key = String(topic ?? '').trim().toLowerCase();
+  return A11Y_CATEGORY_LEVEL_MAP[key] ?? 'A';
+}
+
+function toChecklistItemsFromCategories(categories) {
+  if (!categories || typeof categories !== 'object') return [];
+
+  const out = [];
+  for (const [topic, checks] of Object.entries(categories)) {
+    if (!Array.isArray(checks)) continue;
+    const wcagLevel = getWcagLevelForA11yTopic(topic);
+    for (const check of checks) {
+      const text = String(check ?? '').trim();
+      if (!text) continue;
+      out.push({
+        topic: String(topic),
+        wcagLevel,
+        check: text,
+      });
+    }
+  }
+  return out;
+}
+
+function toChecklistItemsFromCallouts(callouts) {
+  if (!Array.isArray(callouts)) return [];
+
+  const out = [];
+  for (const callout of callouts) {
+    const parts = [
+      callout?.title,
+      callout?.label,
+      callout?.description,
+      ...(Array.isArray(callout?.highlights) ? callout.highlights : []),
+    ]
+      .map((value) => String(value ?? '').trim())
+      .filter(Boolean);
+
+    if (parts.length === 0) continue;
+    out.push({
+      topic: 'callouts',
+      wcagLevel: getWcagLevelForA11yTopic('callouts'),
+      check: parts.join(' — '),
+    });
+  }
+  return out;
+}
+
+export function extractAccessibilityChecklist(decl, { prefix } = {}) {
+  const annotations = decl?.custom?.a11yAnnotations;
+  if (!annotations || typeof annotations !== 'object') return undefined;
+
+  const items = [
+    ...toChecklistItemsFromCategories(annotations.categories),
+    ...toChecklistItemsFromCallouts(annotations.callouts),
+  ];
+  if (items.length === 0) return undefined;
+
+  const unique = new Map();
+  for (const item of items) {
+    const key = `${item.topic}|${item.wcagLevel}|${item.check}`;
+    if (!unique.has(key)) unique.set(key, item);
+  }
+
+  return {
+    summary: String(annotations.summary ?? '').trim() || 'Component accessibility checklist',
+    version: Number.isInteger(annotations.version) ? annotations.version : 1,
+    totalChecks: unique.size,
+    items: [...unique.values()],
+    componentTagName:
+      typeof decl?.tagName === 'string' ? withPrefix(decl.tagName.toLowerCase(), prefix) : undefined,
+  };
+}
+
+export function buildAccessibilityIndex(indexes, guidelinesIndexData, { prefix } = {}) {
+  const out = [];
+
+  for (const { decl, tagName } of indexes.decls) {
+    const checklist = extractAccessibilityChecklist(decl, { prefix });
+    if (!checklist) continue;
+    const className = typeof decl?.name === 'string' ? decl.name : undefined;
+
+    for (const item of checklist.items) {
+      out.push({
+        source: 'component',
+        componentTagName: withPrefix(tagName, prefix),
+        componentClassName: className,
+        topic: item.topic,
+        wcagLevel: item.wcagLevel,
+        check: item.check,
+      });
+    }
+  }
+
+  const docs = Array.isArray(guidelinesIndexData?.documents)
+    ? guidelinesIndexData.documents.filter((doc) => doc?.topic === 'accessibility')
+    : [];
+
+  for (const doc of docs) {
+    const sections = Array.isArray(doc?.sections) ? doc.sections : [];
+    for (const section of sections) {
+      const heading = String(section?.heading ?? '').trim();
+      const snippet = String(section?.snippet ?? '').trim();
+      if (!heading && !snippet) continue;
+
+      out.push({
+        source: 'guideline',
+        documentId: String(doc?.id ?? ''),
+        title: String(doc?.title ?? ''),
+        heading,
+        topic: 'guideline',
+        wcagLevel: getWcagLevelForA11yTopic('guideline'),
+        check: snippet || heading,
+      });
+    }
+  }
+
+  return out;
+}
+
+export function queryAccessibilityIndex(
+  entries,
+  { componentTagName, topic, wcagLevel, maxResults = 20 } = {},
+) {
+  const normalizedTopic = String(topic ?? '').trim().toLowerCase() || 'all';
+  const normalizedWcagLevel = normalizeWcagLevel(wcagLevel);
+  const pageSize = Number.isInteger(maxResults) ? Math.max(1, Math.min(maxResults, 100)) : 20;
+  const source = Array.isArray(entries) ? entries : [];
+  const results = [];
+  const shouldBalanceSources = !componentTagName && normalizedTopic === 'all';
+  const guidelineCandidates = [];
+  const componentCandidates = [];
+  const otherCandidates = [];
+  let totalHits = 0;
+
+  for (const entry of source) {
+    if (componentTagName && entry.componentTagName !== componentTagName) continue;
+    if (normalizedTopic !== 'all' && String(entry.topic ?? '').toLowerCase() !== normalizedTopic) continue;
+    if (normalizedWcagLevel !== 'all' && String(entry.wcagLevel ?? '').toUpperCase() !== normalizedWcagLevel) continue;
+
+    totalHits += 1;
+    if (!shouldBalanceSources) {
+      if (results.length < pageSize) results.push(entry);
+      continue;
+    }
+
+    if (String(entry.source ?? '') === 'guideline') {
+      if (guidelineCandidates.length < pageSize) guidelineCandidates.push(entry);
+    } else if (String(entry.source ?? '') === 'component') {
+      if (componentCandidates.length < pageSize) componentCandidates.push(entry);
+    } else if (otherCandidates.length < pageSize) {
+      otherCandidates.push(entry);
+    }
+  }
+
+  if (shouldBalanceSources) {
+    while (results.length < pageSize) {
+      const beforeLength = results.length;
+      if (guidelineCandidates.length > 0) results.push(guidelineCandidates.shift());
+      if (results.length < pageSize && componentCandidates.length > 0) results.push(componentCandidates.shift());
+      if (results.length < pageSize && otherCandidates.length > 0) results.push(otherCandidates.shift());
+      if (results.length === beforeLength) break;
+    }
+  }
+
+  return {
+    topic: normalizedTopic,
+    wcagLevel: normalizedWcagLevel,
+    totalHits,
+    results,
+  };
+}
+
+function resolveDeclByComponent(indexes, component, prefix) {
+  const byTagOrClass =
+    pickDecl(indexes, { tagName: component, prefix }) ??
+    pickDecl(indexes, { className: component, prefix });
+  if (byTagOrClass) {
+    const canonicalTag = typeof byTagOrClass.tagName === 'string' ? byTagOrClass.tagName.toLowerCase() : undefined;
+    return {
+      decl: byTagOrClass,
+      modulePath: canonicalTag ? indexes.modulePathByTag.get(canonicalTag) : undefined,
+    };
+  }
+
+  return findDeclByComponentId(indexes, component);
+}
+
 // ---------------------------------------------------------------------------
 // createMcpServer — builds the McpServer with all tools registered, but does
 // NOT connect a transport.  Callers choose their own transport.
@@ -338,11 +923,17 @@ export function resolveComponentClosure({ installRegistry }, componentIds) {
 export async function createMcpServer(loadJsonData, loadValidator) {
   const manifest = await loadJsonData('custom-elements.json');
   const indexes = buildIndexes(manifest);
-  const { collectCemCustomElements, validateTextAgainstCem } = await loadValidator();
+  const {
+    collectCemCustomElements,
+    validateTextAgainstCem,
+    detectTokenMisuseInInlineStyles = () => [],
+    detectAccessibilityMisuseInMarkup = () => [],
+  } = await loadValidator();
   const canonicalCemIndex = collectCemCustomElements(manifest);
   const installRegistry = await loadJsonData('install-registry.json');
   const patternRegistry = await loadJsonData('pattern-registry.json');
   const { patterns } = loadPatternRegistryShape(patternRegistry);
+  const relatedComponentMap = buildRelatedComponentMap(installRegistry, patterns);
 
   // Load optional data files (design tokens, guidelines index)
   let designTokensData = null;
@@ -359,6 +950,8 @@ export async function createMcpServer(loadJsonData, loadValidator) {
     // guidelines-index.json may not exist yet
   }
 
+  const tokenSuggestionMap = buildTokenSuggestionMap(designTokensData);
+
   const server = new McpServer({
     name: 'web-components-factory-design-system',
     version: '0.1.1',
@@ -394,9 +987,11 @@ export async function createMcpServer(loadJsonData, loadValidator) {
         componentsByCategory: categoryCount,
         totalPatterns: patternList.length,
         patterns: patternList,
+        ideSetupTemplates: IDE_SETUP_TEMPLATES,
         availableTools: [
           { name: 'get_design_system_overview', purpose: 'This overview (start here)' },
-          { name: 'list_components', purpose: 'Browse components, optionally filter by category' },
+          { name: 'list_components', purpose: 'Browse components with progressive disclosure and filters' },
+          { name: 'search_icons', purpose: 'Search icon names and usage examples' },
           { name: 'get_component_api', purpose: 'Full API surface for a single component' },
           { name: 'generate_usage_snippet', purpose: 'Minimal HTML usage example' },
           { name: 'get_install_recipe', purpose: 'Installation instructions and dependency tree' },
@@ -405,17 +1000,20 @@ export async function createMcpServer(loadJsonData, loadValidator) {
           { name: 'get_pattern_recipe', purpose: 'Full pattern recipe with dependencies and HTML' },
           { name: 'generate_pattern_snippet', purpose: 'Pattern HTML snippet only' },
           { name: 'get_design_tokens', purpose: 'Query design tokens (colors, spacing, typography, radius, shadows)' },
+          { name: 'get_accessibility_docs', purpose: 'Search component-level accessibility checklist and WCAG-filtered guidance' },
           { name: 'search_guidelines', purpose: 'Search design system guidelines and best practices' },
         ],
         recommendedWorkflow: [
-          '1. get_design_system_overview → understand components, patterns & tokens',
+          '1. get_design_system_overview → understand components, patterns, tokens, and IDE setup templates',
           '2. search_guidelines → find relevant guidelines',
           '3. get_design_tokens → get correct token values',
-          '4. list_components (category filter) → find the right components',
-          '5. get_component_api → check attributes, slots, events, CSS parts',
-          '6. generate_usage_snippet or get_pattern_recipe → get code',
-          '7. validate_markup → verify your HTML is correct',
-          '8. get_install_recipe → get import/install instructions',
+          '4. get_accessibility_docs → fetch component-level accessibility checklist',
+          '5. list_components (category/query + pagination) → shortlist components',
+          '6. search_icons (optional) → find icon names quickly',
+          '7. get_component_api → check attributes, slots, events, CSS parts',
+          '8. generate_usage_snippet or get_pattern_recipe → get code',
+          '9. validate_markup → verify your HTML and use suggestions to self-correct',
+          '10. get_install_recipe → get import/install instructions',
         ],
       };
 
@@ -432,31 +1030,45 @@ export async function createMcpServer(loadJsonData, loadValidator) {
     'list_components',
     {
       description:
-        'List custom elements in the design system. When: exploring available components or filtering by category. Returns: array of {tagName, className, description, category}. After: use get_component_api for details on a specific component.',
+        'List custom elements in the design system. When: exploring available components, searching by keyword, or paging through results. Returns: array of {tagName, className, description, category}. After: use get_component_api for details on a specific component.',
       inputSchema: {
         category: z
           .enum(['Form', 'Actions', 'Navigation', 'Content', 'Display', 'Layout', 'Other'])
           .optional()
           .describe('Filter by component category'),
+        query: z.string().optional().describe('Search by tagName/className/description/category/modulePath'),
+        limit: z.number().int().min(1).max(200).optional().describe('Maximum items to return (optional; omit for all results)'),
+        offset: z.number().int().min(0).optional().describe('Pagination offset (default: 0)'),
         prefix: z.string().optional(),
       },
     },
-    async ({ category, prefix }) => {
-      const p = normalizePrefix(prefix);
-      let list = indexes.decls.map(({ decl, tagName, modulePath }) => ({
-        tagName: withPrefix(tagName, p),
-        className: typeof decl?.name === 'string' ? decl.name : undefined,
-        description: typeof decl?.description === 'string' ? decl.description : undefined,
-        category: getCategory(tagName),
-        modulePath,
-      }));
-
-      if (category) {
-        list = list.filter((item) => item.category === category);
-      }
+    async ({ category, query, limit, offset, prefix }) => {
+      const { items } = buildComponentSummaries(indexes, { category, query, limit, offset, prefix });
+      return {
+        content: [{ type: 'text', text: JSON.stringify(items, null, 2) }],
+      };
+    },
+  );
 
+  // -----------------------------------------------------------------------
+  // Tool: search_icons
+  // -----------------------------------------------------------------------
+  server.registerTool(
+    'search_icons',
+    {
+      description:
+        'Search icon catalog by keyword. When: you need a valid icon name for dads-icon or icon-capable components. Returns: { total, limit, offset, hasMore, icons[] } with name, variants, and usageExample. After: use the icon name in generate_usage_snippet or your markup.',
+      inputSchema: {
+        query: z.string().optional().describe('Search icon names (partial match)'),
+        limit: z.number().int().min(1).max(100).optional().describe('Maximum items to return (default: 20)'),
+        offset: z.number().int().min(0).optional().describe('Pagination offset (default: 0)'),
+        prefix: z.string().optional(),
+      },
+    },
+    async ({ query, limit, offset, prefix }) => {
+      const payload = searchIconCatalog(indexes, { query, limit, offset, prefix });
       return {
-        content: [{ type: 'text', text: JSON.stringify(list, null, 2) }],
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
       };
     },
   );
@@ -492,10 +1104,21 @@ export async function createMcpServer(loadJsonData, loadValidator) {
       const canonicalTag = typeof decl.tagName === 'string' ? decl.tagName.toLowerCase() : undefined;
       const modulePath = canonicalTag ? indexes.modulePathByTag.get(canonicalTag) : undefined;
       const api = serializeApi(decl, modulePath, prefix);
+      const relatedComponents = getRelatedComponentsForTag({
+        canonicalTagName: canonicalTag,
+        installRegistry,
+        relatedMap: relatedComponentMap,
+        prefix,
+      });
+      if (relatedComponents.length > 0) {
+        api.relatedComponents = relatedComponents;
+      }
+      const accessibilityChecklist = extractAccessibilityChecklist(decl, { prefix });
+      if (accessibilityChecklist) {
+        api.accessibilityChecklist = accessibilityChecklist;
+      }
 
-      return {
-        content: [{ type: 'text', text: JSON.stringify(api, null, 2) }],
-      };
+      return buildJsonToolResponse(api);
     },
   );
 
@@ -550,13 +1173,8 @@ export async function createMcpServer(loadJsonData, loadValidator) {
     },
     async ({ component, prefix }) => {
       const p = normalizePrefix(prefix);
-
-      const byTagOrClass =
-        pickDecl(indexes, { tagName: component, prefix: p }) ??
-        pickDecl(indexes, { className: component, prefix: p });
-
-      const byComponentId = byTagOrClass ? undefined : findDeclByComponentId(indexes, component);
-      const decl = byTagOrClass ?? byComponentId?.decl;
+      const resolved = resolveDeclByComponent(indexes, component, p);
+      const decl = resolved?.decl;
 
       if (!decl) {
         return {
@@ -566,8 +1184,7 @@ export async function createMcpServer(loadJsonData, loadValidator) {
       }
 
       const canonicalTag = typeof decl.tagName === 'string' ? decl.tagName.toLowerCase() : undefined;
-      const modulePath =
-        canonicalTag ? indexes.modulePathByTag.get(canonicalTag) : byComponentId?.modulePath;
+      const modulePath = canonicalTag ? indexes.modulePathByTag.get(canonicalTag) : resolved?.modulePath;
       const api = serializeApi(decl, modulePath, p);
       const usageSnippet = generateSnippet(api, p);
 
@@ -633,7 +1250,7 @@ export async function createMcpServer(loadJsonData, loadValidator) {
     'validate_markup',
     {
       description:
-        'Validate HTML against the design system Custom Elements Manifest. When: checking generated or written HTML for correctness. Returns: diagnostics array with errors (unknown elements) and warnings (unknown attributes). Use after generating HTML to catch mistakes.',
+        'Validate HTML against the design system Custom Elements Manifest. When: checking generated or written HTML for correctness. Returns: diagnostics array with errors (unknown elements), warnings (unknown attributes/token misuse/accessibility misuse), and optional suggestion text for quick recovery. Use after generating HTML to catch mistakes.',
       inputSchema: {
         html: z.string(),
         prefix: z.string().optional(),
@@ -649,7 +1266,7 @@ export async function createMcpServer(loadJsonData, loadValidator) {
         cemIndex = combined;
       }
 
-      const diagnostics = validateTextAgainstCem({
+      const cemDiagnostics = validateTextAgainstCem({
         filePath: '<markup>',
         text: html,
         cem: cemIndex,
@@ -657,16 +1274,35 @@ export async function createMcpServer(loadJsonData, loadValidator) {
           unknownElement: 'error',
           unknownAttribute: 'warning',
         },
-      }).map((d) => ({
-        file: d.file,
-        range: d.range,
-        severity: d.severity,
-        code: d.code,
-        message: d.message,
-        tagName: d.tagName,
-        attrName: d.attrName,
-        hint: d.hint,
-      }));
+      });
+
+      const tokenMisuseDiagnostics = detectTokenMisuseInInlineStyles({
+        filePath: '<markup>',
+        text: html,
+        valueToToken: tokenSuggestionMap,
+        severity: 'warning',
+      });
+
+      const accessibilityDiagnostics = detectAccessibilityMisuseInMarkup({
+        filePath: '<markup>',
+        text: html,
+        severity: 'warning',
+      });
+
+      const diagnostics = [...cemDiagnostics, ...tokenMisuseDiagnostics, ...accessibilityDiagnostics].map((d) => {
+        const suggestion = buildDiagnosticSuggestion({ diagnostic: d, cemIndex });
+        return {
+          file: d.file,
+          range: d.range,
+          severity: d.severity,
+          code: d.code,
+          message: d.message,
+          tagName: d.tagName,
+          attrName: d.attrName,
+          hint: d.hint,
+          suggestion,
+        };
+      });
 
       return {
         content: [{ type: 'text', text: JSON.stringify({ diagnostics }, null, 2) }],
@@ -841,16 +1477,78 @@ export async function createMcpServer(loadJsonData, loadValidator) {
         tokens = tokens.filter((t) => t.name.toLowerCase().includes(q));
       }
 
-      return {
-        content: [{
-          type: 'text',
-          text: JSON.stringify({
-            total: tokens.length,
-            tokens,
-            summary: designTokensData.summary,
-          }, null, 2),
-        }],
+      const payload = {
+        total: tokens.length,
+        tokens,
+        summary: designTokensData.summary,
       };
+
+      return buildJsonToolResponse(payload);
+    },
+  );
+
+  // -----------------------------------------------------------------------
+  // Tool: get_accessibility_docs
+  // -----------------------------------------------------------------------
+  server.registerTool(
+    'get_accessibility_docs',
+    {
+      description:
+        'Get accessibility guidance and component checklist entries. ' +
+        'When: validating accessibility decisions, reviewing ARIA usage, or checking WCAG-focused implementation notes. ' +
+        'Returns: filtered checklist entries from component a11y annotations and accessibility guidelines. ' +
+        'After: apply the checks in your markup and run validate_markup.',
+      inputSchema: {
+        component: z.string().optional()
+          .describe('Filter by component tagName/className/componentId'),
+        topic: z.string().optional()
+          .describe('Filter by topic (e.g. semantics, keyboard, labels, states, zoom, motion, callouts, guideline)'),
+        wcagLevel: z.enum(['A', 'AA', 'AAA', 'all']).optional()
+          .describe('Filter by WCAG level (default: all)'),
+        maxResults: z.number().int().min(1).max(100).optional()
+          .describe('Maximum results to return (default: 20)'),
+        prefix: z.string().optional(),
+      },
+    },
+    async ({ component, topic, wcagLevel, maxResults, prefix }) => {
+      const p = normalizePrefix(prefix);
+      let componentTagName;
+
+      if (typeof component === 'string' && component.trim() !== '') {
+        const decl = resolveDeclByComponent(indexes, component, p)?.decl;
+
+        if (!decl || typeof decl?.tagName !== 'string') {
+          return {
+            content: [{
+              type: 'text',
+              text: `Component not found (component=${component})`,
+            }],
+            isError: true,
+          };
+        }
+
+        componentTagName = withPrefix(decl.tagName.toLowerCase(), p);
+      }
+
+      const entries = buildAccessibilityIndex(indexes, guidelinesIndexData, { prefix: p });
+      const result = queryAccessibilityIndex(entries, {
+        componentTagName,
+        topic,
+        wcagLevel,
+        maxResults,
+      });
+
+      const payload = {
+        query: {
+          component: componentTagName ?? null,
+          topic: result.topic,
+          wcagLevel: result.wcagLevel,
+        },
+        totalHits: result.totalHits,
+        results: result.results,
+      };
+
+      return buildJsonToolResponse(payload);
     },
   );
 
@@ -930,17 +1628,14 @@ export async function createMcpServer(loadJsonData, loadValidator) {
       results.sort((a, b) => b.score - a.score);
       const topResults = results.slice(0, max);
 
-      return {
-        content: [{
-          type: 'text',
-          text: JSON.stringify({
-            query,
-            topic: topic ?? 'all',
-            totalHits: results.length,
-            results: topResults,
-          }, null, 2),
-        }],
+      const payload = {
+        query,
+        topic: topic ?? 'all',
+        totalHits: results.length,
+        results: topResults,
       };
+
+      return buildJsonToolResponse(payload);
     },
   );