@monoharada/wcf-mcp 0.1.0 → 0.1.2

package/README.md

@@ -1,4 +1,4 @@
-# @anthropic/wcf-mcp
+# @monoharada/wcf-mcp
 
 web-components-factory デザインシステム用の MCP (Model Context Protocol) サーバー。
 
@@ -9,7 +9,7 @@ web-components-factory デザインシステム用の MCP (Model Context Protoco
 ### npx で起動（クローン不要）
 
 ```bash
-npx @anthropic/wcf-mcp
+npx @monoharada/wcf-mcp
 ```
 
 ### Claude Desktop で使う
@@ -21,7 +21,7 @@ npx @anthropic/wcf-mcp
   "mcpServers": {
     "wcf": {
       "command": "npx",
-      "args": ["@anthropic/wcf-mcp"]
+      "args": ["@monoharada/wcf-mcp"]
     }
   }
 }
@@ -30,17 +30,39 @@ npx @anthropic/wcf-mcp
 ### Claude Code で使う
 
 ```bash
-claude mcp add wcf -- npx @anthropic/wcf-mcp
+claude mcp add wcf -- npx @monoharada/wcf-mcp
 ```
 
-## 提供ツール（8個）
+### Cursor で使う
+
+`.cursor/mcp.json` に追加:
+
+```json
+{
+  "mcpServers": {
+    "wcf": {
+      "command": "npx",
+      "args": ["@monoharada/wcf-mcp"]
+    }
+  }
+}
+```
+
+## 提供ツール（13個）
+
+### ガードレール
+
+| ツール | 説明 |
+|--------|------|
+| `get_design_system_overview` | 最初に呼ぶ前提情報（カテゴリ別コンポーネント数、利用可能パターン、推奨ワークフロー、IDE設定テンプレート）を返す |
 
 ### コンポーネント検索・API
 
 | ツール | 説明 |
 |--------|------|
-| `list_components` | デザインシステム内の全カスタム要素を一覧表示 |
-| `get_component_api` | tagName or className で属性・スロット・イベント・CSS Parts・CSS Custom Properties を取得 |
+| `list_components` | カテゴリ/クエリ/limit/offset でコンポーネントを段階的に取得（互換維持のため limit 未指定時は全件） |
+| `search_icons` | アイコン名をキーワード検索し、usage example を返す |
+| `get_component_api` | tagName or className で属性・スロット・イベント・CSS Parts・CSS Custom Properties を取得（`relatedComponents` を含む） |
 | `generate_usage_snippet` | コンポーネントの最小限 HTML スニペットを生成 |
 | `get_install_recipe` | componentId・依存関係・define関数・インストールコマンドを取得 |
 
@@ -48,7 +70,7 @@ claude mcp add wcf -- npx @anthropic/wcf-mcp
 
 | ツール | 説明 |
 |--------|------|
-| `validate_markup` | HTML スニペットを CEM に照合し、未知の要素（error）・属性（warning）を検出 |
+| `validate_markup` | HTML スニペットを検証し、未知要素（error）・未知属性（warning）・禁止属性/トークン誤用/`aria-live`・`role="alert"` の誤用（warning）を検出し、可能な場合は `suggestion` を返す |
 
 ### UI パターン
 
@@ -58,9 +80,58 @@ claude mcp add wcf -- npx @anthropic/wcf-mcp
 | `get_pattern_recipe` | パターンの完全レシピ（必要コンポーネント・依存解決・HTML）を取得 |
 | `generate_pattern_snippet` | パターンの HTML スニペットを生成 |
 
+### トークン・ガイドライン検索
+
+| ツール | 説明 |
+|--------|------|
+| `get_design_tokens` | デザイントークンを type/category/query で検索 |
+| `get_accessibility_docs` | component/topic/wcagLevel で A11y チェックリストとガイドライン要点を検索（`topic=all` では両ソースを混在返却） |
+| `search_guidelines` | ガイドライン（topic/query）をスコア付きで検索 |
+
+## transport
+
+標準は stdio です。HTTP transport も利用できます（localhost のみ）。
+
+```bash
+npx @monoharada/wcf-mcp --transport=http --port=3100
+```
+
+- bind: `127.0.0.1`
+- endpoint: `http://127.0.0.1:3100/mcp`
+
+## structuredContent rollback
+
+`get_component_api` / `get_design_tokens` / `get_accessibility_docs` / `search_guidelines` は通常 `structuredContent` を返します。
+
+- 100KB 制限を超える場合は自動的に `structuredContent` を省略し、`content` のみ返します
+- 緊急切り戻し時は環境変数 `WCF_MCP_DISABLE_STRUCTURED_CONTENT=1` を設定してください
+
+例:
+
+```bash
+WCF_MCP_DISABLE_STRUCTURED_CONTENT=1 npx @monoharada/wcf-mcp
+```
+
+Claude Desktop 設定例:
+
+```json
+{
+  "mcpServers": {
+    "wcf": {
+      "command": "npx",
+      "args": ["@monoharada/wcf-mcp"],
+      "env": {
+        "WCF_MCP_DISABLE_STRUCTURED_CONTENT": "1"
+      }
+    }
+  }
+}
+```
+
 ## prefix パラメータ
 
 全ツールで `prefix` パラメータをサポート。デフォルトは `dads`（例: `dads-button`）。
+`prefix` は最大64文字まで使用され、超過分は切り詰められます（例: 200文字指定 -> 先頭64文字を採用）。
 
 カスタム prefix を指定すると、出力のタグ名が自動変換されます:
 
@@ -115,7 +186,6 @@ prefix: "myui" → dads-button → myui-button
       "severity": "warning",
       "code": "unknownAttribute",
       "message": "Unknown attribute on <dads-button>: foo",
-      "tagName": "dads-button",
       "attrName": "foo"
     }
   ]
@@ -148,13 +218,16 @@ npm run mcp:check     # データが最新かチェック（CI用）
 ```
 packages/mcp-server/
 ├── bin.mjs          # エントリポイント (#!/usr/bin/env node)
+├── core.mjs         # ツール定義・共通ロジック
 ├── server.mjs       # MCP サーバー本体
 ├── validator.mjs    # HTML バリデーター
 ├── package.json     # npm パッケージ定義
 └── data/            # バンドルデータ (npm run mcp:build で生成)
     ├── custom-elements.json
     ├── install-registry.json
-    └── pattern-registry.json
+    ├── pattern-registry.json
+    ├── design-tokens.json
+    └── guidelines-index.json
 ```
 
 ## 要件

package/bin.mjs

@@ -1,7 +1,113 @@
 #!/usr/bin/env node
-import { startServer } from './server.mjs';
+/**
+ * bin.mjs — CLI entry-point for the wcf-mcp server.
+ *
+ * Usage:
+ *   wcf-mcp                        # stdio (default)
+ *   wcf-mcp --transport=http       # HTTP on 127.0.0.1:3100
+ *   wcf-mcp --transport=http --port=4000
+ */
 
-startServer().catch((err) => {
+import { createServer } from './server.mjs';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+const USAGE = [
+  'Usage:',
+  '  wcf-mcp',
+  '  wcf-mcp --transport=stdio',
+  '  wcf-mcp --transport=http [--port=3100]',
+  '  wcf-mcp --help',
+].join('\n');
+
+function parseArgs(argv) {
+  let transport = 'stdio';
+  let port = 3100;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--help' || arg === '-h') {
+      return { help: true, transport, port };
+    }
+
+    if (arg === '--transport') {
+      const value = argv[index + 1];
+      if (!value || value.startsWith('--')) {
+        throw new Error('--transport requires a value (stdio|http)');
+      }
+      transport = value;
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith('--transport=')) {
+      transport = arg.slice('--transport='.length);
+      continue;
+    }
+
+    if (arg === '--port') {
+      const value = argv[index + 1];
+      if (!value || value.startsWith('--')) {
+        throw new Error('--port requires a number between 1 and 65535');
+      }
+      port = Number(value);
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith('--port=')) {
+      port = Number(arg.slice('--port='.length));
+      continue;
+    }
+
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  if (transport !== 'stdio' && transport !== 'http') {
+    throw new Error(`Invalid transport: ${transport} (expected: stdio or http)`);
+  }
+
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(`Invalid port: ${String(port)} (expected: integer 1-65535)`);
+  }
+
+  return { help: false, transport, port };
+}
+
+async function main() {
+  let parsed;
+  try {
+    parsed = parseArgs(process.argv.slice(2));
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    console.error('');
+    console.error(USAGE);
+    process.exit(1);
+  }
+
+  if (parsed.help) {
+    console.log(USAGE);
+    return;
+  }
+
+  const { server } = await createServer();
+
+  if (parsed.transport === 'http') {
+    const { StreamableHTTPServerTransport } = await import(
+      '@modelcontextprotocol/sdk/server/streamableHttp.js'
+    );
+    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));
+    httpServer.listen(parsed.port, '127.0.0.1', () => {
+      console.error(`MCP HTTP server listening on http://127.0.0.1:${parsed.port}/mcp`);
+    });
+  } else {
+    await server.connect(new StdioServerTransport());
+  }
+}
+
+main().catch((err) => {
   console.error(err);
   process.exit(1);
 });