@monoharada/wcf-mcp 0.9.1 → 0.11.0

package/README.md

@@ -78,7 +78,7 @@ claude mcp add wcf -- npx @monoharada/wcf-mcp
 }
 ```
 
-## 提供機能（16 tools + 1 prompt + 5 resources）
+## 提供機能（19 tools + 2 prompts + 5 resources）
 
 ### ガードレール
 
@@ -101,6 +101,11 @@ claude mcp add wcf -- npx @monoharada/wcf-mcp
 | ツール | 説明 |
 |--------|------|
 | `validate_markup` | HTML スニペットを検証し、セマンティック検証（下表）で `suggestion` 付き診断を返す |
+| `validate_files` | 複数のマークアップファイルをまとめて検証し、ファイル別診断と集計を返す |
+| `validate_project` | ディレクトリを走査し、include/exclude glob に一致する複数ファイルをまとめて検証する |
+
+`validate_*` 系は common template syntax（`{{ }}`, `{% %}`, `<% %>`, `<? ?>`, script/style blocks）をそのまま HTML と誤認しないようにマスクして検証します。
+`validate_project` の既定 include は `*.html`, `*.htm`, `*.njk`, `*.liquid`, `*.astro`, `*.twig`, `*.hbs` です。
 
 #### validate_markup 検出コード一覧
 
@@ -119,6 +124,7 @@ claude mcp add wcf -- npx @monoharada/wcf-mcp
 | `roleAlertNotRecommended` | warning | `role="alert"` の使用（DADS 非推奨） | `role="alert"` |
 | `emptyLabel` | error | 空の `label` 属性（アクセシビリティ違反） | `<dads-input-text label="">` |
 | `emptyAriaLabel` | error | 空の `aria-label` 属性（アクセシビリティ違反） | `<dads-button aria-label="">` |
+| `duplicateId` | error | 同一ドキュメント内で `id` が重複している | `<div id="hero">...</div><section id="hero">...</section>` |
 | `forbiddenAttribute` | warning | 禁止属性 | `placeholder` |
 
 ### UI パターン
@@ -140,10 +146,11 @@ claude mcp add wcf -- npx @monoharada/wcf-mcp
 
 | ツール | 説明 |
 |--------|------|
-| `get_design_tokens` | デザイントークンを type/category/query/theme で検索（`theme=light` のみ。`dark/all` はエラー） |
+| `get_design_tokens` | デザイントークンを type/category/query/theme で検索（現状データは `light` のみ。`all` は利用可能テーマ全体、`dark` は非サポート） |
 | `get_design_token_detail` | 単一トークンの詳細（references/referencedBy/relatedTokens/usageExamples）を取得 |
 | `get_accessibility_docs` | component/topic/wcagLevel で A11y チェックリストとガイドライン要点を検索（`topic=all` では両ソースを混在返却） |
 | `search_guidelines` | ガイドライン（topic/query）をスコア付きで検索 |
+| `search_design_system_knowledge` | components/patterns/guidelines/tokens/skills を横断して検索し、exact/prefix/intent-aware ranking と source ごとの follow-up 導線を返す |
 
 #### `get_design_tokens` の使用例
 
@@ -226,12 +233,14 @@ claude mcp add wcf -- npx @monoharada/wcf-mcp
 }
 ```
 
-> **注意**: `theme` は `"light"` のみサポート。`"dark"` や `"all"` を指定すると `INVALID_THEME` エラーが返ります。
+> **注意**: 現在の実データは `light` のみです。`theme="all"` は利用可能テーマ全体として `light` を返します。`theme="dark"` は `INVALID_THEME` エラーです。
+> `var(--token, #fff)` のような literal fallback は relationship graph には含めません。`var(--token-a, var(--token-b))` のような token fallback のみ参照関係として扱います。
 
 ### Prompt
 
 | 名前 | 説明 |
 |------|------|
+| `build_page` | パターンID またはコンポーネントリストから no-build HTML ページを構築するガイド付きプロンプト |
 | `figma_to_wcf` | Figma URL を入力に、`overview → tokens → component api → snippet → validate` の実行順を返す |
 
 ### Resources (`wcf://`)
@@ -336,13 +345,20 @@ npx @monoharada/wcf-mcp --transport=http --port=3100
 詳細仕様: [docs/plugin-contract-v1.md](../../docs/plugin-contract-v1.md)
 
 - `plugins[].name` / `plugins[].version` は必須
+- `plugins[].validators` を使うと `validate_markup` / `validate_files` / `validate_project` に独自診断を差し込めます
+- `plugins[].prompts` / `plugins[].resources` を使うと MCP prompt / resource を追加できます
+- `plugins[].resourceTemplates` を使うと MCP resource template も追加できます
 - tool 名は組み込みツール名と重複不可（例: `list_components` など）
+- prompt の `argsSchema` は plain shape に加えて zod object shape も使えます
 - `dataSources` で差し替え可能な key は次のみ
   - `custom-elements.json`
   - `install-registry.json`
   - `pattern-registry.json`
+  - `component-selector-guide.json`
   - `design-tokens.json`
   - `guidelines-index.json`
+  - `skills-registry.json`
+  - `llms-full.txt`
 
 ## structuredContent rollback
 
@@ -636,8 +652,13 @@ CEM やレジストリを更新した後:
 ```bash
 npm run mcp:build     # データファイルをパッケージにコピー
 npm run mcp:check     # データが最新かチェック（CI用）
+npm run mcp:summary   # MCP inventory + quality summary(JSON)を生成
+npm run mcp:summary:check # summary JSON の drift をチェック
 ```
 
+- machine-readable summary: `packages/mcp-server/mcp-spec-test/summary/v3-final.json`
+- `npm run mcp:check:response-size` は human-readable stdout、`node scripts/mcp/check-response-size.mjs --json` は JSON 出力に使えます
+
 ### パッケージ構成
 
 ```

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

@@ -13,7 +13,7 @@ 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.1).';
+export const PLUGIN_TOOL_NOTICE = 'Plugin tool (contract v1.4).';
 export const PACKAGE_VERSION = String(packageMeta?.version ?? '0.0.0');
 
 export const CATEGORY_MAP = {
@@ -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,53 @@ 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_pattern_recipe({ patternId: "<id>", include: ["fullPage"] })',
+    '   → Returns a complete <!DOCTYPE html> page in one call',
+    '2. validate_markup({ html: "<the full page HTML>" }) → Validate the full page (catches missing importmap / boot script)',
+    '3. 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. generate_usage_snippet({ component: "<componentId>" }) → Get HTML for each component',
+    '2. generate_full_page_html({ html: "<combined fragments>" }) → Wrap into a complete page',
+    '3. 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

@@ -5,17 +5,20 @@
 import { z } from 'zod';
 import { PLUGIN_TOOL_NOTICE } from './constants.mjs';
 
-export const PLUGIN_CONTRACT_VERSION = '1.1.0';
+export const PLUGIN_CONTRACT_VERSION = '1.4.0';
 
 // Single-module constants (DD-14)
 const PLUGIN_DATA_SOURCE_KEYS = Object.freeze(new Set([
   'custom-elements.json',
   'install-registry.json',
   'pattern-registry.json',
+  'component-selector-guide.json',
   'design-tokens.json',
   'guidelines-index.json',
+  'skills-registry.json',
+  'llms-full.txt',
 ]));
-const BUILTIN_TOOL_NAMES = Object.freeze(new Set([
+export const BUILTIN_TOOL_NAMES = Object.freeze(new Set([
   'get_design_system_overview',
   'list_components',
   'search_icons',
@@ -23,6 +26,8 @@ const BUILTIN_TOOL_NAMES = Object.freeze(new Set([
   'generate_usage_snippet',
   'get_install_recipe',
   'validate_markup',
+  'validate_files',
+  'validate_project',
   'list_patterns',
   'get_pattern_recipe',
   'generate_pattern_snippet',
@@ -30,9 +35,24 @@ const BUILTIN_TOOL_NAMES = Object.freeze(new Set([
   'get_design_token_detail',
   'get_accessibility_docs',
   'search_guidelines',
+  'search_design_system_knowledge',
   'generate_full_page_html',
   'get_component_selector_guide',
 ]));
+const BUILTIN_PROMPT_NAMES = Object.freeze(new Set([
+  'figma_to_wcf',
+  'build_page',
+]));
+const BUILTIN_RESOURCE_URIS = Object.freeze(new Set([
+  'wcf://components',
+  'wcf://tokens',
+  'wcf://guidelines/{topic}',
+  'wcf://llms-full',
+  'wcf://skills',
+]));
+const BUILTIN_RESOURCE_TEMPLATE_URIS = Object.freeze(new Set([
+  'wcf://guidelines/{topic}',
+]));
 
 function isPlainObject(value) {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -109,11 +129,151 @@ function normalizePluginTools(pluginName, tools) {
   return out;
 }
 
+function normalizePluginValidators(pluginName, validators) {
+  if (!Array.isArray(validators)) return [];
+  const out = [];
+  const seen = new Set();
+  for (const rawValidator of validators) {
+    if (!isPlainObject(rawValidator)) {
+      throw new Error(toPluginErrorMessage(pluginName, 'validators entries must be objects'));
+    }
+    const name = String(rawValidator.name ?? '').trim();
+    if (!name) throw new Error(toPluginErrorMessage(pluginName, 'validator.name is required'));
+    if (seen.has(name)) {
+      throw new Error(toPluginErrorMessage(pluginName, `duplicate validator name: ${name}`));
+    }
+    seen.add(name);
+    if (typeof rawValidator.handler !== 'function') {
+      throw new Error(toPluginErrorMessage(pluginName, `validator "${name}" needs handler`));
+    }
+    out.push({
+      name,
+      description: String(rawValidator.description ?? '').trim() || `Validator hook provided by ${pluginName}.`,
+      handler: rawValidator.handler,
+    });
+  }
+  return out;
+}
+
+function normalizePluginPrompts(pluginName, prompts) {
+  if (!Array.isArray(prompts)) return [];
+  const out = [];
+  const seen = new Set();
+  for (const rawPrompt of prompts) {
+    if (!isPlainObject(rawPrompt)) {
+      throw new Error(toPluginErrorMessage(pluginName, 'prompts entries must be objects'));
+    }
+    const name = String(rawPrompt.name ?? '').trim();
+    if (!name) throw new Error(toPluginErrorMessage(pluginName, 'prompt.name is required'));
+    if (seen.has(name)) {
+      throw new Error(toPluginErrorMessage(pluginName, `duplicate prompt name: ${name}`));
+    }
+    seen.add(name);
+    const hasHandler = typeof rawPrompt.handler === 'function';
+    const hasStaticText = typeof rawPrompt.text === 'string';
+    if (!hasHandler && !hasStaticText) {
+      throw new Error(toPluginErrorMessage(pluginName, `prompt "${name}" needs handler or text`));
+    }
+    out.push({
+      name,
+      title: String(rawPrompt.title ?? name).trim(),
+      description: String(rawPrompt.description ?? '').trim() || `Prompt provided by ${pluginName}.`,
+      argsSchema: isPlainObject(rawPrompt.argsSchema) ? rawPrompt.argsSchema : {},
+      handler: hasHandler ? rawPrompt.handler : undefined,
+      text: hasStaticText ? rawPrompt.text : undefined,
+    });
+  }
+  return out;
+}
+
+function normalizePluginResources(pluginName, resources) {
+  if (!Array.isArray(resources)) return [];
+  const out = [];
+  const seenNames = new Set();
+  const seenUris = new Set();
+  for (const rawResource of resources) {
+    if (!isPlainObject(rawResource)) {
+      throw new Error(toPluginErrorMessage(pluginName, 'resources entries must be objects'));
+    }
+    const name = String(rawResource.name ?? '').trim();
+    const uri = String(rawResource.uri ?? '').trim();
+    if (!name) throw new Error(toPluginErrorMessage(pluginName, 'resource.name is required'));
+    if (!uri) throw new Error(toPluginErrorMessage(pluginName, `resource "${name}" needs uri`));
+    if (seenNames.has(name)) {
+      throw new Error(toPluginErrorMessage(pluginName, `duplicate resource name: ${name}`));
+    }
+    if (seenUris.has(uri)) {
+      throw new Error(toPluginErrorMessage(pluginName, `duplicate resource uri: ${uri}`));
+    }
+    seenNames.add(name);
+    seenUris.add(uri);
+    const hasHandler = typeof rawResource.handler === 'function';
+    const hasText = typeof rawResource.text === 'string';
+    const hasPayload = Object.prototype.hasOwnProperty.call(rawResource, 'payload');
+    if (!hasHandler && !hasText && !hasPayload) {
+      throw new Error(toPluginErrorMessage(pluginName, `resource "${name}" needs handler, text, or payload`));
+    }
+    out.push({
+      name,
+      uri,
+      title: String(rawResource.title ?? name).trim(),
+      description: String(rawResource.description ?? '').trim() || `Resource provided by ${pluginName}.`,
+      mimeType: String(rawResource.mimeType ?? '').trim() || undefined,
+      handler: hasHandler ? rawResource.handler : undefined,
+      text: hasText ? rawResource.text : undefined,
+      payload: hasPayload ? rawResource.payload : undefined,
+    });
+  }
+  return out;
+}
+
+function normalizePluginResourceTemplates(pluginName, resourceTemplates) {
+  if (!Array.isArray(resourceTemplates)) return [];
+  const out = [];
+  const seenNames = new Set();
+  const seenTemplates = new Set();
+  for (const rawTemplate of resourceTemplates) {
+    if (!isPlainObject(rawTemplate)) {
+      throw new Error(toPluginErrorMessage(pluginName, 'resourceTemplates entries must be objects'));
+    }
+    const name = String(rawTemplate.name ?? '').trim();
+    const uriTemplate = String(rawTemplate.uriTemplate ?? '').trim();
+    if (!name) throw new Error(toPluginErrorMessage(pluginName, 'resourceTemplate.name is required'));
+    if (!uriTemplate) throw new Error(toPluginErrorMessage(pluginName, `resourceTemplate "${name}" needs uriTemplate`));
+    if (seenNames.has(name)) throw new Error(toPluginErrorMessage(pluginName, `duplicate resourceTemplate name: ${name}`));
+    if (seenTemplates.has(uriTemplate)) throw new Error(toPluginErrorMessage(pluginName, `duplicate resourceTemplate uriTemplate: ${uriTemplate}`));
+    seenNames.add(name);
+    seenTemplates.add(uriTemplate);
+    const hasHandler = typeof rawTemplate.handler === 'function';
+    const hasText = typeof rawTemplate.text === 'string';
+    const hasPayload = Object.prototype.hasOwnProperty.call(rawTemplate, 'payload');
+    if (!hasHandler && !hasText && !hasPayload) {
+      throw new Error(toPluginErrorMessage(pluginName, `resourceTemplate "${name}" needs handler, text, or payload`));
+    }
+    out.push({
+      name,
+      uriTemplate,
+      title: String(rawTemplate.title ?? name).trim(),
+      description: String(rawTemplate.description ?? '').trim() || `Resource template provided by ${pluginName}.`,
+      mimeType: String(rawTemplate.mimeType ?? '').trim() || undefined,
+      handler: hasHandler ? rawTemplate.handler : undefined,
+      text: hasText ? rawTemplate.text : undefined,
+      payload: hasPayload ? rawTemplate.payload : undefined,
+      list: Array.isArray(rawTemplate.list) ? rawTemplate.list : undefined,
+      complete: isPlainObject(rawTemplate.complete) ? rawTemplate.complete : 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);
+  const seenPromptNames = new Set(BUILTIN_PROMPT_NAMES);
+  const seenResourceUris = new Set(BUILTIN_RESOURCE_URIS);
+  const seenResourceTemplateUris = new Set(BUILTIN_RESOURCE_TEMPLATE_URIS);
 
   for (const rawPlugin of plugins) {
     if (!isPlainObject(rawPlugin)) throw new Error('Invalid plugin configuration: each plugin must be an object');
@@ -124,15 +284,37 @@ export function normalizePlugins(plugins = []) {
     seenPluginNames.add(name);
 
     const tools = normalizePluginTools(name, rawPlugin.tools);
+    const validators = normalizePluginValidators(name, rawPlugin.validators);
+    const prompts = normalizePluginPrompts(name, rawPlugin.prompts);
+    const resources = normalizePluginResources(name, rawPlugin.resources);
+    const resourceTemplates = normalizePluginResourceTemplates(name, rawPlugin.resourceTemplates);
     for (const tool of tools) {
       if (seenToolNames.has(tool.name)) {
         throw new Error(toPluginErrorMessage(name, `tool name collision: ${tool.name}`));
       }
       seenToolNames.add(tool.name);
     }
+    for (const prompt of prompts) {
+      if (seenPromptNames.has(prompt.name)) {
+        throw new Error(toPluginErrorMessage(name, `prompt name collision: ${prompt.name}`));
+      }
+      seenPromptNames.add(prompt.name);
+    }
+    for (const resource of resources) {
+      if (seenResourceUris.has(resource.uri)) {
+        throw new Error(toPluginErrorMessage(name, `resource uri collision: ${resource.uri}`));
+      }
+      seenResourceUris.add(resource.uri);
+    }
+    for (const resourceTemplate of resourceTemplates) {
+      if (seenResourceTemplateUris.has(resourceTemplate.uriTemplate)) {
+        throw new Error(toPluginErrorMessage(name, `resourceTemplate uri collision: ${resourceTemplate.uriTemplate}`));
+      }
+      seenResourceTemplateUris.add(resourceTemplate.uriTemplate);
+    }
 
     const dataSources = normalizePluginDataSources(name, rawPlugin.dataSources);
-    normalized.push({ name, version, tools, dataSources });
+    normalized.push({ name, version, tools, validators, prompts, resources, resourceTemplates, dataSources });
   }
 
   return normalized;