@lism-css/mcp 0.28.0 → 0.28.1

package/README.ja.md

@@ -9,7 +9,7 @@ AIツール（Claude Code, Cursor 等）が、インストールされている
 
 | ツール | 説明 |
 |--------|------|
-| `get_overview` | フレームワークの全体像（アーキテクチャ、設計思想、パッケージ構成、ブレークポイント、CSS Layers、実装ルール） |
+| `get_overview` | フレームワークの全体像（基本ルール、何を書く前にどの資料を引くか、目的別のPrimitive/コンポーネント選定、クラス一覧、CSS Layers、ブレークポイント） |
 | `get_tokens` | デザイントークン（色、余白、フォントサイズ、影、角丸など）のリファレンス全文を取得 |
 | `get_props_system` | Propsシステム対応表 — React/Astro のpropsがCSSクラス・スタイルにどう変換されるか。CSSプロパティ名での逆引き（例: `padding` → `p`）や Property Class 記法（`-g:5` 等）にも対応 |
 | `get_component` | コンポーネント詳細（props、使用例、サブコンポーネント構成）。パッケージ（`lism-css` / `@lism-css/ui`）での絞り込みも可能 |

package/README.md

@@ -9,7 +9,7 @@ Enables AI tools (Claude Code, Cursor, etc.) to accurately reference Lism CSS do
 
 | Tool | Description |
 |------|-------------|
-| `get_overview` | Framework overview (architecture, design philosophy, packages, breakpoints, CSS layers, implementation rules) |
+| `get_overview` | Framework overview (core rules, which reference to look up before writing what, primitive/component selection by goal, class inventory, CSS layers, breakpoints) |
 | `get_tokens` | Get the full design token reference (colors, spacing, font sizes, shadows, radii, etc.) |
 | `get_props_system` | Props system reference — how React/Astro props map to CSS classes and styles. Supports reverse lookup by CSS property name (e.g. `padding` → `p`) and Property Class notation (e.g. `-g:5`) |
 | `get_component` | Component details (props, usage examples, sub-component structure). Optionally filter by package (`lism-css` or `@lism-css/ui`) |

package/dist/data/guides/references/page-sections.md

@@ -1,6 +1,6 @@
 # ページ定番セクションの構成例
 
-ヒーロー・サイトヘッダー・フッターなど、ページの定番セクションを`Group`/`Wrapper`/`Stack`＋Propsで組む時の出発点です。ここにある構成をベースにし、実際の値は値・トークン照合（C5）を通してから確定します。
+ヒーロー・サイトヘッダー・フッターなど、ページの定番セクションを`Group`/`Wrapper`/`Stack`＋Propsで組む時の出発点です。ここにある構成をベースにし、実際の値は`tokens.md`のトークンと照合してから確定します。
 
 共通の考え方:
 
@@ -94,6 +94,6 @@ import { Group, Wrapper, Stack, Heading, Columns } from 'lism-css/astro';
 
 ## 使う前の確認
 
-- 使うPrimitive/Traitの詳細ファイル（`primitives/l--*.md`・`trait-class/*.md`）を、`SKILL.md`の資料確認トリガーに従って読む。
+- 使うPrimitive/Traitの詳細ファイル（`primitives/*.md`・`trait-class/*.md`）で、既定のスタイル・Props・CSS変数を確認する。
 - レスポンシブ値（配列・オブジェクト指定）を使う場合は、祖先の`isContainer`または`@media`運用の確認が必要（[`responsive.md`](../responsive.md)）。
-- ここに書いた値はすべて例。実際のデザイン値は`tokens.md`との照合（C5）とトークン差分表を通す。
+- ここに書いた値はすべて例。実際のデザイン値を`tokens.md`と照合し、使うトークンを決める。

package/dist/lib/markdown-utils.d.ts

@@ -1,5 +1,7 @@
 /** 指定見出しから同レベル以上の次の見出しまでを抽出する。headingは#の有無を問わない。 */
 export declare function extractSection(md: string, heading: string): string;
+/** 冒頭（frontmatter を除き、最初の `##` 見出しの手前まで）を返す。H1 は含む。 */
+export declare function extractPreamble(md: string): string;
 export declare function listHeadings(md: string): {
     level: number;
     text: string;

package/dist/lib/markdown-utils.js

@@ -28,6 +28,13 @@ export function extractSection(md, heading) {
     }
     return lines.slice(startIdx, endIdx).join('\n').trimEnd();
 }
+/** 冒頭（frontmatter を除き、最初の `##` 見出しの手前まで）を返す。H1 は含む。 */
+export function extractPreamble(md) {
+    const body = md.replace(/^---\n[\s\S]*?\n---\n/, '');
+    const lines = body.split('\n');
+    const endIdx = lines.findIndex((line) => headingLevel(line) >= 2);
+    return (endIdx === -1 ? lines : lines.slice(0, endIdx)).join('\n').trim();
+}
 export function listHeadings(md) {
     return md.split('\n').flatMap((line, i) => {
         const lv = headingLevel(line);

package/dist/lib/search.js

@@ -97,6 +97,9 @@ function getBasename(withoutExt) {
 function getNextTool(entry, guideTopics) {
     const withoutExt = entry.sourcePath.replace(/\.mdx$/, '');
     const basename = getBasename(withoutExt);
+    if (withoutExt === 'overview') {
+        return 'get_overview()';
+    }
     if (withoutExt === 'core-components/lism-props') {
         return 'get_props_system()';
     }

package/dist/tools/convert-css.js

@@ -124,7 +124,8 @@ function detectComponent(declarations) {
     const display = propMap.get('display');
     const flexDirection = propMap.get('flex-direction');
     const placeItems = propMap.get('place-items');
-    if (display === 'flex' && (flexDirection === 'column' || flexDirection === 'column-reverse')) {
+    // column-reverse は Stack にせず、Flex + fxd で方向を保つ。
+    if (display === 'flex' && flexDirection === 'column') {
         return {
             name: 'Stack',
             reason: 'display: flex + flex-direction: column → Stack (vertical flex)',
@@ -161,20 +162,25 @@ function findCategory(mappings, propName) {
     const found = mappings.find((m) => m.prop === propName);
     return found?.sectionName ?? 'unknown';
 }
+/** `property: value` を比較用に正規化する。 */
+function normalizeDeclaration(css) {
+    const [prop, ...rest] = css.split(':');
+    return `${prop.trim().toLowerCase()}: ${rest.join(':').trim().toLowerCase()}`;
+}
 /** 変換結果からJSX使用例を組み立てる。 */
 function buildExample(conversions, component) {
     const tagName = component?.name ?? 'Lism';
-    const implicitCssSet = new Set(component?.implicitCss.map((c) => c.split(':')[0].trim()) ?? []);
+    // プロパティ名だけで照合すると値違い（例: flex-direction: column-reverse）まで落ちるため、値込みで照合する。
+    const implicitCssSet = new Set(component?.implicitCss.map(normalizeDeclaration) ?? []);
     const props = [];
     const styles = [];
     for (const conv of conversions) {
-        const cssProp = conv.css.split(':')[0].trim();
         if (!conv.lismProp) {
             styles.push(conv.css);
             continue;
         }
         // コンポーネントが暗黙に持つCSSは重複出力しない。
-        if (implicitCssSet.has(cssProp))
+        if (implicitCssSet.has(normalizeDeclaration(conv.css)))
             continue;
         if (conv.suggestedValue != null) {
             props.push(`${conv.lismProp}='${conv.suggestedValue}'`);

package/dist/tools/get-component.js

@@ -9,7 +9,7 @@ function normalizeComponentKey(input) {
         .trim()
         .toLowerCase()
         .replace(/^<|>$/g, '')
-        .replace(/^(l--|is--|a--|c--)/, '');
+        .replace(/^(l--|is--|has--|a--|c--)/, '');
 }
 /** 入力が `<ComponentName>` 形式（React コンポーネントとしての問い合わせ）か判定する */
 function isAngleBracketNotation(input) {
@@ -18,7 +18,7 @@ function isAngleBracketNotation(input) {
 /** 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]+)>`)?/);
+    const match = firstLine.match(/^#\s+((?:l|is|has|a|c)--[A-Za-z0-9]+)(?:\s*\/\s*`<([A-Za-z0-9]+)>`)?/);
     if (!match)
         return null;
     return { className: match[1], componentName: match[2] };
@@ -63,7 +63,7 @@ export function registerGetComponent(server) {
             '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.',
+            'The response is Markdown reference material. Use it as context; when you write code, follow the code examples and class names exactly as documented rather than inventing variants.',
         inputSchema: {
             name: z.string().describe('Component name to look up (e.g. "Box", "Flex", "Accordion", "l--flex", "<Flex>").'),
             package: z

package/dist/tools/get-guide.js

@@ -4,7 +4,6 @@ import { markdownResponse, loadFailureError, READ_ONLY_ANNOTATIONS } from '../li
 // files に複数指定したトピックは結合して返す。
 // MCP クライアントは Markdown 内の相対リンクを辿れないため、分冊ファイルは本体に結合する。
 const GUIDE_TOPICS = {
-    overview: { files: ['SKILL.md'], label: 'Framework overview, packages, implementation rules' },
     tokens: { files: ['tokens.md'], label: 'Design tokens (spacing, colors, font sizes, etc.)' },
     'property-class': {
         files: ['property-class.md', 'property-class/all-props.md', 'property-class/bd.md', 'property-class/hov.md', 'property-class/max-sz.md'],
@@ -47,6 +46,10 @@ const GUIDE_TOPICS = {
         files: ['antipatterns-layout.md'],
         label: 'AI code-generation antipatterns (structure / layout / responsive): layout choice errors, responsive omissions, is-- misuse, naming mistakes',
     },
+    'page-sections': {
+        files: ['references/page-sections.md'],
+        label: 'Standard page section patterns (hero, site header, footer, etc.) built from Group + Wrapper / Stack / Cluster',
+    },
 };
 /** get_guide が受理するトピックキーの集合。search.ts の nextTool 判定で利用する。 */
 export const GUIDE_TOPIC_KEYS = new Set(Object.keys(GUIDE_TOPICS));
@@ -56,8 +59,8 @@ const TOPIC_DESCRIPTION = Object.entries(GUIDE_TOPICS)
 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' +
+            'For the framework overview, use get_overview. 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 Markdown reference material. Use it as context; apply its rules and examples exactly as documented rather than paraphrasing them from memory.\n' +
             `\nAvailable topics:\n${TOPIC_DESCRIPTION}`,
         inputSchema: {
             topic: z.enum(Object.keys(GUIDE_TOPICS)).describe('The guide topic to retrieve.'),

package/dist/tools/get-overview.js

@@ -1,33 +1,53 @@
 import { loadMarkdown } from '../lib/load-markdown.js';
-import { extractSection } from '../lib/markdown-utils.js';
+import { extractPreamble, extractSection } from '../lib/markdown-utils.js';
 import { markdownResponse, loadFailureError, READ_ONLY_ANNOTATIONS } from '../lib/response.js';
 /**
- * SKILL.md を中核に、css-rules.md の Layer 構造セクションと
- * responsive.md のブレイクポイントセクションを付加して返す。
+ * SKILL.md から MCP でも意味を持つ節だけを抜き出す。
+ * 実装フロー・判定記号・C0–C8・実行レベル・提出前セルフチェックはスキル（ファイル参照と `.lism/` 保存）前提の作業手順なので含めない。
  */
+const SKILL_SECTIONS = ['最小ゲート', '資料確認トリガー', '目的別実装ガイド', 'クラス単位の詳細リファレンス'];
+/** 抜き出した節に残るガイドファイル名・判定記号を MCP ツールへ読み替えるための案内。 */
+const TOOL_ROUTING = `## Looking up details with this MCP server
+
+Guide file names mentioned below map to tools as follows:
+
+- \`primitives/*.md\`, \`trait-class/*.md\` → \`get_component\` with the class or component name (e.g. "l--stack", "Stack", "a--icon", "is--container", "has--transition")
+- \`tokens.md\` → \`get_tokens\`
+- \`property-class.md\`, \`property-class/*.md\` → \`get_props_system\` for a single prop, or \`get_guide\` topic "property-class" for the whole system
+- \`references/page-sections.md\` → \`get_guide\` topic "page-sections"
+- Any other \`*.md\` → \`get_guide\` with the topic of the same name (e.g. \`css-rules.md\` → "css-rules", \`antipatterns.md\` → "antipatterns")
+- Keyword search across all docs → \`search_docs\`; bulk CSS-to-Lism conversion → \`convert_css\`
+
+Markers used in the rules below: 🔁 = look up the referenced guide before writing that code; ⏸ = confirm with the user before implementing (hardcoded px values, rounding to a nearby token, changing public classes, etc.). Do not write code while a decision is still 🔁. A hardcoded value is allowed as a documented exception (✅例外) only when the "直書きしてよい例外" section of \`antipatterns.md\` (\`get_guide\` topic "antipatterns") lists that case; user instructions such as "reproduce it exactly" do not count.`;
 function buildOverviewMarkdown() {
     const skill = loadMarkdown('SKILL.md');
     const cssRules = loadMarkdown('css-rules.md');
     const responsive = loadMarkdown('responsive.md');
+    // 冒頭（タイトル・公式ドキュメント URL・対象バージョン）。
+    // スキルの作業手順（実行レベル判定→セルフチェック）の一文は落とし、スキル更新の案内は MCP 向けに読み替える。
+    const preamble = extractPreamble(skill)
+        .replace(/変更規模から実行レベルを判定し、[^。]*。/, '')
+        .replace('このスキルの更新', '`@lism-css/mcp`の更新');
+    const parts = [preamble, TOOL_ROUTING];
+    for (const heading of SKILL_SECTIONS) {
+        const section = extractSection(skill, heading);
+        if (section)
+            parts.push(section);
+    }
     const layerSection = extractSection(cssRules, 'CSS Layer 構造');
-    const bpSection = extractSection(responsive, 'ブレイクポイント');
-    const parts = [skill];
-    if (layerSection) {
-        parts.push('\n---\n');
+    if (layerSection)
         parts.push(layerSection);
-    }
-    if (bpSection) {
-        parts.push('\n---\n');
+    const bpSection = extractSection(responsive, 'ブレイクポイント');
+    if (bpSection)
         parts.push(bpSection);
-    }
-    return parts.join('\n');
+    return parts.join('\n\n---\n\n');
 }
 export function registerGetOverview(server) {
     server.registerTool('get_overview', {
-        description: 'Get an overview of the lism-css framework: architecture, design philosophy, packages, breakpoints, CSS layers, and implementation rules.\n' +
+        description: 'Get an overview of the lism-css framework: core rules (minimum gates), which reference to look up before writing what, primitive/component selection by goal, class inventory, CSS layers, and breakpoints.\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.',
+            'The response is Markdown reference material. Use it as context for your answer or implementation; do not paraphrase rules or invent class names, props, or token values that are not in it.',
         annotations: READ_ONLY_ANNOTATIONS,
     }, () => {
         try {

package/dist/tools/get-props-system.js

@@ -16,7 +16,7 @@ export function registerGetPropsSystem(server) {
         description: 'Get the lism-css Props system reference: how React/Astro props map to CSS classes and styles. Supports lookup by lism prop name (e.g. "p", "fz") OR by CSS property name (e.g. "padding", "font-size"). Omit the prop parameter to get the full reference.\n' +
             'Use this when you need to find a specific prop mapping, understand the Property Class system, or check what CSS property a lism prop corresponds to.\n' +
             'For bulk CSS-to-lism conversion, convert_css is more efficient. For component-specific documentation, use get_component.\n' +
-            'The response is pre-formatted Markdown. Output it verbatim. Do NOT summarize the prop tables.',
+            'The response is Markdown reference material. Use prop names and preset values exactly as listed in the tables; do not invent props or values that are not there.',
         inputSchema: {
             prop: z
                 .string()

package/dist/tools/get-tokens.js

@@ -5,7 +5,7 @@ export function registerGetTokens(server) {
         description: 'Get design tokens (colors, spacing, font sizes, shadows, etc.) used in lism-css. Returns the full token reference including CSS variable names and available values.\n' +
             'Use this when you need to check available token values, variable names, or design scales (e.g. "what spacing values exist?", "what are the font size tokens?").\n' +
             'For prop-to-CSS mappings, get_props_system is more suitable. For CSS conversion, use convert_css. Call get_overview first if you have not yet.\n' +
-            'The response is pre-formatted Markdown. Output it verbatim. Do NOT summarize or omit token values.',
+            'The response is Markdown reference material. Use token names and values exactly as listed; do not invent tokens or values that are not there.',
         annotations: READ_ONLY_ANNOTATIONS,
     }, () => {
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lism-css/mcp",
-  "version": "0.28.0",
+  "version": "0.28.1",
   "description": "MCP server for lism-css documentation and API reference.",
   "keywords": [
     "mcp",