@monoharada/wcf-mcp 0.10.0 → 0.12.0

package/README.md

@@ -78,13 +78,13 @@ claude mcp add wcf -- npx @monoharada/wcf-mcp
 }
 ```
 
-## 提供機能（19 tools + 1 prompt + 5 resources）
+## 提供機能（19 tools + 2 prompts + 5 resources）
 
 ### ガードレール
 
 | ツール | 説明 |
 |--------|------|
-| `get_design_system_overview` | 最初に呼ぶ前提情報（カテゴリ別コンポーネント数、利用可能パターン、推奨ワークフロー、IDE設定テンプレート）を返す |
+| `get_design_system_overview` | 最初に呼ぶ前提情報（カテゴリ別コンポーネント数、利用可能パターン、`componentPatternMap`、推奨 preloading / workflow、IDE設定テンプレート）を返す |
 
 ### コンポーネント検索・API
 
@@ -100,7 +100,7 @@ claude mcp add wcf -- npx @monoharada/wcf-mcp
 
 | ツール | 説明 |
 |--------|------|
-| `validate_markup` | HTML スニペットを検証し、セマンティック検証（下表）で `suggestion` 付き診断を返す |
+| `validate_markup` | HTML スニペットを検証し、セマンティック検証（下表）で `suggestion` 付き診断を返す。severity は `error` / `warning` / `info` |
 | `validate_files` | 複数のマークアップファイルをまとめて検証し、ファイル別診断と集計を返す |
 | `validate_project` | ディレクトリを走査し、include/exclude glob に一致する複数ファイルをまとめて検証する |
 
@@ -126,6 +126,11 @@ claude mcp add wcf -- npx @monoharada/wcf-mcp
 | `emptyAriaLabel` | error | 空の `aria-label` 属性（アクセシビリティ違反） | `<dads-button aria-label="">` |
 | `duplicateId` | error | 同一ドキュメント内で `id` が重複している | `<div id="hero">...</div><section id="hero">...</section>` |
 | `forbiddenAttribute` | warning | 禁止属性 | `placeholder` |
+| `sortOnTh` / `sortWrongTarget` / `sortTypeOnWrongElement` | warning | `dads-table` のソート構造誤用 | `th[data-sort]`, `button[data-sort-type]` |
+| `selectionControlWrongElement` | warning | `data-select-row` / `data-select-all` が checkbox 以外 | `<button data-select-row>` |
+| `resourceListWholeLinkMissingInteraction` | warning | `dads-resource-list[href]` に `data-interaction="whole"` がない | `<dads-resource-list href="...">` |
+| `nativePatternReplaceable` | warning / info | 既存 DADS コンポーネントに置換可能な独自パターン | `role="tablist"`, `role="dialog"`, `<dl>` |
+| `customAnimationReplaceable` | warning | スピナー相当の独自 CSS アニメーション | `@keyframes spin` + `animation` |
 
 ### UI パターン
 
@@ -240,13 +245,14 @@ claude mcp add wcf -- npx @monoharada/wcf-mcp
 
 | 名前 | 説明 |
 |------|------|
+| `build_page` | パターンID またはコンポーネントリストから no-build HTML ページを構築するガイド付きプロンプト |
 | `figma_to_wcf` | Figma URL を入力に、`overview → tokens → component api → snippet → validate` の実行順を返す |
 
 ### Resources (`wcf://`)
 
 | URI | 説明 |
 |-----|------|
-| `wcf://components` | コンポーネントカタログのスナップショット |
+| `wcf://components` | コンポーネントカタログのスナップショット。プロトタイピング前の preload を推奨 |
 | `wcf://tokens` | トークン summary（type/category/themes/sample） |
 | `wcf://guidelines/{topic}` | topic 別ガイドライン要約（`accessibility`,`css`,`patterns`,`all`） |
 | `wcf://llms-full` | `llms-full.txt` の全文 |

package/core/cem.mjs

@@ -899,7 +899,7 @@ export function resolveDeclByComponent(indexes, component, prefix) {
   return undefined;
 }
 
-export function buildComponentNotFoundError(component, indexes, prefix) {
+export function buildComponentNotFoundError(component, indexes, prefix, installRegistry) {
   const comp = typeof component === 'string' ? component.trim() : '';
   const p = normalizePrefix(prefix);
   const suggestions = [];
@@ -916,8 +916,19 @@ export function buildComponentNotFoundError(component, indexes, prefix) {
     suggestions.push(suggested);
   }
 
-  const msg = suggestions.length > 0
-    ? `Component not found: ${comp}. Did you mean: ${suggestions.join(', ')}?`
-    : `Component not found: ${comp}`;
-  return { content: [{ type: 'text', text: msg }], isError: true };
+  const parts = [];
+  if (suggestions.length > 0) {
+    parts.push(`Component not found: ${comp}. Did you mean: ${suggestions.join(', ')}?`);
+  } else {
+    parts.push(`Component not found: ${comp}`);
+  }
+
+  const validIds = installRegistry?.components && typeof installRegistry.components === 'object'
+    ? Object.keys(installRegistry.components).sort()
+    : [];
+  if (validIds.length > 0) {
+    parts.push(`\nAvailable component IDs (${validIds.length}): ${validIds.join(', ')}`);
+  }
+
+  return { content: [{ type: 'text', text: parts.join('') }], isError: true };
 }

package/core/constants.mjs

@@ -81,6 +81,7 @@ export const CATEGORY_MAP = {
 };
 
 export const FIGMA_TO_WCF_PROMPT = 'figma_to_wcf';
+export const BUILD_PAGE_PROMPT = 'build_page';
 export const WCF_RESOURCE_URIS = Object.freeze({
   components: 'wcf://components',
   tokens: 'wcf://tokens',
@@ -94,6 +95,59 @@ const NPX_TEMPLATE = Object.freeze({
   args: ['@monoharada/wcf-mcp'],
 });
 
+/**
+ * Build the server-level instructions string sent to MCP clients on initialization.
+ * This enables AI agents to immediately understand what the server offers and how to
+ * build pages without any prior knowledge.
+ */
+export function buildServerInstructions(prefix, installRegistry, patterns) {
+  const components = installRegistry?.components && typeof installRegistry.components === 'object'
+    ? installRegistry.components : {};
+  const componentIds = Object.keys(components).sort();
+  const patternIds = patterns && typeof patterns === 'object'
+    ? Object.keys(patterns).sort() : [];
+
+  return [
+    '# wcf-mcp: DADS Web Components Design System MCP Server',
+    '',
+    '## Capabilities',
+    'This server provides a no-build / no-CDN Web Components design system.',
+    'You can generate complete HTML pages using MCP tools alone — no CLI installation required.',
+    '',
+    '## Quickest Workflow (build a page)',
+    '1. get_design_system_overview()',
+    '   → Inspect componentPatternMap before writing custom HTML/CSS',
+    '2. Read resource wcf://components',
+    '   → Preload the component catalog to avoid re-implementing existing components',
+    '3. get_pattern_recipe({ patternId: "<id>", include: ["fullPage"] })',
+    '   → Returns a complete <!DOCTYPE html> page in one call',
+    '4. validate_markup({ html: "<the full page HTML>" }) → Validate the full page (catches missing importmap / boot script)',
+    '5. Save the fullPageHtml result to a file and serve via HTTP',
+    '',
+    `## Available Pattern IDs (${patternIds.length})`,
+    patternIds.length > 0 ? patternIds.join(', ') : '(none)',
+    '',
+    `## Available Component IDs (${componentIds.length})`,
+    componentIds.length > 0 ? componentIds.join(', ') : '(none)',
+    '',
+    '## Custom Page Construction',
+    '1. get_design_system_overview() → review componentPatternMap',
+    '2. Read resource wcf://components → preload component catalog context',
+    '3. generate_usage_snippet({ component: "<componentId>" }) → Get HTML for each component',
+    '4. generate_full_page_html({ html: "<combined fragments>" }) → Wrap into a complete page',
+    '5. validate_markup({ html: "<the full page HTML>" }) → Validate the full page (catches missing importmap / boot script)',
+    '',
+    '## Important Notes',
+    '- No CDN exists. All files are served from a local vendor directory.',
+    `- CLI setup: npm install web-components-factory → npx wcf init --prefix ${prefix}`,
+    '- file:// protocol does not work. An HTTP server is required.',
+    '',
+    '## Prompts',
+    '- build_page: Guided prompt for building a no-build HTML page',
+    '- figma_to_wcf: Convert Figma designs to WCF implementation',
+  ].join('\n');
+}
+
 export const IDE_SETUP_TEMPLATES = Object.freeze([
   {
     ide: 'Claude Desktop',

package/core/plugins.mjs

@@ -41,6 +41,7 @@ export const BUILTIN_TOOL_NAMES = Object.freeze(new Set([
 ]));
 const BUILTIN_PROMPT_NAMES = Object.freeze(new Set([
   'figma_to_wcf',
+  'build_page',
 ]));
 const BUILTIN_RESOURCE_URIS = Object.freeze(new Set([
   'wcf://components',

package/core/prefix.mjs

@@ -111,7 +111,7 @@ export function buildDiagnosticSuggestion({ diagnostic, cemIndex, prefix }) {
   }
 
   if (code === 'forbiddenAttribute' && String(diagnostic?.attrName ?? '').toLowerCase() === 'placeholder') {
-    return 'Use aria-label or aria-describedby support text instead of placeholder.';
+    return 'Use support-text (attribute or slot), a visible label, and aria-describedby/aria-label where needed instead of placeholder. See: https://design.digital.go.jp/dads/components/input-text/accessibility/';
   }
 
   if (code === 'ariaLiveNotRecommended') {
@@ -130,6 +130,18 @@ export function buildDiagnosticSuggestion({ diagnostic, cemIndex, prefix }) {
     return diagnostic?.hint ?? 'Provide a meaningful aria-label value or use a visible <label> element.';
   }
 
+  if (
+    code === 'sortOnTh' ||
+    code === 'sortWrongTarget' ||
+    code === 'sortTypeOnWrongElement' ||
+    code === 'selectionControlWrongElement' ||
+    code === 'resourceListWholeLinkMissingInteraction' ||
+    code === 'nativePatternReplaceable' ||
+    code === 'customAnimationReplaceable'
+  ) {
+    return diagnostic?.hint ?? undefined;
+  }
+
   return undefined;
 }
 

package/core/register.mjs

@@ -6,7 +6,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import { CANONICAL_PREFIX, PACKAGE_VERSION, PLUGIN_TOOL_NOTICE, FIGMA_TO_WCF_PROMPT, WCF_RESOURCE_URIS, IDE_SETUP_TEMPLATES } from './constants.mjs';
+import { CANONICAL_PREFIX, PACKAGE_VERSION, PLUGIN_TOOL_NOTICE, FIGMA_TO_WCF_PROMPT, BUILD_PAGE_PROMPT, WCF_RESOURCE_URIS, IDE_SETUP_TEMPLATES } from './constants.mjs';
 import { normalizePrefix, withPrefix, toCanonicalTagName, getCategory, buildDiagnosticSuggestion, applyPrefixToHtml, applyPrefixToTagMap, mergeWithPrefixed } from './prefix.mjs';
 import { buildJsonToolResponse, buildJsonToolErrorResponse, expandQueryWithSynonyms, finalizeToolResult } from './response.mjs';
 import { normalizePlugins, buildPluginDataSourceMap, toPassthroughSchema } from './plugins.mjs';
@@ -130,6 +130,77 @@ function buildFigmaToWcfPromptText({ figmaUrl, userIntent }) {
   ].join('\n');
 }
 
+function buildBuildPagePromptText({ patternId, components: componentsCsv, userIntent, detectedPrefix, installRegistry, patterns }) {
+  const p = normalizePrefix(detectedPrefix);
+  const intent = String(userIntent ?? '').trim();
+  const registryComponents = installRegistry?.components && typeof installRegistry.components === 'object'
+    ? installRegistry.components : {};
+  const componentIds = Object.keys(registryComponents).sort();
+  const patternIds = patterns && typeof patterns === 'object'
+    ? Object.keys(patterns).sort() : [];
+
+  const lines = [
+    intent ? `Page goal: ${intent}` : 'Page goal: (not specified)',
+    '',
+  ];
+
+  // patternId takes priority over components when both are specified
+  if (patternId) {
+    lines.push(
+      '## Using a Pattern',
+      `1. get_pattern_recipe({ patternId: "${patternId}", include: ["fullPage"] })`,
+      '2. validate_markup({ html: "<the full page HTML>" }) — pass the entire page to catch missing importmap / boot script',
+      '3. Save the fullPageHtml to a .html file',
+      '',
+    );
+    if (componentsCsv) {
+      lines.push(
+        '> Note: patternId was specified, so the components argument is ignored. Remove patternId to use individual components instead.',
+        '',
+      );
+    }
+  } else if (componentsCsv) {
+    const ids = componentsCsv.split(',').map((s) => s.trim()).filter(Boolean);
+    lines.push(
+      '## Using Specific Components',
+      ...ids.map((id) => `- generate_usage_snippet({ component: "${id}" })`),
+      '- Combine the HTML fragments',
+      '- generate_full_page_html({ html: "<combined fragments>" }) → returns fullHtml',
+      '- validate_markup({ html: "<the full page HTML>" }) — pass the entire page to catch missing importmap / boot script',
+      '',
+    );
+  } else {
+    lines.push(
+      '## Workflow Options',
+      '',
+      '### Option A: Use a pattern (recommended)',
+      '1. get_pattern_recipe({ patternId: "<id>", include: ["fullPage"] })',
+      '2. validate_markup({ html: "<the full page HTML>" }) — pass the entire page to catch missing importmap / boot script',
+      '3. Save the fullPageHtml to a .html file',
+      '',
+      '### Option B: Build from individual components',
+      '1. generate_usage_snippet({ component: "<componentId>" }) for each component',
+      '2. Combine the HTML fragments',
+      '3. generate_full_page_html({ html: "<combined fragments>" }) → returns fullHtml',
+      '4. validate_markup({ html: "<the full page HTML>" }) — pass the entire page to catch missing importmap / boot script',
+      '',
+    );
+  }
+
+  lines.push(
+    `## Available Pattern IDs (${patternIds.length})`,
+    patternIds.length > 0 ? patternIds.join(', ') : '(none)',
+    '',
+    `## Available Component IDs (${componentIds.length})`,
+    componentIds.length > 0 ? componentIds.join(', ') : '(none)',
+    '',
+    '## CLI Vendor Setup (alternative)',
+    `npx web-components-factory init --prefix ${p} --dir .` + (patternId ? ` --pattern ${patternId}` : ''),
+  );
+
+  return lines.join('\n');
+}
+
 function escapeHtmlTitle(s) {
   return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 }
@@ -178,6 +249,71 @@ function scoreSearchFields(query, terms, fields) {
   return score;
 }
 
+function normalizeSearchText(value) {
+  return String(value ?? '').trim().toLowerCase();
+}
+
+function normalizeSearchTokens(value) {
+  return normalizeSearchText(value)
+    .split(/[^a-z0-9\u3040-\u30ff\u3400-\u9fff-]+/u)
+    .filter(Boolean);
+}
+
+function includesWholeToken(value, query) {
+  return normalizeSearchTokens(value).includes(normalizeSearchText(query));
+}
+
+function buildSelectorGuideComponentLookup(selectorGuideData) {
+  const lookup = new Map();
+  const categories = Array.isArray(selectorGuideData?.categories) ? selectorGuideData.categories : [];
+  for (const category of categories) {
+    const categoryKey = String(category?.key ?? '');
+    const components = Array.isArray(category?.components) ? category.components : [];
+    for (const component of components) {
+      const id = String(component?.id ?? '').trim();
+      const tagName = String(component?.tagName ?? '').trim().toLowerCase();
+      const useCase = String(component?.useCase ?? '');
+      const keywords = Array.isArray(component?.keywords) ? component.keywords.map((keyword) => String(keyword)) : [];
+      const entry = { id, tagName, useCase, keywords, categoryKey };
+      if (id) lookup.set(`id:${id}`, entry);
+      if (tagName) lookup.set(`tag:${tagName}`, entry);
+    }
+  }
+  return lookup;
+}
+
+function scoreSelectorGuideComponent(component, query) {
+  const q = normalizeSearchText(query);
+  if (!q) return 0;
+
+  const id = String(component?.id ?? '');
+  const tagName = String(component?.tagName ?? '').toLowerCase();
+  const useCase = String(component?.useCase ?? '');
+  const keywords = Array.isArray(component?.keywords) ? component.keywords : [];
+
+  if (id.toLowerCase() === q) return 120;
+  if (tagName === q || tagName === `dads-${q}`) return 115;
+  if (keywords.some((keyword) => normalizeSearchText(keyword) === q)) return 110;
+  if (includesWholeToken(useCase, q)) return 90;
+  if (keywords.some((keyword) => includesWholeToken(keyword, q))) return 85;
+  if (tagName.startsWith(q) || id.toLowerCase().startsWith(q)) return 70;
+  if (useCase.toLowerCase().includes(q)) return 40;
+  if (keywords.some((keyword) => normalizeSearchText(keyword).includes(q))) return 35;
+  if (tagName.includes(q) || id.toLowerCase().includes(q)) return 20;
+  return 0;
+}
+
+function buildOverviewPatternMap(selectorGuideData) {
+  const entries = Array.isArray(selectorGuideData?.componentPatternMap) ? selectorGuideData.componentPatternMap : [];
+  return entries.map((entry) => ({
+    pattern: String(entry?.pattern ?? ''),
+    componentIds: Array.isArray(entry?.componentIds) ? entry.componentIds.map((item) => String(item)) : [],
+    usage: typeof entry?.usage === 'string' ? entry.usage : undefined,
+    note: String(entry?.note ?? ''),
+    keywords: Array.isArray(entry?.keywords) ? entry.keywords.map((item) => String(item)) : [],
+  })).filter((entry) => entry.pattern && entry.componentIds.length > 0);
+}
+
 function detectKnowledgeIntentSources(query, terms) {
   const raw = `${query} ${terms.join(' ')}`.toLowerCase();
   const intents = new Set();
@@ -361,10 +497,12 @@ async function walkProjectFiles(rootDir) {
 function summarizeDiagnostics(diagnostics) {
   const errorCount = diagnostics.filter((diagnostic) => diagnostic.severity === 'error').length;
   const warningCount = diagnostics.filter((diagnostic) => diagnostic.severity === 'warning').length;
+  const infoCount = diagnostics.filter((diagnostic) => diagnostic.severity === 'info').length;
   return {
     total: diagnostics.length,
     errorCount,
     warningCount,
+    infoCount,
   };
 }
 
@@ -549,6 +687,7 @@ export function registerAll(context) {
     llmsFullText,
     tokenSuggestionMap,
     componentTokenRefMap,
+    selectorGuideData,
     plugins,
     loadJsonData,
     loadJson,
@@ -586,6 +725,10 @@ export function registerAll(context) {
       detectNonLowercaseAttributes,
       detectCdnReferences,
       detectMissingRuntimeScaffold,
+      detectTableAuthoringMisuse = () => [],
+      detectResourceListAuthoringMisuse = () => [],
+      detectReplaceableNativePatterns = () => [],
+      detectReplaceableAnimationPatterns = () => [],
     } = await loadValidator();
 
     const p = normalizePrefix(prefix);
@@ -686,6 +829,32 @@ export function registerAll(context) {
       severity: 'warning',
     });
 
+    const tableAuthoringDiagnostics = detectTableAuthoringMisuse({
+      filePath,
+      text,
+      prefix: p,
+      severity: 'warning',
+    });
+
+    const resourceListAuthoringDiagnostics = detectResourceListAuthoringMisuse({
+      filePath,
+      text,
+      prefix: p,
+      severity: 'warning',
+    });
+
+    const replaceableNativeDiagnostics = detectReplaceableNativePatterns({
+      filePath,
+      text,
+      prefix: p,
+    });
+
+    const replaceableAnimationDiagnostics = detectReplaceableAnimationPatterns({
+      filePath,
+      text,
+      prefix: p,
+    });
+
     const allRawDiagnostics = [
       ...cemDiagnostics,
       ...enumDiagnostics,
@@ -699,6 +868,10 @@ export function registerAll(context) {
       ...accessibilityDiagnostics,
       ...cdnDiagnostics,
       ...scaffoldDiagnostics,
+      ...tableAuthoringDiagnostics,
+      ...resourceListAuthoringDiagnostics,
+      ...replaceableNativeDiagnostics,
+      ...replaceableAnimationDiagnostics,
     ];
 
     for (const plugin of plugins) {
@@ -770,6 +943,32 @@ export function registerAll(context) {
     }),
   );
 
+  // -----------------------------------------------------------------------
+  // Prompt: build_page
+  // -----------------------------------------------------------------------
+  server.registerPrompt(
+    BUILD_PAGE_PROMPT,
+    {
+      title: 'Build Page',
+      description:
+        'Guided prompt for building a no-build HTML page from a pattern or component list.',
+      argsSchema: {
+        patternId: z.string().optional().describe('Pattern ID (e.g., "search-results", "card-grid"). Use list_patterns to see all.'),
+        components: z.string().optional().describe('Comma-separated component IDs if not using a pattern'),
+        userIntent: z.string().optional().describe('What the page should accomplish'),
+      },
+    },
+    async ({ patternId, components: componentsCsv, userIntent }) => ({
+      messages: [{
+        role: 'user',
+        content: {
+          type: 'text',
+          text: buildBuildPagePromptText({ patternId, components: componentsCsv, userIntent, detectedPrefix, installRegistry, patterns }),
+        },
+      }],
+    }),
+  );
+
   // -----------------------------------------------------------------------
   // Resource: wcf://components
   // -----------------------------------------------------------------------
@@ -926,6 +1125,7 @@ export function registerAll(context) {
         const cat = getCategory(tagName);
         categoryCount[cat] = (categoryCount[cat] ?? 0) + 1;
       }
+      const componentPatternMap = buildOverviewPatternMap(selectorGuideData);
 
       const patternList = Object.values(patterns).map((p) => ({
         id: p?.id,
@@ -940,6 +1140,7 @@ export function registerAll(context) {
         componentsByCategory: categoryCount,
         totalPatterns: patternList.length,
         patterns: patternList,
+        componentPatternMap,
         setupInfo: {
           npmPackage: 'web-components-factory',
           installCommand: 'npm install web-components-factory',
@@ -987,6 +1188,10 @@ export function registerAll(context) {
             name: FIGMA_TO_WCF_PROMPT,
             purpose: 'Figma-to-WCF conversion workflow prompt',
           },
+          {
+            name: BUILD_PAGE_PROMPT,
+            purpose: 'Build a no-build HTML page from a pattern or component list',
+          },
         ],
         availableResources: [
           { uri: WCF_RESOURCE_URIS.components, purpose: 'Component catalog snapshot' },
@@ -1017,10 +1222,10 @@ export function registerAll(context) {
           { name: 'get_component_selector_guide', purpose: 'Component selection guide by category and use case' },
         ],
         recommendedWorkflow: [
-          '1. get_design_system_overview → understand components, patterns, tokens, and IDE setup templates',
-          '2. figma_to_wcf (optional) → bootstrap the Figma-to-WCF tool sequence',
-          '3. search_design_system_knowledge → do a broad first-pass search across components, patterns, tokens, guidelines, and skills',
-          '4. wcf://components and wcf://tokens resources → preload catalog/token context',
+          '1. get_design_system_overview → start here and inspect componentPatternMap before creating custom HTML/CSS',
+          '2. wcf://components and wcf://tokens resources → preload the component/token catalog',
+          '3. figma_to_wcf (optional) → bootstrap the Figma-to-WCF tool sequence',
+          '4. search_design_system_knowledge → do a broad first-pass search across components, patterns, tokens, guidelines, and skills',
           '5. search_guidelines → find relevant guidelines',
           '6. get_design_tokens → get correct token values',
           '7. get_design_token_detail → inspect one token with references/referencedBy and usage examples',
@@ -1033,6 +1238,18 @@ export function registerAll(context) {
           '14. generate_full_page_html → wrap fragment into a complete preview-ready page',
           '15. get_install_recipe → get import/install instructions',
         ],
+        recommendedPreloadResources: [
+          {
+            uri: WCF_RESOURCE_URIS.components,
+            reason: 'Read this before prototyping to avoid re-implementing existing WCF components.',
+            when: 'Before generating page markup',
+          },
+          {
+            uri: WCF_RESOURCE_URIS.tokens,
+            reason: 'Read this before styling to avoid hard-coded token values.',
+            when: 'Before writing CSS or inline styles',
+          },
+        ],
         experimental: {
           plugins: {
             enabled: plugins.length > 0,
@@ -1160,6 +1377,12 @@ export function registerAll(context) {
           if (related.length > 0) api.relatedComponents = related;
           const a11y = extractAccessibilityChecklist(d, { prefix });
           if (a11y) api.accessibilityChecklist = a11y;
+          const interactionExamples = cTag ? INTERACTION_EXAMPLES_MAP[cTag] : undefined;
+          if (interactionExamples) api.interactionExamples = interactionExamples;
+          const layoutBehavior = cTag ? LAYOUT_BEHAVIOR_MAP[cTag] : undefined;
+          if (layoutBehavior) api.layoutBehavior = layoutBehavior;
+          const authoringGuidance = d?.custom?.authoringGuidance;
+          if (authoringGuidance) api.authoringGuidance = authoringGuidance;
           results.push(api);
         }
         return buildJsonToolResponse(results);
@@ -1179,7 +1402,7 @@ export function registerAll(context) {
 
       if (!decl) {
         const identifier = component || tagName || className || '';
-        return buildComponentNotFoundError(identifier, indexes, p);
+        return buildComponentNotFoundError(identifier, indexes, p, installRegistry);
       }
 
       const canonicalTag = typeof decl.tagName === 'string' ? decl.tagName.toLowerCase() : undefined;
@@ -1200,6 +1423,10 @@ export function registerAll(context) {
       if (accessibilityChecklist) {
         api.accessibilityChecklist = accessibilityChecklist;
       }
+      const authoringGuidance = decl?.custom?.authoringGuidance;
+      if (authoringGuidance) {
+        api.authoringGuidance = authoringGuidance;
+      }
       const interactionExamples = canonicalTag ? INTERACTION_EXAMPLES_MAP[canonicalTag] : undefined;
       if (interactionExamples) {
         api.interactionExamples = interactionExamples;
@@ -1232,7 +1459,7 @@ export function registerAll(context) {
       const decl = resolved?.decl;
 
       if (!decl) {
-        return buildComponentNotFoundError(component, indexes, p);
+        return buildComponentNotFoundError(component, indexes, p, installRegistry);
       }
 
       const canonicalTag = typeof decl.tagName === 'string' ? decl.tagName.toLowerCase() : undefined;
@@ -1265,10 +1492,7 @@ export function registerAll(context) {
       const decl = resolved?.decl;
 
       if (!decl) {
-        return {
-          content: [{ type: 'text', text: `Component not found: ${component}` }],
-          isError: true,
-        };
+        return buildComponentNotFoundError(component, indexes, p, installRegistry);
       }
 
       const canonicalTag = typeof decl.tagName === 'string' ? decl.tagName.toLowerCase() : undefined;
@@ -1588,13 +1812,13 @@ export function registerAll(context) {
       },
     },
     async ({ category, useCase }) => {
-      if (!context.selectorGuideData || !Array.isArray(context.selectorGuideData.categories)) {
+      if (!selectorGuideData || !Array.isArray(selectorGuideData.categories)) {
         return buildJsonToolErrorResponse({
           error: 'Component selector guide not available.',
         });
       }
 
-      let categories = context.selectorGuideData.categories;
+      let categories = selectorGuideData.categories;
 
       if (typeof category === 'string' && category.trim()) {
         const cat = category.trim().toLowerCase();
@@ -1602,15 +1826,35 @@ export function registerAll(context) {
       }
 
       if (typeof useCase === 'string' && useCase.trim()) {
-        const kw = useCase.trim().toLowerCase();
-        categories = categories.map((c) => ({
-          ...c,
-          components: c.components.filter((comp) =>
-            comp.useCase.toLowerCase().includes(kw) ||
-            comp.id.toLowerCase().includes(kw) ||
-            comp.tagName.toLowerCase().includes(kw)
-          ),
-        })).filter((c) => c.components.length > 0);
+        const scored = [];
+        for (const categoryEntry of categories) {
+          const components = Array.isArray(categoryEntry?.components) ? categoryEntry.components : [];
+          for (const component of components) {
+            const score = scoreSelectorGuideComponent(component, useCase);
+            if (score <= 0) continue;
+            scored.push({
+              categoryKey: categoryEntry.key,
+              component: { ...component, _score: score },
+            });
+          }
+        }
+
+        const grouped = new Map();
+        for (const hit of scored.sort((left, right) => right.component._score - left.component._score)) {
+          const list = grouped.get(hit.categoryKey) ?? [];
+          list.push(hit.component);
+          grouped.set(hit.categoryKey, list);
+        }
+
+        categories = categories
+          .map((categoryEntry) => ({
+            ...categoryEntry,
+            components: (grouped.get(categoryEntry.key) ?? []).map((component) => {
+              const { _score, ...rest } = component;
+              return rest;
+            }),
+          }))
+          .filter((categoryEntry) => categoryEntry.components.length > 0);
       }
 
       return buildJsonToolResponse({
@@ -2051,19 +2295,25 @@ export function registerAll(context) {
       const terms = expandQueryWithSynonyms(q).filter(Boolean);
       const limit = Number.isInteger(maxResults) ? maxResults : 10;
       const results = [];
+      const selectorGuideLookup = buildSelectorGuideComponentLookup(selectorGuideData);
 
       if (requestedSources.has('components')) {
         const page = buildComponentSummaries(indexes, {
-          query: q,
           limit: 200,
           prefix: p,
         });
         for (const item of page.items) {
+          const canonicalTagName = toCanonicalTagName(item.tagName, p) ?? item.tagName;
+          const guideEntry =
+            selectorGuideLookup.get(`tag:${String(canonicalTagName).toLowerCase()}`) ??
+            selectorGuideLookup.get(`id:${installRegistry?.tags?.[String(canonicalTagName).toLowerCase()] ?? ''}`);
           const score = scoreSearchFields(q, terms, [
             { text: item.tagName, weight: 5 },
             { text: item.className, weight: 4 },
             { text: item.description, weight: 2 },
             { text: item.category, weight: 1 },
+            { text: guideEntry?.useCase, weight: 4 },
+            { text: Array.isArray(guideEntry?.keywords) ? guideEntry.keywords.join(' ') : '', weight: 5 },
           ]);
           if (score <= 0) continue;
           results.push({
@@ -2074,6 +2324,8 @@ export function registerAll(context) {
             metadata: {
               className: item.className,
               category: item.category,
+              useCase: guideEntry?.useCase,
+              keywords: guideEntry?.keywords ?? [],
             },
             score: score + getKnowledgeSourceBoost('components', q, terms),
           });