@monoharada/wcf-mcp 0.1.2 → 0.2.0

package/core.mjs

@@ -6,7 +6,7 @@
  * and helper functions live in exactly one place.
  */
 
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 
 // ---------------------------------------------------------------------------
@@ -17,6 +17,8 @@ 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 PLUGIN_TOOL_NOTICE = 'Plugin tool (contract v1).';
+export const PLUGIN_CONTRACT_VERSION = '1.0.0';
 
 export const CATEGORY_MAP = {
   'dads-input-text': 'Form',
@@ -85,6 +87,32 @@ export const CATEGORY_MAP = {
 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 TOKEN_THEMES = Object.freeze(new Set(['light', 'dark', 'all']));
+const GUIDELINE_TOPICS = Object.freeze(['accessibility', 'css', 'patterns', 'all']);
+const GUIDELINE_TOPIC_SET = Object.freeze(new Set(GUIDELINE_TOPICS));
+const PLUGIN_DATA_SOURCE_KEYS = Object.freeze(new Set([
+  'custom-elements.json',
+  'install-registry.json',
+  'pattern-registry.json',
+  'design-tokens.json',
+  'guidelines-index.json',
+]));
+const BUILTIN_TOOL_NAMES = Object.freeze(new Set([
+  'get_design_system_overview',
+  'list_components',
+  'search_icons',
+  'get_component_api',
+  'generate_usage_snippet',
+  'get_install_recipe',
+  'validate_markup',
+  'list_patterns',
+  'get_pattern_recipe',
+  'generate_pattern_snippet',
+  'get_design_tokens',
+  'get_design_token_detail',
+  'get_accessibility_docs',
+  'search_guidelines',
+]));
 const A11Y_CATEGORY_LEVEL_MAP = Object.freeze({
   semantics: 'A',
   keyboard: 'A',
@@ -99,6 +127,40 @@ const NPX_TEMPLATE = Object.freeze({
   command: 'npx',
   args: ['@monoharada/wcf-mcp'],
 });
+export const FIGMA_TO_WCF_PROMPT = 'figma_to_wcf';
+export const WCF_RESOURCE_URIS = Object.freeze({
+  components: 'wcf://components',
+  tokens: 'wcf://tokens',
+  guidelinesTemplate: 'wcf://guidelines/{topic}',
+  llmsFull: 'wcf://llms-full',
+});
+
+// Unidirectional synonym table: key → expands to include these terms (DIG-09)
+// Searching "keyboard" also matches "focus", "tab" etc. but NOT reverse.
+const SYNONYM_TABLE = new Map([
+  ['aria-live', ['role=alert', 'aria-describedby', 'live region', 'error text']],
+  ['keyboard', ['focus', 'tab', 'tabindex', 'key event', 'focus trap']],
+  ['contrast', ['color', 'wcag', 'color contrast']],
+  ['spacing', ['margin', 'padding', 'gap', 'spacing token']],
+  ['skip-navigation', ['skip-link', 'landmark', 'skip nav']],
+  ['heading', ['heading hierarchy', 'h1', 'heading level']],
+  ['form', ['input', 'validation', 'required', 'label']],
+]);
+
+export function expandQueryWithSynonyms(query) {
+  const q = String(query ?? '').toLowerCase().trim();
+  if (!q) return [q];
+  const terms = [q];
+  for (const [key, synonyms] of SYNONYM_TABLE) {
+    if (q.includes(key)) {
+      for (const syn of synonyms) {
+        if (!terms.includes(syn)) terms.push(syn);
+      }
+    }
+  }
+  return terms;
+}
+
 export const IDE_SETUP_TEMPLATES = Object.freeze([
   {
     ide: 'Claude Desktop',
@@ -127,6 +189,24 @@ export const IDE_SETUP_TEMPLATES = Object.freeze([
       },
     },
   },
+  {
+    ide: 'VS Code (GitHub Copilot)',
+    configPath: '.vscode/mcp.json',
+    snippet: {
+      mcpServers: {
+        wcf: NPX_TEMPLATE,
+      },
+    },
+  },
+  {
+    ide: 'Windsurf',
+    configPath: '.windsurf/mcp_config.json',
+    snippet: {
+      mcpServers: {
+        wcf: NPX_TEMPLATE,
+      },
+    },
+  },
 ]);
 
 export function isStructuredContentDisabled(env = process.env) {
@@ -204,6 +284,406 @@ export function buildTokenSuggestionMap(designTokensData) {
   return out;
 }
 
+export function normalizeTokenIdentifier(value) {
+  const raw = String(value ?? '').trim().toLowerCase();
+  if (!raw) return '';
+  const cssVariable = normalizeCssVariable(raw);
+  if (cssVariable) return cssVariable;
+  if (raw.startsWith('--')) return raw;
+  return `--${raw.replace(/^[-]+/, '')}`;
+}
+
+export function resolveTokenTheme(theme) {
+  const requested = String(theme ?? 'light').trim().toLowerCase() || 'light';
+  if (!TOKEN_THEMES.has(requested)) {
+    return {
+      ok: false,
+      errorCode: 'INVALID_THEME',
+      message: `Unsupported theme: ${requested}. Allowed values are light, dark, all.`,
+    };
+  }
+  if (requested !== 'light') {
+    return {
+      ok: false,
+      errorCode: 'INVALID_THEME',
+      message: `Theme "${requested}" is not available yet. Use theme="light" (NG-06).`,
+    };
+  }
+  return {
+    ok: true,
+    requested,
+    resolved: 'light',
+    available: ['light'],
+  };
+}
+
+export function extractReferencedTokenNames(value) {
+  if (typeof value !== 'string') return [];
+  const refs = [];
+  const re = /var\(\s*(--[^,\s)]+)\s*(?:,\s*[^)]+)?\)/g;
+  let match;
+  while ((match = re.exec(value))) {
+    const tokenName = normalizeTokenIdentifier(match[1]);
+    if (tokenName) refs.push(tokenName);
+  }
+  return [...new Set(refs)];
+}
+
+export function buildTokenRelationshipIndex(designTokensData) {
+  const byToken = {};
+  const tokens = Array.isArray(designTokensData?.tokens) ? designTokensData.tokens : [];
+  const fromData = designTokensData?.relationships?.byToken;
+  if (fromData && typeof fromData === 'object') {
+    for (const [rawName, rawRel] of Object.entries(fromData)) {
+      const name = normalizeTokenIdentifier(rawName);
+      if (!name) continue;
+      const refs = Array.isArray(rawRel?.references)
+        ? rawRel.references.map((r) => normalizeTokenIdentifier(r)).filter(Boolean)
+        : [];
+      const referencedBy = Array.isArray(rawRel?.referencedBy)
+        ? rawRel.referencedBy.map((r) => normalizeTokenIdentifier(r)).filter(Boolean)
+        : [];
+      byToken[name] = {
+        references: [...new Set(refs)].sort(),
+        referencedBy: [...new Set(referencedBy)].sort(),
+      };
+    }
+  }
+
+  if (Object.keys(byToken).length > 0) {
+    return { byToken };
+  }
+
+  for (const token of tokens) {
+    const name = normalizeTokenIdentifier(token?.name);
+    if (!name) continue;
+    if (!byToken[name]) byToken[name] = { references: [], referencedBy: [] };
+    const refs = extractReferencedTokenNames(token?.value);
+    byToken[name].references = refs;
+  }
+
+  for (const [sourceName, relation] of Object.entries(byToken)) {
+    for (const refName of relation.references) {
+      if (!byToken[refName]) byToken[refName] = { references: [], referencedBy: [] };
+      byToken[refName].referencedBy.push(sourceName);
+    }
+  }
+
+  for (const relation of Object.values(byToken)) {
+    relation.references = [...new Set(relation.references)].sort();
+    relation.referencedBy = [...new Set(relation.referencedBy)].sort();
+  }
+
+  return { byToken };
+}
+
+function toTokenSummary(token) {
+  return {
+    name: String(token?.name ?? ''),
+    value: String(token?.value ?? ''),
+    type: String(token?.type ?? ''),
+    category: String(token?.category ?? ''),
+    cssVariable: String(token?.cssVariable ?? ''),
+  };
+}
+
+export function suggestTokenNames(targetName, tokens, maxSuggestions = 5) {
+  const target = normalizeTokenIdentifier(targetName);
+  if (!target) return [];
+  const allNames = [...new Set(tokens
+    .map((token) => normalizeTokenIdentifier(token?.name))
+    .filter(Boolean))];
+
+  const startsWith = allNames.filter((name) => name.startsWith(target));
+  if (startsWith.length >= maxSuggestions) return startsWith.slice(0, maxSuggestions);
+
+  const includes = allNames.filter((name) => name.includes(target) && !startsWith.includes(name));
+  const ranked = allNames
+    .filter((name) => !startsWith.includes(name) && !includes.includes(name))
+    .map((name) => ({ name, distance: levenshteinDistance(target, name) }))
+    .sort((left, right) => left.distance - right.distance || left.name.localeCompare(right.name))
+    .map((entry) => entry.name);
+
+  return [...startsWith, ...includes, ...ranked].slice(0, maxSuggestions);
+}
+
+function buildUsageExamples(token) {
+  const cssVar = String(token?.cssVariable ?? '');
+  const type = String(token?.type ?? '').toLowerCase();
+  if (!cssVar) return [];
+  if (type === 'color') {
+    return [
+      `.example { color: ${cssVar}; }`,
+      `.example { background-color: ${cssVar}; }`,
+    ];
+  }
+  if (type === 'spacing') {
+    return [
+      `.example { padding: ${cssVar}; }`,
+      `.example { gap: ${cssVar}; }`,
+    ];
+  }
+  if (type === 'typography') {
+    return [
+      `.example { font-size: ${cssVar}; }`,
+      `.example { line-height: ${cssVar}; }`,
+    ];
+  }
+  if (type === 'radius') {
+    return [`.example { border-radius: ${cssVar}; }`];
+  }
+  if (type === 'shadow') {
+    return [`.example { box-shadow: ${cssVar}; }`];
+  }
+  return [`.example { --token-value: ${cssVar}; }`];
+}
+
+function buildTokenErrorPayload(code, message, extra = {}) {
+  return {
+    isError: true,
+    payload: {
+      error: { code, message },
+      ...extra,
+    },
+  };
+}
+
+export function buildDesignTokenDetailPayload(designTokensData, name, theme) {
+  if (!Array.isArray(designTokensData?.tokens)) {
+    return buildTokenErrorPayload(
+      'DESIGN_TOKENS_DATA_UNAVAILABLE',
+      'Design tokens data not available. Run: npm run mcp:extract-tokens',
+    );
+  }
+
+  const themeInfo = resolveTokenTheme(theme);
+  if (!themeInfo.ok) {
+    return buildTokenErrorPayload(themeInfo.errorCode, themeInfo.message);
+  }
+
+  const normalizedName = normalizeTokenIdentifier(name);
+  if (!normalizedName) {
+    return buildTokenErrorPayload('INVALID_TOKEN_INPUT', 'Token name is required.');
+  }
+
+  const tokens = designTokensData.tokens;
+  const token = tokens.find((item) => normalizeTokenIdentifier(item?.name) === normalizedName);
+  if (!token) {
+    return buildTokenErrorPayload(
+      'TOKEN_NOT_FOUND',
+      `Token not found: ${normalizedName}`,
+      { suggestions: suggestTokenNames(normalizedName, tokens) },
+    );
+  }
+
+  const relationshipIndex = buildTokenRelationshipIndex(designTokensData);
+  const relation = relationshipIndex.byToken[normalizedName] ?? { references: [], referencedBy: [] };
+  const tokenByName = new Map(tokens
+    .map((item) => [normalizeTokenIdentifier(item?.name), item])
+    .filter(([tokenName]) => tokenName));
+  const references = relation.references
+    .map((tokenName) => tokenByName.get(tokenName))
+    .filter(Boolean)
+    .map(toTokenSummary);
+  const referencedBy = relation.referencedBy
+    .map((tokenName) => tokenByName.get(tokenName))
+    .filter(Boolean)
+    .map(toTokenSummary);
+  const relatedTokens = referencedBy
+    .filter((item) => String(item.category).toLowerCase() === 'semantic')
+    .map((item) => item.name);
+
+  return {
+    isError: false,
+    payload: {
+      token: {
+        ...toTokenSummary(token),
+        group: token?.group ?? null,
+      },
+      references,
+      referencedBy,
+      relatedTokens,
+      usageExamples: buildUsageExamples(token),
+      theme: {
+        requested: themeInfo.requested,
+        resolved: themeInfo.resolved,
+        available: themeInfo.available,
+      },
+    },
+  };
+}
+
+export function buildDesignTokensPayload(designTokensData, { type, category, query, theme } = {}) {
+  if (!designTokensData) {
+    return buildTokenErrorPayload(
+      'DESIGN_TOKENS_DATA_UNAVAILABLE',
+      'Design tokens data not available. Run: npm run mcp:extract-tokens',
+    );
+  }
+
+  const themeInfo = resolveTokenTheme(theme);
+  if (!themeInfo.ok) {
+    return buildTokenErrorPayload(themeInfo.errorCode, themeInfo.message);
+  }
+
+  let tokens = Array.isArray(designTokensData.tokens) ? designTokensData.tokens : [];
+  if (type) tokens = tokens.filter((t) => t.type === type);
+  if (category) tokens = tokens.filter((t) => t.category === category);
+  if (query) {
+    const q = String(query).toLowerCase();
+    tokens = tokens.filter((t) => String(t.name ?? '').toLowerCase().includes(q));
+  }
+
+  return {
+    isError: false,
+    payload: {
+      total: tokens.length,
+      tokens,
+      summary: designTokensData.summary,
+      theme: {
+        requested: themeInfo.requested,
+        resolved: themeInfo.resolved,
+        available: themeInfo.available,
+      },
+    },
+  };
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function toPluginErrorMessage(name, reason) {
+  return `Invalid plugin (${name}): ${reason}`;
+}
+
+/**
+ * Plugin contract v1 — stable interface. See docs/plugin-contract-v1.md.
+ * @typedef {{
+ *   fileName: string,
+ *   path: string,
+ * }} WcfMcpDataSourceConfig
+ */
+
+/**
+ * Plugin contract v1 — stable interface. See docs/plugin-contract-v1.md.
+ * @typedef {{
+ *   name: string,
+ *   description?: string,
+ *   inputSchema?: Record<string, unknown>,
+ *   handler?: (args: Record<string, unknown>, context: { plugin: { name: string, version: string }, helpers: { loadJsonData: Function } }) => unknown,
+ *   staticPayload?: unknown,
+ * }} WcfMcpPluginTool
+ */
+
+/**
+ * Plugin contract v1 — stable interface. See docs/plugin-contract-v1.md.
+ * @typedef {{
+ *   name: string,
+ *   version: string,
+ *   tools?: WcfMcpPluginTool[],
+ *   dataSources?: WcfMcpDataSourceConfig[],
+ * }} WcfMcpPlugin
+ */
+
+function normalizePluginDataSources(pluginName, dataSources) {
+  if (!Array.isArray(dataSources)) return [];
+  const out = [];
+  for (const entry of dataSources) {
+    if (!isPlainObject(entry)) {
+      throw new Error(toPluginErrorMessage(pluginName, 'dataSources entries must be objects'));
+    }
+    const fileName = String(entry.fileName ?? '').trim();
+    const sourcePath = String(entry.path ?? '').trim();
+    if (!fileName || !sourcePath) {
+      throw new Error(toPluginErrorMessage(pluginName, 'dataSources entries require fileName and path'));
+    }
+    if (!PLUGIN_DATA_SOURCE_KEYS.has(fileName)) {
+      throw new Error(toPluginErrorMessage(pluginName, `unsupported data source key: ${fileName}`));
+    }
+    out.push({ fileName, path: sourcePath });
+  }
+  return out;
+}
+
+function normalizePluginTools(pluginName, tools) {
+  if (!Array.isArray(tools)) return [];
+  const out = [];
+  for (const rawTool of tools) {
+    if (!isPlainObject(rawTool)) {
+      throw new Error(toPluginErrorMessage(pluginName, 'tools entries must be objects'));
+    }
+    const name = String(rawTool.name ?? '').trim();
+    if (!name) throw new Error(toPluginErrorMessage(pluginName, 'tool.name is required'));
+    const hasHandler = typeof rawTool.handler === 'function';
+    const hasStaticPayload = Object.prototype.hasOwnProperty.call(rawTool, 'staticPayload');
+    if (!hasHandler && !hasStaticPayload) {
+      throw new Error(toPluginErrorMessage(pluginName, `tool "${name}" needs handler or staticPayload`));
+    }
+    // When both are specified, handler takes priority (contract v1: handler-wins)
+    // staticPayload is ignored silently.
+    const description = String(rawTool.description ?? '').trim() ||
+      `Plugin tool provided by ${pluginName}. ${PLUGIN_TOOL_NOTICE}`;
+    const inputSchema = isPlainObject(rawTool.inputSchema) ? rawTool.inputSchema : {};
+    out.push({
+      name,
+      description,
+      inputSchema,
+      handler: hasHandler ? rawTool.handler : undefined,
+      staticPayload: hasStaticPayload ? rawTool.staticPayload : undefined,
+    });
+  }
+  return out;
+}
+
+export function normalizePlugins(plugins = []) {
+  if (!Array.isArray(plugins)) throw new Error('Invalid plugin configuration: plugins must be an array');
+  const normalized = [];
+  const seenPluginNames = new Set();
+  const seenToolNames = new Set(BUILTIN_TOOL_NAMES);
+
+  for (const rawPlugin of plugins) {
+    if (!isPlainObject(rawPlugin)) throw new Error('Invalid plugin configuration: each plugin must be an object');
+    const name = String(rawPlugin.name ?? '').trim();
+    const version = String(rawPlugin.version ?? '').trim();
+    if (!name || !version) throw new Error('Invalid plugin configuration: plugin.name and plugin.version are required');
+    if (seenPluginNames.has(name)) throw new Error(`Duplicate plugin name: ${name}`);
+    seenPluginNames.add(name);
+
+    const tools = normalizePluginTools(name, rawPlugin.tools);
+    for (const tool of tools) {
+      if (seenToolNames.has(tool.name)) {
+        throw new Error(toPluginErrorMessage(name, `tool name collision: ${tool.name}`));
+      }
+      seenToolNames.add(tool.name);
+    }
+
+    const dataSources = normalizePluginDataSources(name, rawPlugin.dataSources);
+    normalized.push({ name, version, tools, dataSources });
+  }
+
+  return normalized;
+}
+
+export function buildPluginDataSourceMap(plugins = []) {
+  const out = new Map();
+  for (const plugin of plugins) {
+    const pluginName = String(plugin?.name ?? 'unknown-plugin');
+    const dataSources = Array.isArray(plugin?.dataSources) ? plugin.dataSources : [];
+    for (const source of dataSources) {
+      const fileName = String(source?.fileName ?? '').trim();
+      const sourcePath = String(source?.path ?? '').trim();
+      if (!fileName || !sourcePath) continue;
+      if (out.has(fileName)) {
+        const prev = out.get(fileName);
+        throw new Error(`Duplicate data source override for ${fileName} (${prev.pluginName}, ${pluginName})`);
+      }
+      out.set(fileName, { path: sourcePath, pluginName });
+    }
+  }
+  return out;
+}
+
 // ---------------------------------------------------------------------------
 // Helpers (exported for testing)
 // ---------------------------------------------------------------------------
@@ -480,18 +960,29 @@ export function findDeclByComponentId(indexes, componentIdRaw) {
   return undefined;
 }
 
-export function applyPrefixToCemIndex(cemIndex, prefix) {
+/**
+ * Generic helper: remap tag-keyed Map to a different prefix.
+ * Used by validate_markup to build prefix-aware CEM/enum/slot maps.
+ */
+export function applyPrefixToTagMap(map, prefix) {
   const p = normalizePrefix(prefix);
-  if (p === CANONICAL_PREFIX) return cemIndex;
+  if (p === CANONICAL_PREFIX) return map;
 
   const out = new Map();
-  for (const [tag, meta] of cemIndex.entries()) {
-    const nextTag = withPrefix(tag, p);
-    out.set(nextTag, meta);
+  for (const [tag, value] of map.entries()) {
+    out.set(withPrefix(tag, p), value);
   }
   return out;
 }
 
+function mergeWithPrefixed(canonicalMap, prefix) {
+  const prefixed = applyPrefixToTagMap(canonicalMap, prefix);
+  if (prefixed === canonicalMap) return canonicalMap;
+  const combined = new Map(canonicalMap);
+  for (const [k, v] of prefixed.entries()) combined.set(k, v);
+  return combined;
+}
+
 export function applyPrefixToHtml(html, prefix) {
   const p = normalizePrefix(prefix);
   if (p === CANONICAL_PREFIX) return String(html ?? '');
@@ -534,7 +1025,8 @@ export function resolveComponentClosure({ installRegistry }, componentIds) {
 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 limitExplicit = Number.isInteger(limit);
+  const pageSize = limitExplicit ? Math.max(1, Math.min(limit, 200)) : 20;
   const pageOffset = Number.isInteger(offset) ? Math.max(0, offset) : 0;
 
   let items = indexes.decls.map(({ decl, tagName, modulePath }) => ({
@@ -565,13 +1057,20 @@ export function buildComponentSummaries(indexes, { category, query, limit, offse
   const total = items.length;
   const paged = items.slice(pageOffset, pageOffset + pageSize);
 
-  return {
+  const result = {
     total,
     limit: pageSize,
     offset: pageOffset,
     hasMore: pageOffset + paged.length < total,
     items: paged,
   };
+
+  // DIG-19: Add migration notice when limit is not explicitly provided
+  if (!limitExplicit && total > pageSize) {
+    result._notice = 'Default pagination changed to 20 items. Set limit:200 for all results.';
+  }
+
+  return result;
 }
 
 export function parseIconNamesFromDescription(description) {
@@ -897,6 +1396,123 @@ export function queryAccessibilityIndex(
   };
 }
 
+function buildComponentsResourcePayload(indexes) {
+  const page = buildComponentSummaries(indexes, { limit: 200 });
+  const componentsByCategory = {};
+  for (const item of page.items) {
+    const category = String(item?.category ?? 'Other');
+    componentsByCategory[category] = (componentsByCategory[category] ?? 0) + 1;
+  }
+  return {
+    total: page.total,
+    componentsByCategory,
+    components: page.items,
+  };
+}
+
+function buildTokensResourcePayload(designTokensData) {
+  if (!Array.isArray(designTokensData?.tokens)) {
+    return {
+      isError: true,
+      error: {
+        code: 'DESIGN_TOKENS_DATA_UNAVAILABLE',
+        message: 'Design tokens data not available. Run: npm run mcp:extract-tokens',
+      },
+    };
+  }
+
+  const tokens = designTokensData.tokens;
+  const tokenTypes = [...new Set(tokens
+    .map((token) => String(token?.type ?? '').trim())
+    .filter(Boolean))].sort();
+  const tokenCategories = [...new Set(tokens
+    .map((token) => String(token?.category ?? '').trim())
+    .filter(Boolean))].sort();
+
+  return {
+    isError: false,
+    payload: {
+      total: tokens.length,
+      summary: designTokensData.summary ?? {},
+      themes: designTokensData.themes ?? { default: 'light', available: ['light'] },
+      tokenTypes,
+      tokenCategories,
+      sample: tokens.slice(0, 20).map(toTokenSummary),
+    },
+  };
+}
+
+function buildGuidelinesResourcePayload(guidelinesIndexData, rawTopic) {
+  const topic = String(rawTopic ?? '').trim().toLowerCase();
+  if (!GUIDELINE_TOPIC_SET.has(topic)) {
+    return {
+      isError: true,
+      error: {
+        code: 'INVALID_GUIDELINE_TOPIC',
+        message: `Unsupported topic: ${topic}. Allowed values are ${GUIDELINE_TOPICS.join(', ')}.`,
+      },
+    };
+  }
+
+  if (!Array.isArray(guidelinesIndexData?.documents)) {
+    return {
+      isError: true,
+      error: {
+        code: 'GUIDELINES_INDEX_UNAVAILABLE',
+        message: 'Guidelines index not available. Run: npm run mcp:index-guidelines',
+      },
+    };
+  }
+
+  const documents = guidelinesIndexData.documents
+    .filter((doc) => topic === 'all' || String(doc?.topic ?? '').toLowerCase() === topic)
+    .map((doc) => {
+      const sections = Array.isArray(doc?.sections) ? doc.sections : [];
+      return {
+        id: String(doc?.id ?? ''),
+        title: String(doc?.title ?? ''),
+        topic: String(doc?.topic ?? ''),
+        sectionCount: sections.length,
+        sections: sections.map((section) => ({
+          heading: String(section?.heading ?? ''),
+          startLine: Number.isInteger(section?.startLine) ? section.startLine : undefined,
+        })),
+      };
+    });
+
+  return {
+    isError: false,
+    payload: {
+      topic,
+      totalDocuments: documents.length,
+      topicCounts: guidelinesIndexData.topicCounts ?? {},
+      documents,
+    },
+  };
+}
+
+function buildFigmaToWcfPromptText({ figmaUrl, userIntent }) {
+  const url = String(figmaUrl ?? '').trim();
+  const intent = String(userIntent ?? '').trim();
+
+  return [
+    `Figma URL: ${url}`,
+    intent ? `Implementation goal: ${intent}` : 'Implementation goal: (not specified)',
+    '',
+    'Use the workflow below in this exact order:',
+    '1. get_design_system_overview',
+    '2. get_design_tokens',
+    '3. get_component_api',
+    '4. generate_usage_snippet (or get_pattern_recipe)',
+    '5. validate_markup',
+    '',
+    'Output requirements:',
+    '- Split the UI into sections before writing code.',
+    '- For each section, name concrete components and token variables.',
+    '- Provide final validation notes and required fixes.',
+  ].join('\n');
+}
+
 function resolveDeclByComponent(indexes, component, prefix) {
   const byTagOrClass =
     pickDecl(indexes, { tagName: component, prefix }) ??
@@ -909,7 +1525,50 @@ function resolveDeclByComponent(indexes, component, prefix) {
     };
   }
 
-  return findDeclByComponentId(indexes, component);
+  const byComponentId = findDeclByComponentId(indexes, component);
+  if (byComponentId) return byComponentId;
+
+  // Auto-prefix: try with canonical prefix if bare name was given (DIG-15)
+  const comp = typeof component === 'string' ? component.trim().toLowerCase() : '';
+  const p = normalizePrefix(prefix);
+  if (comp && !comp.startsWith(p)) {
+    const prefixed = `${p}-${comp}`;
+    const byPrefixed = pickDecl(indexes, { tagName: prefixed, prefix: p });
+    if (byPrefixed) {
+      const canonicalTag = typeof byPrefixed.tagName === 'string' ? byPrefixed.tagName.toLowerCase() : undefined;
+      return {
+        decl: byPrefixed,
+        modulePath: canonicalTag ? indexes.modulePathByTag.get(canonicalTag) : undefined,
+      };
+    }
+  }
+
+  return undefined;
+}
+
+function buildComponentNotFoundError(component, indexes, prefix) {
+  const comp = typeof component === 'string' ? component.trim() : '';
+  const p = normalizePrefix(prefix);
+  const suggestions = [];
+
+  // Try suggesting with prefix
+  if (comp && !comp.toLowerCase().startsWith(p)) {
+    const prefixed = `${p}-${comp.toLowerCase()}`;
+    if (indexes.byTag.has(prefixed)) {
+      suggestions.push(prefixed);
+    }
+  }
+
+  // Levenshtein-based suggestion
+  const suggested = suggestUnknownElementTagName(comp.includes('-') ? comp : `${p}-${comp}`, indexes.byTag);
+  if (suggested && !suggestions.includes(suggested)) {
+    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 };
 }
 
 // ---------------------------------------------------------------------------
@@ -918,45 +1577,210 @@ function resolveDeclByComponent(indexes, component, prefix) {
 //
 //   loadJsonData(fileName: string) → Promise<object>
 //   loadValidator() → Promise<{ collectCemCustomElements, validateTextAgainstCem }>
+//   options?: {
+//     plugins?: WcfMcpPlugin[],
+//     loadJsonDataFromPath?: (path: string, fileName: string, pluginName?: string) => Promise<object>
+//     loadTextData?: (fileName: string) => Promise<string>
+//   }
 // ---------------------------------------------------------------------------
 
-export async function createMcpServer(loadJsonData, loadValidator) {
-  const manifest = await loadJsonData('custom-elements.json');
+export async function createMcpServer(loadJsonData, loadValidator, options = {}) {
+  const plugins = normalizePlugins(options?.plugins ?? []);
+  const pluginDataSourceMap = buildPluginDataSourceMap(plugins);
+  const loadJsonDataFromPath = typeof options?.loadJsonDataFromPath === 'function'
+    ? options.loadJsonDataFromPath
+    : null;
+  const loadTextData = typeof options?.loadTextData === 'function'
+    ? options.loadTextData
+    : null;
+
+  const loadJson = async (fileName) => {
+    const override = pluginDataSourceMap.get(fileName);
+    if (!override) return loadJsonData(fileName);
+    if (!loadJsonDataFromPath) {
+      throw new Error(`Plugin data source override for ${fileName} requires loadJsonDataFromPath`);
+    }
+    return loadJsonDataFromPath(override.path, fileName, override.pluginName);
+  };
+  const loadText = async (fileName) => {
+    if (!loadTextData) throw new Error(`Text data loader not configured for ${fileName}`);
+    return loadTextData(fileName);
+  };
+
+  const manifest = await loadJson('custom-elements.json');
   const indexes = buildIndexes(manifest);
   const {
     collectCemCustomElements,
     validateTextAgainstCem,
     detectTokenMisuseInInlineStyles = () => [],
     detectAccessibilityMisuseInMarkup = () => [],
+    buildEnumAttributeMap = () => new Map(),
+    detectEnumValueMisuse = () => [],
+    buildSlotNameMap = () => new Map(),
+    detectInvalidSlotName = () => [],
+    detectMissingRequiredAttributes = () => [],
+    detectOrphanedChildComponents = () => [],
+    detectEmptyInteractiveElement = () => [],
   } = await loadValidator();
   const canonicalCemIndex = collectCemCustomElements(manifest);
-  const installRegistry = await loadJsonData('install-registry.json');
-  const patternRegistry = await loadJsonData('pattern-registry.json');
+  const canonicalEnumMap = buildEnumAttributeMap(manifest);
+  const canonicalSlotMap = buildSlotNameMap(manifest);
+  const installRegistry = await loadJson('install-registry.json');
+  const patternRegistry = await loadJson('pattern-registry.json');
   const { patterns } = loadPatternRegistryShape(patternRegistry);
   const relatedComponentMap = buildRelatedComponentMap(installRegistry, patterns);
 
   // Load optional data files (design tokens, guidelines index)
   let designTokensData = null;
   try {
-    designTokensData = await loadJsonData('design-tokens.json');
+    designTokensData = await loadJson('design-tokens.json');
   } catch {
     // design-tokens.json may not exist yet
   }
 
   let guidelinesIndexData = null;
   try {
-    guidelinesIndexData = await loadJsonData('guidelines-index.json');
+    guidelinesIndexData = await loadJson('guidelines-index.json');
   } catch {
     // guidelines-index.json may not exist yet
   }
+  let llmsFullText = null;
+  try {
+    llmsFullText = await loadText('llms-full.txt');
+  } catch {
+    // llms-full.txt may not exist in local setup
+  }
 
   const tokenSuggestionMap = buildTokenSuggestionMap(designTokensData);
 
   const server = new McpServer({
     name: 'web-components-factory-design-system',
-    version: '0.1.1',
+    version: '0.2.0',
   });
 
+  server.registerPrompt(
+    FIGMA_TO_WCF_PROMPT,
+    {
+      title: 'Figma To WCF',
+      description:
+        'Guided prompt for converting a Figma URL into WCF implementation steps with a strict tool order.',
+      argsSchema: {
+        figmaUrl: z.string().trim().url().describe('Figma URL (design or board link)'),
+        userIntent: z.string().optional().describe('Optional implementation intent / screen purpose'),
+      },
+    },
+    async ({ figmaUrl, userIntent }) => ({
+      messages: [{
+        role: 'user',
+        content: {
+          type: 'text',
+          text: buildFigmaToWcfPromptText({ figmaUrl, userIntent }),
+        },
+      }],
+    }),
+  );
+
+  server.registerResource(
+    'wcf_components',
+    WCF_RESOURCE_URIS.components,
+    {
+      title: 'WCF Component Catalog',
+      description: 'Component catalog snapshot with categories and API entry points.',
+      mimeType: 'application/json',
+    },
+    async () => {
+      const payload = buildComponentsResourcePayload(indexes);
+      return {
+        contents: [{
+          uri: WCF_RESOURCE_URIS.components,
+          mimeType: 'application/json',
+          text: JSON.stringify(payload, null, 2),
+        }],
+      };
+    },
+  );
+
+  server.registerResource(
+    'wcf_tokens',
+    WCF_RESOURCE_URIS.tokens,
+    {
+      title: 'WCF Design Tokens',
+      description: 'Token summary resource for colors, spacing, typography, radius, and shadows.',
+      mimeType: 'application/json',
+    },
+    async () => {
+      const result = buildTokensResourcePayload(designTokensData);
+      const payload = result.isError ? { error: result.error } : result.payload;
+      return {
+        contents: [{
+          uri: WCF_RESOURCE_URIS.tokens,
+          mimeType: 'application/json',
+          text: JSON.stringify(payload, null, 2),
+        }],
+      };
+    },
+  );
+
+  server.registerResource(
+    'wcf_guidelines',
+    new ResourceTemplate(WCF_RESOURCE_URIS.guidelinesTemplate, {
+      list: async () => ({
+        resources: GUIDELINE_TOPICS.map((topic) => ({
+          uri: `wcf://guidelines/${topic}`,
+          name: `wcf guidelines (${topic})`,
+          description: `Guideline summary for topic=${topic}`,
+        })),
+      }),
+      complete: {
+        topic: async (value) => {
+          const query = String(value ?? '').trim().toLowerCase();
+          return GUIDELINE_TOPICS.filter((topic) => topic.startsWith(query));
+        },
+      },
+    }),
+    {
+      title: 'WCF Guidelines',
+      description: 'Topic-scoped guideline resource (accessibility|css|patterns|all).',
+      mimeType: 'application/json',
+    },
+    async (_uri, variables) => {
+      const topic = String(variables?.topic ?? '').trim().toLowerCase();
+      const result = buildGuidelinesResourcePayload(guidelinesIndexData, topic);
+      if (result.isError) {
+        throw new Error(`${result.error.code}: ${result.error.message}`);
+      }
+      return {
+        contents: [{
+          uri: `wcf://guidelines/${topic}`,
+          mimeType: 'application/json',
+          text: JSON.stringify(result.payload, null, 2),
+        }],
+      };
+    },
+  );
+
+  server.registerResource(
+    'wcf_llms_full',
+    WCF_RESOURCE_URIS.llmsFull,
+    {
+      title: 'WCF llms-full',
+      description: 'LLM reference corpus for WCF usage, generated from repository docs.',
+      mimeType: 'text/plain',
+    },
+    async () => {
+      if (typeof llmsFullText !== 'string' || llmsFullText.length === 0) {
+        throw new Error('LLMS_FULL_UNAVAILABLE: llms-full.txt is not available.');
+      }
+      return {
+        contents: [{
+          uri: WCF_RESOURCE_URIS.llmsFull,
+          mimeType: 'text/plain',
+          text: llmsFullText,
+        }],
+      };
+    },
+  );
+
   // -----------------------------------------------------------------------
   // Tool: get_design_system_overview
   // -----------------------------------------------------------------------
@@ -981,13 +1805,44 @@ export async function createMcpServer(loadJsonData, loadValidator) {
 
       const overview = {
         name: 'DADS Web Components (wcf)',
-        version: '0.1.1',
+        version: '0.2.0',
         prefix: CANONICAL_PREFIX,
         totalComponents: indexes.decls.length,
         componentsByCategory: categoryCount,
         totalPatterns: patternList.length,
         patterns: patternList,
+        setupInfo: {
+          npmPackage: 'web-components-factory',
+          installCommand: 'npm install web-components-factory',
+          vendorRuntimePath: 'vendor-runtime/',
+          htmlBoilerplate: '<script type="module" src="vendor-runtime/src/autoload.js"></script>',
+          noscriptGuidance: 'WCF components require JavaScript. Provide <noscript> fallback with static HTML equivalents for critical content.',
+        },
         ideSetupTemplates: IDE_SETUP_TEMPLATES,
+        availablePrompts: [
+          {
+            name: FIGMA_TO_WCF_PROMPT,
+            purpose: 'Figma-to-WCF conversion workflow prompt',
+          },
+        ],
+        availableResources: [
+          {
+            uri: WCF_RESOURCE_URIS.components,
+            purpose: 'Component catalog snapshot',
+          },
+          {
+            uri: WCF_RESOURCE_URIS.tokens,
+            purpose: 'Token summary snapshot',
+          },
+          {
+            uri: WCF_RESOURCE_URIS.guidelinesTemplate,
+            purpose: 'Topic-based guideline summaries',
+          },
+          {
+            uri: WCF_RESOURCE_URIS.llmsFull,
+            purpose: 'Full LLM reference text for WCF',
+          },
+        ],
         availableTools: [
           { name: 'get_design_system_overview', purpose: 'This overview (start here)' },
           { name: 'list_components', purpose: 'Browse components with progressive disclosure and filters' },
@@ -1000,23 +1855,51 @@ 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_design_token_detail', purpose: 'Get details, relationships, and usage examples for one token' },
           { 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, and IDE setup templates',
-          '2. search_guidelines → find relevant guidelines',
-          '3. get_design_tokens → get correct token values',
-          '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',
+          '2. figma_to_wcf (optional) → bootstrap the Figma-to-WCF tool sequence',
+          '3. wcf://components and wcf://tokens resources → preload catalog/token context',
+          '4. search_guidelines → find relevant guidelines',
+          '5. get_design_tokens → get correct token values',
+          '6. get_design_token_detail → inspect one token with references/referencedBy and usage examples',
+          '7. get_accessibility_docs → fetch component-level accessibility checklist',
+          '8. list_components (category/query + pagination) → shortlist components',
+          '9. search_icons (optional) → find icon names quickly',
+          '10. get_component_api → check attributes, slots, events, CSS parts',
+          '11. generate_usage_snippet or get_pattern_recipe → get code',
+          '12. validate_markup → verify your HTML and use suggestions to self-correct',
+          '13. get_install_recipe → get import/install instructions',
         ],
+        experimental: {
+          plugins: {
+            enabled: plugins.length > 0,
+            note: PLUGIN_TOOL_NOTICE,
+            pluginCount: plugins.length,
+            pluginToolCount: plugins.reduce((sum, plugin) => sum + (plugin.tools?.length ?? 0), 0),
+            plugins: plugins.map((plugin) => ({
+              name: plugin.name,
+              version: plugin.version,
+              toolCount: plugin.tools?.length ?? 0,
+              dataSourceOverrides: plugin.dataSources?.map((source) => source.fileName) ?? [],
+            })),
+          },
+        },
       };
 
+      for (const plugin of plugins) {
+        const tools = Array.isArray(plugin.tools) ? plugin.tools : [];
+        for (const tool of tools) {
+          overview.availableTools.push({
+            name: tool.name,
+            purpose: `${tool.description} (plugin: ${plugin.name})`,
+          });
+        }
+      }
+
       return {
         content: [{ type: 'text', text: JSON.stringify(overview, null, 2) }],
       };
@@ -1030,22 +1913,30 @@ export async function createMcpServer(loadJsonData, loadValidator) {
     'list_components',
     {
       description:
-        '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.',
+        'List custom elements in the design system. When: exploring available components, searching by keyword, or paging through results. Returns: {items, total, limit, offset, hasMore} where items is 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)'),
+        limit: z.number().int().min(1).max(200).optional().describe('Maximum items to return (default: 20; set 200 for all results)'),
         offset: z.number().int().min(0).optional().describe('Pagination offset (default: 0)'),
         prefix: z.string().optional(),
       },
     },
     async ({ category, query, limit, offset, prefix }) => {
-      const { items } = buildComponentSummaries(indexes, { category, query, limit, offset, prefix });
+      const page = buildComponentSummaries(indexes, { category, query, limit, offset, prefix });
+      const payload = {
+        items: page.items,
+        total: page.total,
+        limit: page.limit,
+        offset: page.offset,
+        hasMore: page.hasMore,
+      };
+      if (page._notice) payload._notice = page._notice;
       return {
-        content: [{ type: 'text', text: JSON.stringify(items, null, 2) }],
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
       };
     },
   );
@@ -1082,27 +1973,34 @@ export async function createMcpServer(loadJsonData, loadValidator) {
       description:
         'Get the full API surface of a single component (attributes, slots, events, CSS parts, CSS custom properties). When: you need detailed specs for a component. Returns: complete component specification. After: use generate_usage_snippet for a code example.',
       inputSchema: {
-        tagName: z.string().optional(),
-        className: z.string().optional(),
+        tagName: z.string().optional().describe('Tag name (e.g., "dads-button")'),
+        className: z.string().optional().describe('Class name (e.g., "DadsButton")'),
+        component: z.string().optional().describe('Any identifier: tagName, className, or bare name (e.g., "button")'),
         prefix: z.string().optional(),
       },
     },
-    async ({ tagName, className, prefix }) => {
-      const decl = pickDecl(indexes, { tagName, className, prefix });
+    async ({ tagName, className, component, prefix }) => {
+      const p = normalizePrefix(prefix);
+      let decl;
+      let modulePath;
+
+      if (component) {
+        const resolved = resolveDeclByComponent(indexes, component, p);
+        decl = resolved?.decl;
+        modulePath = resolved?.modulePath;
+      } else {
+        decl = pickDecl(indexes, { tagName, className, prefix: p });
+      }
+
       if (!decl) {
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `Component not found (tagName=${String(tagName ?? '')}, className=${String(className ?? '')})`,
-            },
-          ],
-          isError: true,
-        };
+        const identifier = component || tagName || className || '';
+        return buildComponentNotFoundError(identifier, indexes, p);
       }
 
       const canonicalTag = typeof decl.tagName === 'string' ? decl.tagName.toLowerCase() : undefined;
-      const modulePath = canonicalTag ? indexes.modulePathByTag.get(canonicalTag) : undefined;
+      if (!modulePath) {
+        modulePath = canonicalTag ? indexes.modulePathByTag.get(canonicalTag) : undefined;
+      }
       const api = serializeApi(decl, modulePath, prefix);
       const relatedComponents = getRelatedComponentsForTag({
         canonicalTagName: canonicalTag,
@@ -1136,19 +2034,16 @@ export async function createMcpServer(loadJsonData, loadValidator) {
       },
     },
     async ({ component, prefix }) => {
-      const decl =
-        pickDecl(indexes, { tagName: component, prefix }) ??
-        pickDecl(indexes, { className: component, prefix });
+      const p = normalizePrefix(prefix);
+      const resolved = resolveDeclByComponent(indexes, component, p);
+      const decl = resolved?.decl;
 
       if (!decl) {
-        return {
-          content: [{ type: 'text', text: `Component not found: ${component}` }],
-          isError: true,
-        };
+        return buildComponentNotFoundError(component, indexes, p);
       }
 
       const canonicalTag = typeof decl.tagName === 'string' ? decl.tagName.toLowerCase() : undefined;
-      const modulePath = canonicalTag ? indexes.modulePathByTag.get(canonicalTag) : undefined;
+      const modulePath = resolved?.modulePath ?? (canonicalTag ? indexes.modulePathByTag.get(canonicalTag) : undefined);
       const api = serializeApi(decl, modulePath, prefix);
       const snippet = generateSnippet(api, prefix);
 
@@ -1206,6 +2101,11 @@ export async function createMcpServer(loadJsonData, loadValidator) {
       const deps = Array.isArray(install.deps) ? install.deps : [];
       const tags = Array.isArray(install.tags) ? install.tags : [];
 
+      // Resolve transitive dependencies via BFS
+      const transitiveDeps = componentId
+        ? resolveComponentClosure({ installRegistry }, [componentId]).filter((id) => id !== componentId)
+        : [];
+
       const tagNames =
         tags.length > 0 ? tags.map((t) => withPrefix(String(t).toLowerCase(), p)) : [api.tagName];
 
@@ -1228,6 +2128,7 @@ export async function createMcpServer(loadJsonData, loadValidator) {
                 componentId,
                 tagNames,
                 deps,
+                transitiveDeps,
                 define,
                 defineHint,
                 source: install.source,
@@ -1250,7 +2151,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), warnings (unknown attributes/token misuse/accessibility misuse), and optional suggestion text for quick recovery. 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/invalid enum values/invalid slot names/missing required attributes), warnings (unknown attributes/token misuse/accessibility misuse/orphaned children/empty interactive elements), and optional suggestion text for quick recovery. Use after generating HTML to catch mistakes.',
       inputSchema: {
         html: z.string(),
         prefix: z.string().optional(),
@@ -1259,11 +2160,12 @@ export async function createMcpServer(loadJsonData, loadValidator) {
     async ({ html, prefix }) => {
       const p = normalizePrefix(prefix);
       let cemIndex = canonicalCemIndex;
+      let enumMap = canonicalEnumMap;
+      let slotMap = canonicalSlotMap;
       if (p !== CANONICAL_PREFIX) {
-        const combined = new Map(canonicalCemIndex);
-        const prefixed = applyPrefixToCemIndex(canonicalCemIndex, p);
-        for (const [tag, meta] of prefixed.entries()) combined.set(tag, meta);
-        cemIndex = combined;
+        cemIndex = mergeWithPrefixed(canonicalCemIndex, p);
+        enumMap = mergeWithPrefixed(canonicalEnumMap, p);
+        slotMap = mergeWithPrefixed(canonicalSlotMap, p);
       }
 
       const cemDiagnostics = validateTextAgainstCem({
@@ -1276,6 +2178,13 @@ export async function createMcpServer(loadJsonData, loadValidator) {
         },
       });
 
+      const enumDiagnostics = detectEnumValueMisuse({
+        filePath: '<markup>',
+        text: html,
+        enumMap,
+        severity: 'error',
+      });
+
       const tokenMisuseDiagnostics = detectTokenMisuseInInlineStyles({
         filePath: '<markup>',
         text: html,
@@ -1289,7 +2198,35 @@ export async function createMcpServer(loadJsonData, loadValidator) {
         severity: 'warning',
       });
 
-      const diagnostics = [...cemDiagnostics, ...tokenMisuseDiagnostics, ...accessibilityDiagnostics].map((d) => {
+      const slotDiagnostics = detectInvalidSlotName({
+        filePath: '<markup>',
+        text: html,
+        slotMap,
+        severity: 'error',
+      });
+
+      const requiredAttrDiagnostics = detectMissingRequiredAttributes({
+        filePath: '<markup>',
+        text: html,
+        prefix: p,
+        severity: 'error',
+      });
+
+      const orphanDiagnostics = detectOrphanedChildComponents({
+        filePath: '<markup>',
+        text: html,
+        prefix: p,
+        severity: 'warning',
+      });
+
+      const emptyInteractiveDiagnostics = detectEmptyInteractiveElement({
+        filePath: '<markup>',
+        text: html,
+        prefix: p,
+        severity: 'warning',
+      });
+
+      const diagnostics = [...cemDiagnostics, ...enumDiagnostics, ...slotDiagnostics, ...requiredAttrDiagnostics, ...orphanDiagnostics, ...emptyInteractiveDiagnostics, ...tokenMisuseDiagnostics, ...accessibilityDiagnostics].map((d) => {
         const suggestion = buildDiagnosticSuggestion({ diagnostic: d, cemIndex });
         return {
           file: d.file,
@@ -1454,35 +2391,48 @@ export async function createMcpServer(loadJsonData, loadValidator) {
           .describe('Filter by token category'),
         query: z.string().optional()
           .describe('Search token names (partial match)'),
+        theme: z.enum(['light', 'dark', 'all']).optional()
+          .describe('Theme filter (currently light only; dark/all return an error due to NG-06)'),
       },
     },
-    async ({ type, category, query }) => {
-      if (!designTokensData) {
+    async ({ type, category, query, theme }) => {
+      const { isError, payload } = buildDesignTokensPayload(designTokensData, { type, category, query, theme });
+      if (isError) {
         return {
-          content: [{ type: 'text', text: 'Design tokens data not available. Run: npm run mcp:extract-tokens' }],
+          content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
           isError: true,
         };
       }
+      return buildJsonToolResponse(payload);
+    },
+  );
 
-      let tokens = Array.isArray(designTokensData.tokens) ? designTokensData.tokens : [];
-
-      if (type) {
-        tokens = tokens.filter((t) => t.type === type);
-      }
-      if (category) {
-        tokens = tokens.filter((t) => t.category === category);
-      }
-      if (query) {
-        const q = query.toLowerCase();
-        tokens = tokens.filter((t) => t.name.toLowerCase().includes(q));
+  // -----------------------------------------------------------------------
+  // Tool: get_design_token_detail
+  // -----------------------------------------------------------------------
+  server.registerTool(
+    'get_design_token_detail',
+    {
+      description:
+        'Get details for one design token. ' +
+        'When: you already found a token and need its references, referencedBy, and usage examples. ' +
+        'Returns: token detail object with relationships and example CSS snippets. ' +
+        'After: apply the cssVariable in your implementation or validate related semantic aliases.',
+      inputSchema: {
+        name: z.string()
+          .describe('Token name or css variable (e.g. --color-primary or var(--color-primary))'),
+        theme: z.enum(['light', 'dark', 'all']).optional()
+          .describe('Theme selector (currently only light is supported due to NG-06)'),
+      },
+    },
+    async ({ name, theme }) => {
+      const { isError, payload } = buildDesignTokenDetailPayload(designTokensData, name, theme);
+      if (isError) {
+        return {
+          content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+          isError: true,
+        };
       }
-
-      const payload = {
-        total: tokens.length,
-        tokens,
-        summary: designTokensData.summary,
-      };
-
       return buildJsonToolResponse(payload);
     },
   );
@@ -1582,6 +2532,7 @@ export async function createMcpServer(loadJsonData, loadValidator) {
       const max = maxResults ?? 5;
       const documents = Array.isArray(guidelinesIndexData.documents) ? guidelinesIndexData.documents : [];
       const q = query.toLowerCase();
+      const expandedTerms = expandQueryWithSynonyms(q);
 
       // Score and rank sections
       const results = [];
@@ -1595,6 +2546,7 @@ export async function createMcpServer(loadJsonData, loadValidator) {
           const heading = String(section.heading ?? '').toLowerCase();
           const keywords = Array.isArray(section.keywords) ? section.keywords : [];
           const snippet = String(section.snippet ?? '').toLowerCase();
+          const body = String(section.body ?? '').toLowerCase();
 
           // Heading match: weight 3
           if (heading.includes(q)) score += 3;
@@ -1610,6 +2562,27 @@ export async function createMcpServer(loadJsonData, loadValidator) {
           // Snippet match: weight 1
           if (snippet.includes(q)) score += 1;
 
+          // Body text match: weight 1
+          if (body && body.includes(q)) score += 1;
+
+          // Synonym expansion match: weight 1 (only for expanded terms, not the original)
+          if (score === 0 && expandedTerms.length > 1) {
+            for (let i = 1; i < expandedTerms.length; i++) {
+              const syn = expandedTerms[i];
+              if (heading.includes(syn) || snippet.includes(syn) || body.includes(syn)) {
+                score += 1;
+                break;
+              }
+              for (const kw of keywords) {
+                if (String(kw).toLowerCase().includes(syn)) {
+                  score += 1;
+                  break;
+                }
+              }
+              if (score > 0) break;
+            }
+          }
+
           if (score > 0) {
             results.push({
               score,
@@ -1635,9 +2608,81 @@ export async function createMcpServer(loadJsonData, loadValidator) {
         results: topResults,
       };
 
+      // Zero-result fallback: suggest alternative queries and tools
+      if (results.length === 0) {
+        const synonymExpansions = expandedTerms.filter((t) => t !== q);
+        payload.suggestions = {
+          alternativeQueries: synonymExpansions.length > 0 ? synonymExpansions : [],
+          alternativeTools: [
+            { tool: 'get_accessibility_docs', hint: 'For component-specific a11y checks' },
+            { tool: 'get_component_api', hint: 'For component API details' },
+          ],
+        };
+      }
+
       return buildJsonToolResponse(payload);
     },
   );
 
-  return { server };
+  for (const plugin of plugins) {
+    const pluginTools = Array.isArray(plugin.tools) ? plugin.tools : [];
+    for (const tool of pluginTools) {
+      server.registerTool(
+        tool.name,
+        {
+          description: tool.description,
+          inputSchema: tool.inputSchema ?? {},
+        },
+        async (args) => {
+          try {
+            if (typeof tool.handler === 'function') {
+              const result = await tool.handler(args, {
+                plugin: { name: plugin.name, version: plugin.version },
+                helpers: {
+                  loadJsonData: loadJson,
+                  buildJsonToolResponse,
+                  normalizePrefix,
+                  withPrefix,
+                  toCanonicalTagName,
+                },
+              });
+              if (isPlainObject(result) && Array.isArray(result.content)) {
+                return result;
+              }
+              return buildJsonToolResponse(result ?? {});
+            }
+            return buildJsonToolResponse(tool.staticPayload ?? {});
+          } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+              content: [{
+                type: 'text',
+                text: JSON.stringify({
+                  error: {
+                    code: 'PLUGIN_TOOL_RUNTIME_ERROR',
+                    message: `Plugin tool failed (${tool.name}): ${message}`,
+                    plugin: plugin.name,
+                  },
+                }, null, 2),
+              }],
+              isError: true,
+            };
+          }
+        },
+      );
+    }
+  }
+
+  return {
+    server,
+    pluginRuntime: {
+      pluginCount: plugins.length,
+      pluginToolCount: plugins.reduce((sum, plugin) => sum + (plugin.tools?.length ?? 0), 0),
+      dataSourceOverrides: [...pluginDataSourceMap.entries()].map(([fileName, item]) => ({
+        fileName,
+        path: item.path,
+        pluginName: item.pluginName,
+      })),
+    },
+  };
 }