@lism-css/mcp 0.11.0 → 0.13.0

package/dist/tools/convert-css.js

@@ -1,74 +1,107 @@
 import { z } from 'zod';
-import { loadJSON } from '../lib/load-data.js';
-import { PropsSystemDataSchema } from '../lib/schemas.js';
+import { loadMarkdown } from '../lib/load-markdown.js';
+import { parsePropRows } from '../lib/markdown-utils.js';
 import { success, error, READ_ONLY_ANNOTATIONS } from '../lib/response.js';
 // ----------------------------------------------------------------
 // CSS パース
 // ----------------------------------------------------------------
+/** @ルール（@media 等）が含まれていないか検査する */
+function detectAtRules(cssText) {
+    const atRuleMatch = cssText.match(/^@(\w[\w-]*)/m);
+    if (atRuleMatch) {
+        return `@${atRuleMatch[1]} ルールは未対応です。CSS 宣言（property: value;）のみを入力してください。`;
+    }
+    return null;
+}
+/**
+ * CSS テキストから宣言を抽出する。
+ * `;` で分割する際に `url()` 等の括弧内の `;` を無視する。
+ */
 function parseCssDeclarations(cssText) {
     // コメント除去
     let cleaned = cssText.replace(/\/\*[\s\S]*?\*\//g, '');
     // セレクタ + ブレースを除去（裸の宣言リストも受け付ける）
     cleaned = cleaned.replace(/[^{}]*\{/g, '').replace(/\}/g, '');
+    // 括弧のネストを考慮して `;` で分割
+    const segments = [];
+    let current = '';
+    let parenDepth = 0;
+    for (const ch of cleaned) {
+        if (ch === '(')
+            parenDepth++;
+        if (ch === ')')
+            parenDepth = Math.max(0, parenDepth - 1);
+        if (ch === ';' && parenDepth === 0) {
+            segments.push(current.trim());
+            current = '';
+        }
+        else {
+            current += ch;
+        }
+    }
+    if (current.trim())
+        segments.push(current.trim());
     const declarations = [];
-    for (const line of cleaned.split(';')) {
-        const trimmed = line.trim();
-        if (!trimmed)
+    for (const segment of segments) {
+        if (!segment)
             continue;
-        const colonIdx = trimmed.indexOf(':');
+        const colonIdx = segment.indexOf(':');
         if (colonIdx === -1)
             continue;
-        const property = trimmed.substring(0, colonIdx).trim().toLowerCase();
-        const value = trimmed.substring(colonIdx + 1).trim();
+        const property = segment.substring(0, colonIdx).trim().toLowerCase();
+        const value = segment.substring(colonIdx + 1).trim();
         if (property && value) {
             declarations.push({ property, value });
         }
     }
     return declarations;
 }
-// ----------------------------------------------------------------
-// CSSプロパティ → PropEntry マップ
-// ----------------------------------------------------------------
-function buildCssPropertyMap(categories) {
+/** プリセット値列から値を抽出する（例: "-fz:root, -fz:base" → ["root", "base"]） */
+function extractPresetValues(presetColumn, propName) {
+    if (!presetColumn || presetColumn === '—' || presetColumn === '-')
+        return [];
+    const values = [];
+    // -{prop}:{value} パターンを全て抽出
+    const escaped = propName.replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&');
+    const regex = new RegExp(`-${escaped}:([^,\\s\`〜]+)`, 'g');
+    let match;
+    while ((match = regex.exec(presetColumn)) !== null) {
+        values.push(match[1]);
+    }
+    return values;
+}
+function buildMappings(md) {
+    return parsePropRows(md).map((row) => ({
+        prop: row.prop,
+        cssProperty: row.cssProperty,
+        presetValues: extractPresetValues(row.presetColumn, row.prop),
+        sectionName: row.sectionName,
+    }));
+}
+function buildCssPropertyMap(mappings) {
     const map = new Map();
-    for (const cat of categories) {
-        for (const prop of cat.props) {
-            const normalized = normalizeCssPropertyName(prop.cssProperty);
-            if (normalized)
-                map.set(normalized, prop);
+    for (const mapping of mappings) {
+        const normalized = mapping.cssProperty.toLowerCase();
+        // CSS カスタムプロパティ形式はスキップ（"--hl" 等）
+        if (!normalized.startsWith('(class:')) {
+            map.set(normalized, mapping);
         }
     }
     return map;
 }
-/** cssProperty フィールドの正規化 */
-function normalizeCssPropertyName(raw) {
-    // "(class: is--container)" → スキップ（CSS プロパティではない）
-    if (raw.startsWith('(class:'))
-        return null;
-    // "--hl (CSS変数)" → "--hl"
-    return raw
-        .replace(/\s*\(.*\)$/, '')
-        .trim()
-        .toLowerCase();
-}
 // ----------------------------------------------------------------
 // 値のマッピング
 // ----------------------------------------------------------------
 /** よくある CSS 値 → Lism トークン値の変換テーブル */
 const VALUE_ALIASES = {
-    column: 'col',
-    'column-reverse': 'col-r',
-    'row-reverse': 'row-r',
     'space-between': 'between',
-    'flex-start': 'flex-s',
-    'flex-end': 'flex-e',
-    currentcolor: 'cc',
+    currentcolor: 'current',
     uppercase: 'upper',
     lowercase: 'lower',
 };
-function suggestValue(propEntry, cssValue) {
-    const tokens = propEntry.values;
-    if (!tokens || tokens.length === 0)
+function suggestValue(mapping, cssValue) {
+    const tokens = mapping.presetValues;
+    if (tokens.length === 0)
         return null;
     // 直接一致
     if (tokens.includes(cssValue))
@@ -124,12 +157,9 @@ function detectComponent(declarations) {
 // ----------------------------------------------------------------
 // 変換メイン
 // ----------------------------------------------------------------
-function findCategory(categories, propName) {
-    for (const cat of categories) {
-        if (cat.props.some((p) => p.prop === propName))
-            return cat.category;
-    }
-    return 'unknown';
+function findCategory(mappings, propName) {
+    const found = mappings.find((m) => m.prop === propName);
+    return found?.sectionName ?? 'unknown';
 }
 function buildExample(conversions, component) {
     const tagName = component?.name ?? 'Lism';
@@ -167,44 +197,55 @@ function buildExample(conversions, component) {
 // ----------------------------------------------------------------
 export function registerConvertCss(server) {
     server.registerTool('convert_css', {
-        description: 'Convert CSS code to lism-css props, utility classes, and component suggestions. Accepts CSS declarations (with or without selectors) and returns the equivalent lism-css representation. Use this to migrate existing CSS to lism-css, or to understand how CSS properties map to lism-css.',
+        description: 'Convert CSS code to lism-css props, utility classes, and component suggestions. Accepts CSS declarations (with or without selectors) and returns the equivalent lism-css representation as structured JSON.\n' +
+            'Use this when migrating existing CSS to lism-css in bulk, or when you need to understand how multiple CSS properties map to lism-css at once.\n' +
+            'Do NOT use this for single prop lookups (use get_props_system instead). Note: @media and other at-rules are NOT supported — an error will be returned if detected.\n' +
+            'Returns JSON with conversions (prop mappings with confidence), component suggestions, and a JSX usage example.',
         inputSchema: {
             css: z
                 .string()
-                .describe('CSS code to convert. Accepts a full rule block with selector (e.g. ".foo { padding: 1rem; }") or bare declarations (e.g. "padding: 1rem; font-size: 16px;").'),
+                .describe('CSS code to convert. Accepts a full rule block with selector (e.g. ".foo { padding: 1rem; }") or bare declarations (e.g. "padding: 1rem; font-size: 16px;"). @media and other at-rules are not supported.'),
         },
         annotations: READ_ONLY_ANNOTATIONS,
     }, ({ css }) => {
         try {
-            const propsData = loadJSON('props-system.json', PropsSystemDataSchema);
-            const cssPropertyMap = buildCssPropertyMap(propsData.categories);
+            // @ ルール検出
+            const atRuleError = detectAtRules(css);
+            if (atRuleError) {
+                return error(atRuleError);
+            }
+            const md = loadMarkdown('property-class.md');
+            const mappings = buildMappings(md);
+            const cssPropertyMap = buildCssPropertyMap(mappings);
             const declarations = parseCssDeclarations(css);
             if (declarations.length === 0) {
                 return error('CSS 宣言が見つかりません。"property: value;" 形式の CSS を入力してください。');
             }
             // 各宣言を変換
             const conversions = declarations.map((decl) => {
-                const propEntry = cssPropertyMap.get(decl.property);
-                if (!propEntry) {
+                const mapping = cssPropertyMap.get(decl.property);
+                if (!mapping) {
                     return {
                         css: `${decl.property}: ${decl.value}`,
                         lismProp: null,
                         suggestedValue: null,
                         availableTokens: null,
+                        confidence: 'unmapped',
                         note: 'Lism Props に該当なし。style で直接指定してください。',
                     };
                 }
-                const suggested = suggestValue(propEntry, decl.value);
-                const category = findCategory(propsData.categories, propEntry.prop);
+                const suggested = suggestValue(mapping, decl.value);
+                const category = findCategory(mappings, mapping.prop);
                 return {
                     css: `${decl.property}: ${decl.value}`,
-                    lismProp: propEntry.prop,
+                    lismProp: mapping.prop,
                     suggestedValue: suggested,
-                    availableTokens: propEntry.values ?? null,
+                    availableTokens: mapping.presetValues.length > 0 ? mapping.presetValues : null,
+                    confidence: suggested ? 'exact' : 'approximate',
                     note: suggested
                         ? `トークン値 '${suggested}' を使用（カテゴリ: ${category}）`
-                        : propEntry.values && propEntry.values.length > 0
-                            ? `カスタム値。利用可能なトークン: ${propEntry.values.join(', ')}（カテゴリ: ${category}）`
+                        : mapping.presetValues.length > 0
+                            ? `カスタム値。利用可能なトークン: ${mapping.presetValues.join(', ')}（カテゴリ: ${category}）`
                             : `カスタム値として指定（カテゴリ: ${category}）`,
                 };
             });

package/dist/tools/get-component.js

@@ -1,12 +1,70 @@
 import { z } from 'zod';
-import { loadJSON } from '../lib/load-data.js';
-import { ComponentInfoSchema } from '../lib/schemas.js';
-import { success, error, notFound, READ_ONLY_ANNOTATIONS } from '../lib/response.js';
+import { getGuideFilenames, loadMarkdown } from '../lib/load-markdown.js';
+import { findComponentByHeading, findComponentInTables } from '../lib/markdown-utils.js';
+import { markdownResponse, error, notFound, READ_ONLY_ANNOTATIONS } from '../lib/response.js';
+/** 入力を正規化してエイリアス検索のキーに変換する。
+ *  `<Flex>` / `Flex` / `l--flex` / `flex` をすべて `flex` に揃える。 */
+function normalizeComponentKey(input) {
+    return input
+        .trim()
+        .toLowerCase()
+        .replace(/^<|>$/g, '')
+        .replace(/^(l--|is--|a--|c--)/, '');
+}
+/** 入力が `<ComponentName>` 形式（React コンポーネントとしての問い合わせ）か判定する */
+function isAngleBracketNotation(input) {
+    return /^<[^<>]+>$/.test(input.trim());
+}
+/** primitives/*.md の先頭行 `# l--flex / \`<Flex>\`` からクラス名とコンポーネント名を抽出する */
+function parsePrimitiveHeading(md) {
+    const firstLine = md.split('\n', 1)[0] ?? '';
+    const match = firstLine.match(/^#\s+((?:l|is|a|c)--[A-Za-z0-9]+)(?:\s*\/\s*`<([A-Za-z0-9]+)>`)?/);
+    if (!match)
+        return null;
+    return { className: match[1], componentName: match[2] };
+}
+let classAliasMap = null;
+let componentAliasMap = null;
+/** primitives/*.md を走査して、クラス名由来 / React コンポーネント名由来の alias map を構築する（遅延初期化・キャッシュ）。
+ *  angle-bracket 形式の問い合わせ（`<Vertical>` など）には componentAliasMap のみを照合し、
+ *  クラス専用プリミティブ（例: is--vertical）を誤ってヒットさせないために分離している。 */
+function buildAliasMaps() {
+    if (classAliasMap && componentAliasMap)
+        return;
+    const classMap = new Map();
+    const componentMap = new Map();
+    for (const filename of getGuideFilenames()) {
+        if (!filename.startsWith('primitives/'))
+            continue;
+        const parsed = parsePrimitiveHeading(loadMarkdown(filename));
+        if (!parsed)
+            continue;
+        classMap.set(normalizeComponentKey(parsed.className), filename);
+        if (parsed.componentName) {
+            componentMap.set(normalizeComponentKey(parsed.componentName), filename);
+        }
+    }
+    classAliasMap = classMap;
+    componentAliasMap = componentMap;
+}
+function getClassAliasMap() {
+    buildAliasMaps();
+    return classAliasMap;
+}
+function getComponentAliasMap() {
+    buildAliasMaps();
+    return componentAliasMap;
+}
 export function registerGetComponent(server) {
     server.registerTool('get_component', {
-        description: '特定のlism-cssコンポーネントに関する詳細情報（プロパティ、使用例、カテゴリー）を取得します。該当するものが見つからない場合は、より広範なキーワードで search_docs を実行してください。',
+        description: 'Get detailed information about a specific lism-css component: purpose, props, and usage examples.\n' +
+            'Use this when you need documentation for a known component by name (e.g. "Box", "Flex", "Accordion", "Lism", "HTML").\n' +
+            'Accepts multiple notations: "Flex", "<Flex>", "l--flex", "flex" all resolve to the same entry.\n' +
+            'Do NOT use this for broad topic guides (use get_guide with "components-core" or "components-ui") or keyword search across all docs (use search_docs).\n' +
+            'If the component is not found, suggestions will be provided — follow up with search_docs for a broader query.\n' +
+            'The response is pre-formatted Markdown. Output it verbatim. Do NOT summarize or omit code examples.',
         inputSchema: {
-            name: z.string().describe('Component name to look up (e.g. "Box", "Flex", "Accordion").'),
+            name: z.string().describe('Component name to look up (e.g. "Box", "Flex", "Accordion", "l--flex", "<Flex>").'),
             package: z
                 .enum(['lism-css', '@lism-css/ui'])
                 .optional()
@@ -15,42 +73,104 @@ export function registerGetComponent(server) {
         annotations: READ_ONLY_ANNOTATIONS,
     }, ({ name, package: pkg }) => {
         try {
-            const data = loadJSON('components.json', z.array(ComponentInfoSchema));
-            let candidates = data;
-            if (pkg) {
-                candidates = data.filter((c) => c.package === pkg);
+            const normalizedKey = normalizeComponentKey(name);
+            const rawLower = name.toLowerCase();
+            const isAngle = isAngleBracketNotation(name);
+            // --- 1) lism-css コア: primitives/ の個別ファイルを alias map で解決 ---
+            //   angle-bracket 形式 (`<Vertical>`) は React コンポーネント alias のみと照合し、
+            //   クラス専用プリミティブ (is--vertical 等) への false positive を避ける。
+            if (!pkg || pkg === 'lism-css') {
+                const componentHit = getComponentAliasMap().get(normalizedKey);
+                if (componentHit) {
+                    return markdownResponse(loadMarkdown(componentHit));
+                }
+                if (!isAngle) {
+                    const classHit = getClassAliasMap().get(normalizedKey);
+                    if (classHit) {
+                        return markdownResponse(loadMarkdown(classHit));
+                    }
+                }
+            }
+            // --- 2) lism-css コア: components-core.md のセマンティック/コアコンポーネント ---
+            if (!pkg || pkg === 'lism-css') {
+                const coreMd = loadMarkdown('components-core.md');
+                // 見出しにコンポーネント名を含むセクションを検索（Lism, HTML 等）
+                const coreLines = coreMd.split('\n');
+                const headingLine = coreLines.find((l) => /^#{2,3}\s/.test(l) && l.toLowerCase().includes(`<${rawLower}>`));
+                if (headingLine) {
+                    const headingText = headingLine.replace(/^#+\s*/, '').trim();
+                    const section = findComponentByHeading(coreMd, headingText);
+                    if (section)
+                        return markdownResponse(section);
+                }
+                // テーブル内の `<ComponentName>` で検索
+                const coreSection = findComponentInTables(coreMd, name);
+                if (coreSection) {
+                    return markdownResponse(coreSection);
+                }
+            }
+            // --- 3) @lism-css/ui: components-ui.md を検索 ---
+            if (!pkg || pkg === '@lism-css/ui') {
+                const uiMd = loadMarkdown('components-ui.md');
+                // ## ComponentName 形式の見出しで検索（完全一致）
+                const uiSection = findComponentByHeading(uiMd, name);
+                if (uiSection) {
+                    return markdownResponse(uiSection);
+                }
+                // 大文字小文字を無視した見出し検索
+                const uiLines = uiMd.split('\n');
+                const headingLine = uiLines.find((l) => l.startsWith('## ') && l.slice(3).trim().toLowerCase() === rawLower);
+                if (headingLine) {
+                    const section = findComponentByHeading(uiMd, headingLine.slice(3).trim());
+                    if (section)
+                        return markdownResponse(section);
+                }
             }
-            const nameLower = name.toLowerCase();
-            // Step 1: 名前の完全一致
-            const exact = candidates.find((c) => c.name.toLowerCase() === nameLower);
-            if (exact) {
-                return success({ component: exact });
+            // --- 4) 部分一致で候補を提示 ---
+            const uiMd = loadMarkdown('components-ui.md');
+            const coreMd = loadMarkdown('components-core.md');
+            const moduleCandidates = [];
+            if (!pkg || pkg === 'lism-css') {
+                const seenFiles = new Set();
+                for (const map of [getComponentAliasMap(), getClassAliasMap()]) {
+                    for (const [key, file] of map) {
+                        if (key.includes(normalizedKey) && !seenFiles.has(file)) {
+                            seenFiles.add(file);
+                            moduleCandidates.push(file.replace(/^primitives\//, '').replace(/\.md$/, ''));
+                        }
+                    }
+                }
             }
-            // Step 2: aliases マッチ（用途ベースの検索、完全一致）
-            const aliasMatches = candidates.filter((c) => c.aliases?.some((a) => a.toLowerCase() === nameLower));
-            if (aliasMatches.length === 1) {
-                return success({ component: aliasMatches[0], matchedBy: 'alias' });
+            const coreCandidates = [];
+            if (!pkg || pkg === 'lism-css') {
+                for (const line of coreMd.split('\n')) {
+                    if (line.startsWith('|') && line.toLowerCase().includes(rawLower)) {
+                        const match = line.match(/`<([^>]+)>`/);
+                        if (match)
+                            coreCandidates.push(match[1]);
+                    }
+                }
             }
-            if (aliasMatches.length > 1) {
-                const suggestions = aliasMatches.map((c) => ({
-                    name: c.name,
-                    package: c.package,
-                    description: c.description,
-                }));
-                return notFound(`Component "${name}" not found by name, but ${aliasMatches.length} components matched by alias. Did you mean one of these?`, { suggestions });
+            const uiCandidates = [];
+            if (!pkg || pkg === '@lism-css/ui') {
+                for (const l of uiMd.split('\n')) {
+                    if (l.startsWith('## ') && l.toLowerCase().includes(rawLower)) {
+                        uiCandidates.push(l.slice(3).trim());
+                    }
+                }
             }
-            // Step 3: 名前の部分一致
-            const suggestions = candidates.filter((c) => c.name.toLowerCase().includes(nameLower)).map((c) => ({ name: c.name, package: c.package }));
+            const suggestions = [...new Set([...moduleCandidates, ...coreCandidates, ...uiCandidates])];
             if (suggestions.length > 0) {
                 return notFound(`Component "${name}" not found. Did you mean one of these? Or try search_docs with a broader query.`, {
                     suggestions,
                 });
             }
-            const available = candidates.map((c) => ({ name: c.name, package: c.package }));
-            return notFound(`Component "${name}" not found. Try search_docs to find related pages.`, { availableComponents: available });
+            return notFound(`Component "${name}" not found. Try search_docs or get_guide to find related pages.`, {
+                tip: 'Use get_guide with topic="components-core" or "components-ui" to see all available components.',
+            });
         }
         catch (e) {
-            return error(`Failed to load component data: ${e instanceof Error ? e.message : String(e)}. The data files may not be built yet. Ensure the server was installed correctly.`);
+            return error(`Failed to load component data: ${e instanceof Error ? e.message : String(e)}. The data files may not be built yet. Run "pnpm build" in packages/mcp first.`);
         }
     });
 }

package/dist/tools/get-guide.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerGetGuide(server: McpServer): void;

package/dist/tools/get-guide.js

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+import { loadMarkdown } from '../lib/load-markdown.js';
+import { markdownResponse, error, READ_ONLY_ANNOTATIONS } from '../lib/response.js';
+const GUIDE_TOPICS = {
+    overview: { file: 'SKILL.md', label: 'Framework overview, packages, implementation rules' },
+    tokens: { file: 'tokens.md', label: 'Design tokens (spacing, colors, font sizes, etc.)' },
+    'property-class': { file: 'property-class.md', label: 'Property Class system, all props reference table' },
+    'components-core': {
+        file: 'components-core.md',
+        label: 'Core component system (Lism, Box, Flex, Stack, Grid, etc.)',
+    },
+    'components-ui': {
+        file: 'components-ui.md',
+        label: 'UI components (Accordion, Modal, Tabs, Button, etc.)',
+    },
+    'base-styles': { file: 'base-styles.md', label: 'Base styling, reset CSS, HTML element styles' },
+    'set-class': { file: 'set-class.md', label: 'Set classes (set--plain, set--shadow, set--hov, etc.)' },
+    'primitive-class': { file: 'primitive-class.md', label: 'Primitive class prefixes (is--, l--, a--) and Component class (c--)' },
+    'utility-class': { file: 'utility-class.md', label: 'Utility classes (u--trim, u--cbox, etc.)' },
+    'css-rules': { file: 'css-rules.md', label: 'CSS methodology, layer structure, naming conventions' },
+    responsive: { file: 'prop-responsive.md', label: 'Responsive design, breakpoints, container queries' },
+};
+const TOPIC_DESCRIPTION = Object.entries(GUIDE_TOPICS)
+    .map(([key, { label }]) => `- ${key}: ${label}`)
+    .join('\n');
+export function registerGetGuide(server) {
+    server.registerTool('get_guide', {
+        description: 'Get a detailed guide on a specific lism-css topic. Use this when you need comprehensive documentation on a broad topic rather than a specific component or prop.\n' +
+            'For individual component lookup, get_component is more direct. For individual prop lookup, use get_props_system.\n' +
+            'The response is the full guide as pre-formatted Markdown. Output it verbatim. Do NOT summarize or omit sections.\n' +
+            `\nAvailable topics:\n${TOPIC_DESCRIPTION}`,
+        inputSchema: {
+            topic: z.enum(Object.keys(GUIDE_TOPICS)).describe('The guide topic to retrieve.'),
+        },
+        annotations: READ_ONLY_ANNOTATIONS,
+    }, ({ topic }) => {
+        try {
+            const { file } = GUIDE_TOPICS[topic];
+            return markdownResponse(loadMarkdown(file));
+        }
+        catch (e) {
+            return error(`Failed to load guide "${topic}": ${e instanceof Error ? e.message : String(e)}. The data files may not be built yet. Run "pnpm build" in packages/mcp first.`);
+        }
+    });
+}

package/dist/tools/get-overview.js

@@ -1,53 +1,40 @@
-import { loadJSON } from '../lib/load-data.js';
-import { OverviewDataSchema } from '../lib/schemas.js';
+import { loadMarkdown } from '../lib/load-markdown.js';
+import { extractSection } from '../lib/markdown-utils.js';
 import { markdownResponse, error, READ_ONLY_ANNOTATIONS } from '../lib/response.js';
-import { meta } from '../data/meta.js';
-function toMarkdown(data) {
-    const lines = [];
-    lines.push(`# lism-css Overview`);
-    lines.push('');
-    lines.push(`> Generated at: ${meta.generatedAt} | Source commit: ${meta.sourceCommit} | Docs version: ${meta.docsVersion}`);
-    lines.push('');
-    lines.push(`## Description`);
-    lines.push('');
-    lines.push(data.description);
-    lines.push('');
-    lines.push(`## Architecture`);
-    lines.push('');
-    lines.push(data.architecture);
-    lines.push('');
-    lines.push(`## Packages`);
-    lines.push('');
-    for (const pkg of data.packages) {
-        lines.push(`- **${pkg.name}** (\`${pkg.npmName}\` v${pkg.version}): ${pkg.description}`);
+/**
+ * SKILL.md を中核に、css-rules.md の Layer 構造セクションと
+ * prop-responsive.md のブレークポイントセクションを付加して返す。
+ */
+function buildOverviewMarkdown() {
+    const skill = loadMarkdown('SKILL.md');
+    const cssRules = loadMarkdown('css-rules.md');
+    const responsive = loadMarkdown('prop-responsive.md');
+    const layerSection = extractSection(cssRules, 'CSS Layer 構造');
+    const bpSection = extractSection(responsive, 'ブレークポイント');
+    const parts = [skill];
+    if (layerSection) {
+        parts.push('\n---\n');
+        parts.push(layerSection);
     }
-    lines.push('');
-    lines.push(`## Breakpoints`);
-    lines.push('');
-    for (const [key, value] of Object.entries(data.breakpoints)) {
-        lines.push(`- \`${key}\`: ${value}`);
+    if (bpSection) {
+        parts.push('\n---\n');
+        parts.push(bpSection);
     }
-    lines.push('');
-    lines.push(`## CSS Layers`);
-    lines.push('');
-    lines.push(data.cssLayers);
-    lines.push('');
-    lines.push(`## Installation`);
-    lines.push('');
-    lines.push(data.installation);
-    return lines.join('\n');
+    return parts.join('\n');
 }
 export function registerGetOverview(server) {
     server.registerTool('get_overview', {
-        description: 'Get an overview of the lism-css framework: architecture, design philosophy, packages, breakpoints, installation guide, and CSS layers. Start here to understand the framework before using other tools.',
+        description: 'Get an overview of the lism-css framework: architecture, design philosophy, packages, breakpoints, CSS layers, and implementation rules.\n' +
+            'Use this as your FIRST call when starting any lism-css task — it provides the foundational context needed to use other tools effectively.\n' +
+            'Do NOT use this to look up specific components (use get_component), individual props (use get_props_system), or design tokens (use get_tokens).\n' +
+            'The response is pre-formatted Markdown. Output it verbatim to the user. Do NOT summarize or omit sections.',
         annotations: READ_ONLY_ANNOTATIONS,
     }, () => {
         try {
-            const data = loadJSON('overview.json', OverviewDataSchema);
-            return markdownResponse(toMarkdown(data));
+            return markdownResponse(buildOverviewMarkdown());
         }
         catch (e) {
-            return error(`Failed to load overview data: ${e instanceof Error ? e.message : String(e)}. The data files may not be built yet. Ensure the server was installed correctly.`);
+            return error(`Failed to load overview data: ${e instanceof Error ? e.message : String(e)}. The data files may not be built yet. Run "pnpm build" in packages/mcp first.`);
         }
     });
 }