@monoharada/wcf-mcp 0.9.1 → 0.11.0

package/data/guidelines-index.json

@@ -1,6 +1,6 @@
 {
   "version": "0.1.0",
-  "indexedAt": "2026-03-07T09:50:20.703Z",
+  "indexedAt": "2026-03-16T07:35:00.939Z",
   "documents": [
     {
       "id": ".claude/skills/css-writing-rules/references/core-principles.md",
@@ -4271,14 +4271,71 @@
             "カスタムツール定義の配列",
             "tools",
             "wcfmcpplugintool",
-            "データソース差し替え定義の配列",
-            "datasources",
-            "wcfmcpdatasourceconfig"
+            "validate_",
+            "系に差し込む",
+            "validator",
+            "hook"
           ],
-          "snippet": "```typescript\n/** プラグイン定義 */\ninterface WcfMcpPlugin {\n  /** プラグイン名（必須。組み込みツール名と重複不可） */\n  name: string;\n  /** プラグインバージョン（必須。semver 推奨） */\n  version: string;\n  /** カスタムツール定義の配列 */\n  tools?: WcfMcpPluginTool[];\n  /** データソース差し替え定義の配列 */\n  dataSources?: WcfMcpDataSourceConfig[];\n}\n```",
+          "snippet": "```typescript\n/** プラグイン定義 */\ninterface WcfMcpPlugin {\n  /** プラグイン名（必須。組み込みツール名と重複不可） */\n  name: string;\n  /** プラグインバージョン（必須。semver 推奨） */\n  version: string;\n  /** カスタムツール定義の配列 */\n  tools?: WcfMcpPluginTool[];\n  /** validate_* 系に差し込む validator hook */\n  validators?: WcfMcpPluginValidator[];\n  /** 追加 prompt */\n  prompts?: WcfMcpPluginPrompt[];\n  /** 追加 resource */\n  resources?: WcfMcpPluginResource[];\n  /** 追加 resource template */\n  resourceTemplates?: WcfMcpPluginResourceTemplate[];\n  /** データソース差",
           "body": "",
           "startLine": 9
         },
+        {
+          "heading": "Validator オブジェクト",
+          "keywords": [
+            "validator",
+            "オブジェクト",
+            "typescript",
+            "interface",
+            "wcfmcppluginvalidator",
+            "plugin",
+            "内で一意",
+            "name",
+            "string",
+            "description",
+            "診断配列または",
+            "diagnostics",
+            "を返す",
+            "handler",
+            "input",
+            "filepath",
+            "text",
+            "prefix",
+            "context",
+            "wcfmcphandlercontext"
+          ],
+          "snippet": "```typescript\ninterface WcfMcpPluginValidator {\n  /** validator 名（plugin 内で一意） */\n  name: string;\n  /** 説明 */\n  description?: string;\n  /** 診断配列または { diagnostics } を返す */\n  handler: (\n    input: { filePath: string; text: string; prefix: string },\n    context: WcfMcpHandlerContext\n  ) => Array<Record<string, unknown>> | { diagnostics: Array<Record<string, unknown>> } | Promise<Array<Record<string, unknown>> | { diagnostics: Array<Record<string, unknown>> }>;\n}\n```\n\n### validator hook\n\n- `validate",
+          "body": "### validator hook - `validate_markup` - `validate_files` - `validate_project` 上記 3 tool 実行時に、各 plugin validator が追加診断を返せます。 - `severity` 未指定時は `warning` - `file` 未指定時は対象ファイルへ自動補完 - 失敗した validator は `pluginValidatorRuntimeError` warning として返却",
+          "startLine": 33
+        },
+        {
+          "heading": "Prompt / Resource オブジェクト",
+          "keywords": [
+            "prompt",
+            "resource",
+            "オブジェクト",
+            "typescript",
+            "interface",
+            "wcfmcppluginprompt",
+            "name",
+            "string",
+            "title",
+            "description",
+            "argsschema",
+            "record",
+            "unknown",
+            "zod",
+            "raw",
+            "shape",
+            "plain",
+            "handler",
+            "args",
+            "context"
+          ],
+          "snippet": "```typescript\ninterface WcfMcpPluginPrompt {\n  name: string;\n  title?: string;\n  description?: string;\n  argsSchema?: Record<string, unknown>; // zod raw shape or plain shape\n  handler?: (args: Record<string, unknown>, context: WcfMcpHandlerContext) => string | { messages: Array<Record<string, unknown>> } | Promise<string | { messages: Array<Record<string, unknown>> }>;\n  text?: string;\n}\n\ninterface WcfMcpPluginResource {\n  name: string;\n  uri: string;\n  title?: string;\n  description?: string;\n ",
+          "body": "- prompt は `handler` または `text` が必須 - resource は `handler` / `text` / `payload` のいずれかが必須 - resourceTemplate も `handler` / `text` / `payload` のいずれかが必須 - prompt 名は組み込み prompt と重複不可 - resource URI は組み込み resource URI と重複不可 - resource template URI は組み込み template URI と重複不可",
+          "startLine": 61
+        },
         {
           "heading": "Tool オブジェクト",
           "keywords": [
@@ -4305,7 +4362,7 @@
           ],
           "snippet": "```typescript\n/** カスタムツール定義 */\ninterface WcfMcpPluginTool {\n  /** ツール名（必須。組み込みツール名と重複不可） */\n  name: string;\n  /** ツールの説明 */\n  description?: string;\n  /** 入力スキーマ（JSON Schema 形式） */\n  inputSchema?: Record<string, unknown>;\n  /** 動的ハンドラ関数。両方指定時は handler が優先される */\n  handler?: (args: Record<string, unknown>, context: WcfMcpHandlerContext) => unknown | Promise<unknown>;\n  /** 静的レスポンスペイロード。handler がある場合は無視される */\n  staticPayload?: unknown;\n}\n```\n\n### handler vs staticPayload\n\n- `handler`: リクエストごとに実行される関",
           "body": "### handler vs staticPayload - `handler`: リクエストごとに実行される関数。動的な結果を返す場合に使用 - `staticPayload`: 固定のレスポンスを返す場合に使用 - **両方指定した場合**: `handler` が優先され、`staticPayload` は無視される - **どちらも未指定**: バリデーションエラー（少なくとも一方が必須） - `handler` は plain payload のほか raw MCP result（`{ content: [...] }`）を返してもよい - ただし最終返却サイズには 100KB 上限が適用され、上限を超える raw result は `TOOL_RESULT_TOO_LARGE` warning payload に置き換わる",
-          "startLine": 25
+          "startLine": 108
         },
         {
           "heading": "Handler Context",
@@ -4333,7 +4390,7 @@
           ],
           "snippet": "```typescript\n/** handler 関数に渡されるコンテキスト */\ninterface WcfMcpHandlerContext {\n  /** プラグイン自身の情報 */\n  plugin: { name: string; version: string };\n  /** 共通ヘルパー */\n  helpers: {\n    /** JSON データファイルを読み込む */\n    loadJsonData: (fileName: string) => Promise<unknown>;\n    /** テキストデータファイルを読み込む (v1.1+) */\n    loadTextData: (fileName: string) => Promise<string>;\n    /** ツール応答を MCP 形式の JSON テキストに変換する */\n    buildJsonToolResponse: (payload: unknown) => { content: Array<{ type: string; text: string }> };\n    /** ",
           "body": "",
-          "startLine": 52
+          "startLine": 135
         },
         {
           "heading": "DataSource オブジェクト",
@@ -4359,9 +4416,9 @@
             "manifest",
             "install-registry"
           ],
-          "snippet": "```typescript\n/** データソース差し替え定義 */\ninterface WcfMcpDataSourceConfig {\n  /** 差し替え対象のファイル名 */\n  fileName: string;\n  /** 差し替えファイルのパス */\n  path: string;\n}\n```\n\n### 差し替え可能なファイル\n\n| fileName | 説明 |\n|----------|------|\n| `custom-elements.json` | Custom Elements Manifest |\n| `install-registry.json` | インストールレジストリ |\n| `pattern-registry.json` | パターンレジストリ |\n| `design-tokens.json` | デザイントークン |\n| `guidelines-index.json` | ガイドラインインデックス |",
-          "body": "### 差し替え可能なファイル | fileName | 説明 | |----------|------| | `custom-elements.json` | Custom Elements Manifest | | `install-registry.json` | インストールレジストリ | | `pattern-registry.json` | パターンレジストリ | | `design-tokens.json` | デザイントークン | | `guidelines-index.json` | ガイドラインインデックス |",
-          "startLine": 77
+          "snippet": "```typescript\n/** データソース差し替え定義 */\ninterface WcfMcpDataSourceConfig {\n  /** 差し替え対象のファイル名 */\n  fileName: string;\n  /** 差し替えファイルのパス */\n  path: string;\n}\n```\n\n### 差し替え可能なファイル\n\n| fileName | 説明 |\n|----------|------|\n| `custom-elements.json` | Custom Elements Manifest |\n| `install-registry.json` | インストールレジストリ |\n| `pattern-registry.json` | パターンレジストリ |\n| `component-selector-guide.json` | コンポーネント選択ガイド |\n| `design-tokens.json` | デザイントークン |\n| `guidelines-index.json` | ガイドラインインデックス |\n| `skills-registry.json`",
+          "body": "### 差し替え可能なファイル | fileName | 説明 | |----------|------| | `custom-elements.json` | Custom Elements Manifest | | `install-registry.json` | インストールレジストリ | | `pattern-registry.json` | パターンレジストリ | | `component-selector-guide.json` | コンポーネント選択ガイド | | `design-tokens.json` | デザイントークン | | `guidelines-index.json` | ガイドラインインデックス | | `skills-registry.json` | スキルレジストリ | | `llms-full.txt` | LLM 向け全文リファレンス |",
+          "startLine": 160
         },
         {
           "heading": "バリデーションルール",
@@ -4373,12 +4430,12 @@
             "ツール名は組み込みツール名と重複不可",
             "複数プラグイン間でツール名の重複不可",
             "datasources",
-            "のファイル名は上記5種のみ",
+            "のファイル名は上記8種のみ",
             "複数プラグイン間で同一ファイルの重複差し替え不可"
           ],
-          "snippet": "1. `name` と `version` は必須\n2. ツール名は組み込みツール名と重複不可\n3. 複数プラグイン間でツール名の重複不可\n4. `dataSources` のファイル名は上記5種のみ\n5. 複数プラグイン間で同一ファイルの重複差し替え不可",
-          "body": "1. `name` と `version` は必須 2. ツール名は組み込みツール名と重複不可 3. 複数プラグイン間でツール名の重複不可 4. `dataSources` のファイル名は上記5種のみ 5. 複数プラグイン間で同一ファイルの重複差し替え不可",
-          "startLine": 99
+          "snippet": "1. `name` と `version` は必須\n2. ツール名は組み込みツール名と重複不可\n3. 複数プラグイン間でツール名の重複不可\n4. `dataSources` のファイル名は上記8種のみ\n5. 複数プラグイン間で同一ファイルの重複差し替え不可",
+          "body": "1. `name` と `version` は必須 2. ツール名は組み込みツール名と重複不可 3. 複数プラグイン間でツール名の重複不可 4. `dataSources` のファイル名は上記8種のみ 5. 複数プラグイン間で同一ファイルの重複差し替え不可",
+          "startLine": 185
         },
         {
           "heading": "互換性ポリシー",
@@ -4391,15 +4448,22 @@
             "loadtextdata",
             "テキストファイルの読み込み",
             "utf-8",
-            "破壊的変更なし",
-            "新フィールドは追加のみ",
-            "既存フィールドの削除・型変更なし",
-            "破壊的変更を含む可能性あり",
-            "メジャーバージョンアップで通知"
+            "validators",
+            "validate_",
+            "tool",
+            "へ差し込む",
+            "validator",
+            "hook",
+            "prompts",
+            "resources",
+            "plugin",
+            "mcp",
+            "prompt",
+            "resource"
           ],
-          "snippet": "- **契約バージョン**: `1.1.0`（`PLUGIN_CONTRACT_VERSION` 定数で公開）\n- **v1.1 追加**: `helpers.loadTextData` — テキストファイルの読み込み（UTF-8）\n- **v1.x 内**: 破壊的変更なし。新フィールドは追加のみ（既存フィールドの削除・型変更なし）\n- **v2.0**: 破壊的変更を含む可能性あり。メジャーバージョンアップで通知",
-          "body": "- **契約バージョン**: `1.1.0`（`PLUGIN_CONTRACT_VERSION` 定数で公開） - **v1.1 追加**: `helpers.loadTextData` — テキストファイルの読み込み（UTF-8） - **v1.x 内**: 破壊的変更なし。新フィールドは追加のみ（既存フィールドの削除・型変更なし） - **v2.0**: 破壊的変更を含む可能性あり。メジャーバージョンアップで通知",
-          "startLine": 107
+          "snippet": "- **契約バージョン**: `1.4.0`（`PLUGIN_CONTRACT_VERSION` 定数で公開）\n- **v1.1 追加**: `helpers.loadTextData` — テキストファイルの読み込み（UTF-8）\n- **v1.2 追加**: `validators` — validate_* tool へ差し込む validator hook\n- **v1.3 追加**: `prompts`, `resources` — plugin から MCP prompt/resource を追加\n- **v1.4 追加**: `resourceTemplates`, prompt の richer `argsSchema` shape\n- **v1.x 内**: 破壊的変更なし。新フィールドは追加のみ（既存フィールドの削除・型変更なし）\n- **v2.0**: 破壊的変更を含む可能性あり。メジャーバージョンアップで通知",
+          "body": "- **契約バージョン**: `1.4.0`（`PLUGIN_CONTRACT_VERSION` 定数で公開） - **v1.1 追加**: `helpers.loadTextData` — テキストファイルの読み込み（UTF-8） - **v1.2 追加**: `validators` — validate_* tool へ差し込む validator hook - **v1.3 追加**: `prompts`, `resources` — plugin から MCP prompt/resource を追加 - **v1.4 追加**: `resourceTemplates`, prompt の richer `argsSchema` shape - **v1.x 内**: 破壊的変更なし。新フィールドは追加のみ（既存フィールドの削除・型変更なし） - **v2.0**: 破壊的変更を含む可能性あり。メジャーバージョンアップで通知",
+          "startLine": 193
         },
         {
           "heading": "@experimental 機能",
@@ -4414,7 +4478,7 @@
           ],
           "snippet": "以下は将来追加される可能性がありますが、まだ安定していません:\n\n- ライフサイクルフック（`onInit`, `onDestroy`）\n- プラグイン間依存の宣言",
           "body": "以下は将来追加される可能性がありますが、まだ安定していません: - ライフサイクルフック（`onInit`, `onDestroy`） - プラグイン間依存の宣言",
-          "startLine": 114
+          "startLine": 203
         },
         {
           "heading": "設定ファイルからの利用",
@@ -4442,7 +4506,7 @@
           ],
           "snippet": "```json\n{\n  \"plugins\": [\n    {\n      \"module\": \"./plugins/my-plugin.mjs\"\n    },\n    {\n      \"name\": \"static-tools\",\n      \"version\": \"1.0.0\",\n      \"staticTools\": [\n        { \"name\": \"my_tool\", \"payload\": { \"ok\": true } }\n      ]\n    }\n  ]\n}\n```\n\n### module プラグイン\n\nESM ファイルが `default export` でプラグインオブジェクトを返す:\n\n```javascript\n// plugins/my-plugin.mjs\nexport default {\n  name: 'my-plugin',\n  version: '1.0.0',\n  tools: [\n    {\n      name: 'my_custom_tool',\n      description: 'Custom tool from plugin',\n",
           "body": "### module プラグイン ESM ファイルが `default export` でプラグインオブジェクトを返す:",
-          "startLine": 121
+          "startLine": 210
         }
       ]
     },

package/examples/plugins/custom-validation-plugin.mjs

@@ -2,6 +2,9 @@
  * Sample plugin for wcf-mcp (Plugin Contract v1).
  * Demonstrates:
  *  - Custom tool with handler
+ *  - Validator hook used by validate_markup / validate_files / validate_project
+ *  - Static prompt and resource hooks
+ *  - Resource template hook
  *  - Custom tool using handler context (helpers.loadJsonData)
  *  - dataSources override for guidelines-index.json
  */
@@ -33,6 +36,64 @@ export default {
       path: './custom-guidelines.json',
     },
   ],
+  validators: [
+    {
+      name: 'heading_structure',
+      description: 'Warn on skipped heading levels during validate_* flows.',
+      async handler({ text, filePath }) {
+        const diagnostics = detectSkippedHeadingLevel(text).map((item) => ({
+          file: filePath,
+          severity: 'warning',
+          code: item.code,
+          message: item.message,
+          hint: 'Use sequential heading levels (e.g. h2 -> h3).',
+        }));
+        return { diagnostics };
+      },
+    },
+  ],
+  prompts: [
+    {
+      name: 'custom_validation_workflow',
+      title: 'Custom Validation Workflow',
+      argsSchema: {
+        audience: {
+          type: 'string',
+          description: 'Optional audience label',
+        },
+      },
+      text: 'Run validate_markup, then validate_files for page-level issues, then inspect custom guidelines.',
+    },
+  ],
+  resources: [
+    {
+      name: 'custom_validation_notes',
+      uri: 'plugin://custom-validation/notes',
+      mimeType: 'text/plain',
+      text: 'Custom validation plugin loaded. Use validate_heading_structure for manual checks.',
+    },
+  ],
+  resourceTemplates: [
+    {
+      name: 'custom_guideline_template',
+      uriTemplate: 'plugin://custom-validation/guidelines/{slug}',
+      complete: {
+        slug: ['headings', 'forms'],
+      },
+      async handler({ uri, variables }) {
+        return {
+          contents: [{
+            uri,
+            mimeType: 'application/json',
+            text: JSON.stringify({
+              slug: variables?.slug ?? '',
+              note: 'Custom guideline template resource',
+            }, null, 2),
+          }],
+        };
+      },
+    },
+  ],
   tools: [
     {
       name: 'validate_heading_structure',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monoharada/wcf-mcp",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "MCP server for the web-components-factory design system. Provides component discovery, validation, and pattern-based UI composition without cloning the repository.",
   "type": "module",
   "bin": {

package/runtime-data.mjs

@@ -1,5 +1,6 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { pathToFileURL } from 'node:url';
 
 export const RUNTIME_FILE_MAP = Object.freeze({
   'custom-elements.json': 'custom-elements.json',
@@ -31,6 +32,33 @@ async function readTextIfExists(targetPath) {
   }
 }
 
+async function loadGeneratedJsonFallback(fileName, { repoRoot }) {
+  const generators = {
+    'design-tokens.json': {
+      modulePath: path.join(repoRoot, 'scripts/mcp/extract-design-tokens.mjs'),
+      exportName: 'buildDesignTokensData',
+    },
+    'guidelines-index.json': {
+      modulePath: path.join(repoRoot, 'scripts/mcp/index-guidelines.mjs'),
+      exportName: 'buildGuidelinesIndexData',
+    },
+  };
+
+  const generator = generators[fileName];
+  if (!generator) return null;
+
+  try {
+    await fs.access(generator.modulePath);
+  } catch {
+    return null;
+  }
+
+  const loaded = await import(pathToFileURL(generator.modulePath).href);
+  const build = loaded?.[generator.exportName];
+  if (typeof build !== 'function') return null;
+  return build();
+}
+
 export async function loadTextDataWithFallback(fileName, { bundledDir, repoRoot = process.cwd() } = {}) {
   const bundled = resolveBundledDataPath(fileName, { bundledDir });
   const repo = resolveRuntimeDataPath(fileName, { repoRoot });
@@ -44,12 +72,20 @@ export async function loadTextDataWithFallback(fileName, { bundledDir, repoRoot
 }
 
 export async function loadJsonDataWithFallback(fileName, options = {}) {
-  const text = await loadTextDataWithFallback(fileName, options);
   try {
-    return JSON.parse(text);
+    const text = await loadTextDataWithFallback(fileName, options);
+    try {
+      return JSON.parse(text);
+    } catch (error) {
+      throw new Error(
+        `データファイルのJSON解析に失敗しました: ${fileName} (${error instanceof Error ? error.message : String(error)})`,
+      );
+    }
   } catch (error) {
-    throw new Error(
-      `データファイルのJSON解析に失敗しました: ${fileName} (${error instanceof Error ? error.message : String(error)})`,
-    );
+    const generated = await loadGeneratedJsonFallback(fileName, {
+      repoRoot: options.repoRoot ?? process.cwd(),
+    });
+    if (generated !== null) return generated;
+    throw error;
   }
 }

package/server.mjs

@@ -197,6 +197,10 @@ export async function loadJsonDataFromPath(sourcePath) {
   return JSON.parse(text);
 }
 
+export async function loadTextDataFromPath(sourcePath) {
+  return fs.readFile(sourcePath, 'utf8');
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -211,6 +215,7 @@ export async function createServer(options = {}) {
   return createMcpServer(loadJsonData, loadValidator, {
     plugins: runtimeConfig.plugins,
     loadJsonDataFromPath,
+    loadTextDataFromPath,
     loadTextData,
   });
 }