@monoharada/wcf-mcp 0.9.0 → 0.10.0

package/README.md

@@ -78,7 +78,7 @@ claude mcp add wcf -- npx @monoharada/wcf-mcp
 }
 ```
 
-## 提供機能（16 tools + 1 prompt + 5 resources）
+## 提供機能（19 tools + 1 prompt + 5 resources）
 
 ### ガードレール
 
@@ -92,7 +92,7 @@ claude mcp add wcf -- npx @monoharada/wcf-mcp
 |--------|------|
 | `list_components` | カテゴリ/クエリ/limit/offset でコンポーネントを段階的に取得（デフォルト20件。全件取得は `limit: 200`） |
 | `search_icons` | アイコン名をキーワード検索し、usage example を返す |
-| `get_component_api` | tagName or className で属性・スロット・イベント・CSS Parts・CSS Custom Properties を取得。`components` 配列でバッチ取得可能（最大10件） |
+| `get_component_api` | tagName or className で属性・スロット・イベント・CSS Parts・CSS Custom Properties を取得。`components` 配列でバッチ取得可能（最大10件。レスポンス予算次第で `structuredContent` は省略される） |
 | `generate_usage_snippet` | コンポーネントの最小限 HTML スニペットを生成 |
 | `get_install_recipe` | componentId・依存関係・define関数・インストールコマンドを取得 |
 
@@ -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,7 +233,8 @@ 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
 
@@ -285,7 +293,9 @@ npx @monoharada/wcf-mcp --transport=http --port=3100
 ```
 
 - bind: `127.0.0.1`
-- endpoint: `http://127.0.0.1:3100/mcp`
+- endpoint: `http://127.0.0.1:3100/mcp` のみ
+- Host / Origin validation を有効化して DNS rebinding を抑止します
+- `--config` が不正な場合は待受開始前に起動失敗します
 
 ## 設定ファイル
 
@@ -334,19 +344,28 @@ 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
 
-`get_component_api` / `get_design_tokens` / `get_design_token_detail` / `get_accessibility_docs` / `search_guidelines` は通常 `structuredContent` を返します。
+`get_component_api` / `get_design_tokens` / `get_design_token_detail` / `get_accessibility_docs` / `search_guidelines` のうち、object payload を返すケースでは通常 `structuredContent` を返します。
 
-- 100KB 制限を超える場合は自動的に `structuredContent` を省略し、`content` のみ返します
+- `structuredContent` は MCP 仕様どおり JSON object を直接返します
+- 100KB 制限を超える場合は自動的に `structuredContent` を省略し、必要に応じて `content` を compact JSON に切り替え、それでも収まらなければ `TOOL_RESULT_TOO_LARGE` warning payload にフォールバックします
+- plugin handler が raw MCP result を返す場合も、最終返却サイズには同じ上限が適用されます
 - 緊急切り戻し時は環境変数 `WCF_MCP_DISABLE_STRUCTURED_CONTENT=1` を設定してください
 
 例:
@@ -632,8 +651,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/bin.mjs

@@ -9,9 +9,12 @@
  */
 
 import { createServer } from './server.mjs';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 
-const USAGE = [
+export const USAGE = [
   'Usage:',
   '  wcf-mcp',
   '  wcf-mcp --transport=stdio',
@@ -19,8 +22,9 @@ const USAGE = [
   '  wcf-mcp --config=./wcf-mcp.config.json',
   '  wcf-mcp --help',
 ].join('\n');
+export const HTTP_ENDPOINT_PATH = '/mcp';
 
-function parseArgs(argv) {
+export function parseArgs(argv) {
   let transport = 'stdio';
   let port = 3100;
   let configPath;
@@ -90,6 +94,144 @@ function parseArgs(argv) {
   return { help: false, transport, port, configPath };
 }
 
+export function buildHttpTransportOptions({ host = '127.0.0.1', port }) {
+  const allowedHostnames = new Set([host]);
+  if (host === '127.0.0.1') {
+    allowedHostnames.add('localhost');
+  }
+  if (host === 'localhost') {
+    allowedHostnames.add('127.0.0.1');
+  }
+
+  const defaultHttpPort = port === 80;
+  const allowedHosts = new Set();
+  const allowedOrigins = new Set();
+  for (const allowedHostname of allowedHostnames) {
+    allowedHosts.add(`${allowedHostname}:${port}`);
+    allowedOrigins.add(`http://${allowedHostname}:${port}`);
+    if (defaultHttpPort) {
+      allowedHosts.add(allowedHostname);
+      allowedOrigins.add(`http://${allowedHostname}`);
+    }
+  }
+
+  return {
+    sessionIdGenerator: undefined,
+    allowedHosts: [...allowedHosts],
+    allowedOrigins: [...allowedOrigins],
+    enableDnsRebindingProtection: true,
+  };
+}
+
+function sendJsonRpcError(res, status, message) {
+  if (res.headersSent) return;
+  res.statusCode = status;
+  res.setHeader('content-type', 'application/json');
+  res.end(JSON.stringify({
+    jsonrpc: '2.0',
+    error: {
+      code: -32603,
+      message,
+    },
+    id: null,
+  }));
+}
+
+function sendNotFound(res) {
+  if (res.headersSent) return;
+  res.statusCode = 404;
+  res.setHeader('content-type', 'text/plain; charset=utf-8');
+  res.end('Not Found');
+}
+
+function getRequestPath(req) {
+  const rawUrl = req.url ?? '/';
+  try {
+    return new URL(rawUrl, 'http://localhost').pathname;
+  } catch {
+    return rawUrl;
+  }
+}
+
+export async function validateHttpStartup({
+  configPath,
+  createServerImpl = createServer,
+} = {}) {
+  const bootstrap = await createServerImpl({ configPath });
+  await Promise.allSettled([
+    bootstrap?.server?.close?.(),
+  ]);
+}
+
+export function createHttpRequestHandler({
+  port,
+  host = '127.0.0.1',
+  configPath,
+  createServerImpl = createServer,
+} = {}) {
+  const transportOptions = buildHttpTransportOptions({ host, port });
+
+  return async function handleHttpRequest(req, res) {
+    if (getRequestPath(req) !== HTTP_ENDPOINT_PATH) {
+      sendNotFound(res);
+      return;
+    }
+
+    let server;
+    let transport;
+    let cleanedUp = false;
+    const cleanup = async () => {
+      if (cleanedUp) return;
+      cleanedUp = true;
+      await Promise.allSettled([
+        transport?.close?.(),
+        server?.close?.(),
+      ]);
+    };
+
+    res.on('close', () => {
+      void cleanup();
+    });
+
+    try {
+      ({ server } = await createServerImpl({ configPath }));
+      const { StreamableHTTPServerTransport } = await import(
+        '@modelcontextprotocol/sdk/server/streamableHttp.js'
+      );
+      transport = new StreamableHTTPServerTransport(transportOptions);
+      await server.connect(transport);
+      await transport.handleRequest(req, res);
+      if (res.writableEnded) {
+        await cleanup();
+      }
+    } catch (error) {
+      await cleanup();
+      const message = error instanceof Error ? error.message : String(error);
+      if (res.headersSent) {
+        res.destroy(error instanceof Error ? error : new Error(message));
+        return;
+      }
+      sendJsonRpcError(res, 500, message);
+    }
+  };
+}
+
+function isDirectRun(metaUrl = import.meta.url, argv = process.argv) {
+  const entryPath = argv[1];
+  if (!entryPath) return false;
+
+  const resolveFilePath = (value) => {
+    const resolvedPath = path.resolve(value);
+    try {
+      return fs.realpathSync.native?.(resolvedPath) ?? fs.realpathSync(resolvedPath);
+    } catch {
+      return resolvedPath;
+    }
+  };
+
+  return resolveFilePath(entryPath) === resolveFilePath(fileURLToPath(metaUrl));
+}
+
 async function main() {
   let parsed;
   try {
@@ -106,25 +248,28 @@ async function main() {
     return;
   }
 
-  const { server } = await createServer({ configPath: parsed.configPath });
-
   if (parsed.transport === 'http') {
-    const { StreamableHTTPServerTransport } = await import(
-      '@modelcontextprotocol/sdk/server/streamableHttp.js'
-    );
+    await validateHttpStartup({ configPath: parsed.configPath });
     const { createServer: createHttpServer } = await import('node:http');
-    const httpTransport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
-    await server.connect(httpTransport);
-    const httpServer = createHttpServer((req, res) => httpTransport.handleRequest(req, res));
+    const handleHttpRequest = createHttpRequestHandler({
+      port: parsed.port,
+      configPath: parsed.configPath,
+    });
+    const httpServer = createHttpServer((req, res) => {
+      void handleHttpRequest(req, res);
+    });
     httpServer.listen(parsed.port, '127.0.0.1', () => {
-      console.error(`MCP HTTP server listening on http://127.0.0.1:${parsed.port}/mcp`);
+      console.error(`MCP HTTP server listening on http://127.0.0.1:${parsed.port}${HTTP_ENDPOINT_PATH}`);
     });
   } else {
+    const { server } = await createServer({ configPath: parsed.configPath });
     await server.connect(new StdioServerTransport());
   }
 }
 
-main().catch((err) => {
-  console.error(err);
-  process.exit(1);
-});
+if (isDirectRun()) {
+  main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}