@makitt.io/mds-mcp-server 0.1.3 → 0.2.0

package/README.md

@@ -1,29 +1,72 @@
 # @makitt.io/mds-mcp-server
 
 MCP (Model Context Protocol) server for `@makitt/mds`. AI 가 mds 의 catalog +
-playbook 을 자동 query — fabrication 0 보장의 최종 layer.
+playbook + recipe 를 자동 query — fabrication 0 보장의 최종 layer.
 
-> **Registry**: npmjs.org (표준 public npm registry). `.npmrc` 별도 setup 없이 install 가능.
+> **Registry**: npmjs.org (표준 public npm registry). `.npmrc` 별도 setup 없이
+> install 가능.
 
 ## 무엇을 하는가
 
 Claude Code / Cursor 같은 AI 도구가 다음을 자동 query:
 
-- **컴포넌트 spec** — props / types / JSDoc / stories (301 components in catalog.json)
-- **Playbook 9 영역** — form / feedback / data-grid / overlay / page-layout / array-input / async-states / ai-fill / anti-patterns
+- **컴포넌트 contract** — public import / props / enum values / type shapes /
+  JSDoc / Storybook URLs / story source
+- **Playbook 영역** — form / feedback / data-grid / overlay / page-layout /
+  array-input / async-states / ai-fill / anti-patterns
+- **MDS-only composition recipes** — admin list page / settings form page /
+  modal form / detail drawer / dashboard overview / async state section
 - **결정 표 검색** — "modal-form vs page-form 어떻게 선택?" → playbook 안 lookup
-- **안티패턴 자동 검출** — 작성 코드의 mds rule 위반 식별
+- **안티패턴 조회/가드레일** — playbook 기반으로 사용 전 금지 패턴 확인
 
 ## Tools
 
-| Tool | 용도 |
-|---|---|
-| `mds_components_list` | 모든 mds 컴포넌트 list (layer 필터 가능) |
-| `mds_components_get` | 특정 컴포넌트의 full spec (props / types / JSDoc) |
-| `mds_components_search` | 컴포넌트 name / description / prop 에 대한 text search |
-| `mds_playbook_list` | 9 Playbook 영역 list |
-| `mds_playbook_get` | 특정 Playbook 의 full content (markdown) |
-| `mds_playbook_search` | 모든 Playbook 의 decision matrix / 안티패턴 text search |
+| Tool                         | 용도                                                                                            |
+| ---------------------------- | ----------------------------------------------------------------------------------------------- |
+| `mds_codegen_plan`           | 새 페이지/기능 codegen 시작점. task → recipe/playbook/component 후속 조회 계획 + guardrail 반환 |
+| `mds_components_list`        | public JSX component / compound part list. 기본 compact, helper/type/internal 숨김              |
+| `mds_components_get`         | 특정 컴포넌트의 full contract (import / props / enum values / type shapes / stories / examples) |
+| `mds_components_search`      | alias / dot name / prop / enum value / type / story normalized search                           |
+| `mds_component_examples_get` | Storybook URL / iframe URL / story source / JSDoc examples                                      |
+| `mds_playbook_list`          | Playbook 영역 list                                                                              |
+| `mds_playbook_get`           | 특정 Playbook 의 full content (markdown)                                                        |
+| `mds_playbook_search`        | 모든 Playbook 의 decision matrix / 안티패턴 text search                                         |
+| `mds_recipes_list`           | MDS-only composition recipe list                                                                |
+| `mds_recipes_get`            | 특정 recipe 의 full MDS composition contract                                                    |
+| `mds_recipes_search`         | recipe content text search                                                                      |
+
+## Agent Codegen Contract
+
+MCP 응답은 AI agent 가 MDS UI 를 바로 작성할 수 있게 아래 정보를 제공한다.
+
+- `kind` — `component`, `compoundPart`, `hook`, `helper`, `type`, `store`,
+  `internal`
+- `status` — `implemented`, `planned`, `deprecated`, `internal`
+- `import.statement` — 실제 코드에서 써야 하는 public import
+- `props[].values` — union / enum literal values
+- `types` — `ColumnDef<T>`, `SortState`, `TableDensity` 같은 참조 타입 shape
+- `storybook[].storyUrl` / `iframeUrl` — browser agent 가 직접 열 visual oracle
+- `storybook[].source` — 해당 story 의 source snippet
+- `examples` — component JSDoc `@example`
+
+기본 `mds_components_list` 는 실제 JSX 로 조립 가능한 public component 와
+compound part 만 반환한다. `insertImage`, `$isImageNode`,
+`NotificationRootProps` 같은 helper / type / internal symbol 은
+`includeInternal: true` 를 명시한 경우에만 탐색 대상이다.
+
+Agent 의 표준 사용 순서:
+
+0. `mds_codegen_plan` 으로 task 에 맞는 recipe / playbook / component 조회
+   순서를 잡는다.
+1. `mds_recipes_search` 또는 `mds_recipes_get` 으로 MDS-only 조립 패턴을
+   확인한다.
+2. `mds_playbook_get` 으로 page/form/data/overlay 결정 기준을 확인한다.
+3. `mds_components_search` 로 후보를 찾는다.
+4. `mds_components_get` 으로 import, prop values, type shape 를 확인한다.
+5. `mds_component_examples_get` 의 Storybook `iframeUrl` 을 browser/screenshot
+   도구로 열어 실제 렌더링을 확인한다.
+6. 생성한 페이지도 Playwright/Storybook screenshot 으로 desktop/mobile overflow
+   와 interaction 을 확인한다.
 
 ## 설치
 
@@ -33,13 +76,14 @@ Claude Code / Cursor 같은 AI 도구가 다음을 자동 query:
 claude mcp add mds -- npx -y @makitt.io/mds-mcp-server@latest
 ```
 
-→ npmjs.org 에서 자동 fetch + 실행. self-contained (embedded catalog + playbook). 별도 auth / scope mapping 없음.
+→ npmjs.org 에서 자동 fetch + 실행. self-contained (embedded catalog +
+playbook + recipe). 별도 auth / scope mapping 없음.
 
 ### B. Local build (mds 개발자 monorepo)
 
 ```bash
 cd packages/mds && pnpm build       # catalog.json 생성
-cd ../mds-mcp-server && pnpm build  # tsc + copy:data
+cd ../mds-mcp-server && pnpm build  # tsc + data/release verify + dogfood + stdio smoke + pack verify
 claude mcp add mds -- node /absolute/path/.../mds-mcp-server/dist/index.js
 ```
 
@@ -49,6 +93,7 @@ claude mcp add mds -- node /absolute/path/.../mds-mcp-server/dist/index.js
 claude mcp add mds \
   -e MDS_CATALOG_PATH=/path/to/your/catalog.json \
   -e MDS_PLAYBOOK_DIR=/path/to/your/playbook \
+  -e MDS_RECIPE_DIR=/path/to/your/recipes \
   -- npx -y @makitt.io/mds-mcp-server@latest
 ```
 
@@ -72,20 +117,41 @@ AI: (mds_playbook_get 'form' 자동 호출 → 결정 표 lookup)
 
 ## Path resolution 우선순위
 
-1. **env var** (`MDS_CATALOG_PATH` / `MDS_PLAYBOOK_DIR`) — 외부 customize
+1. **env var** (`MDS_CATALOG_PATH` / `MDS_PLAYBOOK_DIR` / `MDS_RECIPE_DIR`) —
+   외부 customize
 2. **embedded data** (`dist/data/`) — published package 의 self-contained
 3. **monorepo relative** (`../../mds/`) — dev fallback
 
 ## Build (data 자동 embed)
 
 ```bash
-pnpm build  # tsc + scripts/copy-data.mjs
+pnpm build  # tsc + copy:data + verify:data + dogfood + smoke:stdio + verify:pack
 ```
 
 - `tsc` — TypeScript compile (`dist/index.js`)
-- `copy-data.mjs` — `../mds/dist/catalog.json` + `../mds/docs/playbook/` 을 `dist/data/` 로 복사
+- `copy-data.mjs` — `../mds/dist/catalog.json` + `../mds/docs/playbook/` +
+  `../mds/docs/recipes/` 를 `dist/data/` 로 복사
+- `verify-data.mjs` — embedded catalog/playbook/recipe 누락과 버전 메타 검증
+- `dogfood.mjs` — build 된 MCP API 로 전체 recipe reachability, recipe 참조
+  component, compound namespace overview, 대표 agent 시나리오 검증
+- `smoke-stdio.mjs` — MCP SDK client 로 `node dist/index.js` 실제 stdio
+  transport 호출 검증
+- `verify-pack.mjs` — `npm pack --dry-run` payload 에 embedded data 포함,
+  source/script 누출 없음 검증
 
-→ self-contained package. `files: ["dist", "README.md"]` 가 npm publish 에 포함됨.
+→ self-contained package. `files: ["dist", "README.md"]` 가 npm publish 에
+포함됨.
+
+## Release policy
+
+```bash
+pnpm verify:release
+```
+
+- `verify-release.mjs` — Changesets/publish policy, npm files contract,
+  README publish guide 검증
+- CI와 `prepublishOnly`에서 실행한다. 앱/로컬 빌드가 루트 `.changeset` 메타데이터에
+  묶이지 않도록 `pnpm build`에는 포함하지 않는다.
 
 ## Transport
 
@@ -97,9 +163,12 @@ npm registry (`registry.npmjs.org`) 에 `@makitt.io/mds-mcp-server` 를 publish.
 
 ### 첫 setup — Granular Access Token (공용 계정 권장)
 
-공용 npm 계정 (예: `techtaka-makitt`) publish 흐름을 자동화 — 매번 2FA OTP race 에는 부적합. **Granular Access Token + bypass 2FA** 를 1회 setup 하면 이후 publish 가 자동.
+공용 npm 계정 (예: `techtaka-makitt`) publish 흐름을 자동화 — 매번 2FA OTP race
+에는 부적합. **Granular Access Token + bypass 2FA** 를 1회 setup 하면 이후
+publish 가 자동.
 
-1. **token 생성** — https://www.npmjs.com/settings/<username>/tokens/granular-access-tokens/new
+1. **token 생성** —
+   https://www.npmjs.com/settings/<username>/tokens/granular-access-tokens/new
    - **Token name**: `mds-mcp-server publish` (또는 유의미한 라벨)
    - **Expiration**: 1 year (또는 정책 따라)
    - **Allowed IP ranges**: 비워두기 (또는 CI / 사무실 IP)
@@ -108,35 +177,66 @@ npm registry (`registry.npmjs.org`) 에 `@makitt.io/mds-mcp-server` 를 publish.
      - Permissions: **Read and write**
    - **Bypass 2FA**: ✓ enable (publish 시 OTP 요구하지 않음)
    - Generate token → 값 복사 (한 번만 표시)
-2. **token 을 공용 vault 에 share** — 1Password / LastPass / Bitwarden 등 team 공유 entry 에 보관. 채팅 / 코드에 직접 노출 금지
-3. **각 maintainer 의 local setup** — `~/.npmrc` 에 직접 entry 추가 (또는 `npm config set`):
+2. **token 을 공용 vault 에 share** — 1Password / LastPass / Bitwarden 등 team
+   공유 entry 에 보관. 채팅 / 코드에 직접 노출 금지
+3. **각 maintainer 의 local setup** — `~/.npmrc` 에 직접 entry 추가 (또는
+   `npm config set`):
    ```bash
    npm config set //registry.npmjs.org/:_authToken=<token>
    ```
    → `~/.npmrc` 에 추가됨. git ignore 됨 (사용자 home dir).
 
+### Version bump — Changesets
+
+이 repo 의 package version 은 Changesets 로 올린다. `npm version` 으로 직접 bump
+하지 않는다.
+
+- `patch` — MCP answer bugfix, stale embed fix, doc/copy correction
+- `minor` — new MCP tool, new response field, new recipe/playbook surface
+- `major` — tool rename/removal, response shape breaking change, install command
+  breaking change
+
+```bash
+pnpm changeset
+```
+
+예:
+
+```md
+---
+'@makitt.io/mds-mcp-server': minor
+'@makitt/mds': patch
+---
+
+Add MCP codegen planning, stdio smoke, and stricter generated catalog contracts.
+```
+
+MDS 와 MCP 는 결합되어 있다. MDS component/catalog/playbook/recipe 가 바뀌고 MCP
+embedded answer 가 바뀌면 MCP changeset 도 같이 남긴다.
+
 ### Publish 흐름
 
+maintainer 가 release PR/commit 에서:
+
 ```bash
-cd packages/mds-mcp-server
-pnpm build                 # tsc + copy-data (catalog.json + playbook md → dist/data/)
-npm publish --dry-run      # tarball 검증 (file list / size / name / version)
-npm publish                # 실제 publish (bypass 2FA token 으로 자동 처리)
+pnpm version-packages  # changeset version: package.json + changelog 갱신
+pnpm release           # packages build + changeset publish
 ```
 
-### Version bump
+로컬 검증은 publish 전 항상:
 
 ```bash
-npm version patch   # 0.1.0 → 0.1.1 (bugfix)
-npm version minor   # 0.1.0 → 0.2.0 (feature)
-npm version major   # 0.1.0 → 1.0.0 (breaking)
+cd packages/mds-mcp-server
+pnpm build             # data/release verify + dogfood + stdio smoke + pack verify
 ```
 
-→ `package.json` 자동 bump + git tag 자동 생성. push 시 `git push --follow-tags`.
+`verify:pack` 이 이미 `npm pack --dry-run --json` payload 를 검사하므로 별도
+수동 `npm publish --dry-run` 은 보조 확인용이다.
 
 ### 보안
 
-- ❌ token 이 채팅 / git commit / chat log 등으로 leak 시 — 즉시 npmjs.com settings 에서 **Revoke**
+- ❌ token 이 채팅 / git commit / chat log 등으로 leak 시 — 즉시 npmjs.com
+  settings 에서 **Revoke**
 - ❌ 무한 expiration token — 1 year 이내
 - ❌ "Read and write" 모든 scope 허용 — `@makitt.io` specific scope 만 허용
 - ✓ Bypass 2FA enable — 공용 계정 publish 시 OTP race 방지
@@ -146,4 +246,5 @@ npm version major   # 0.1.0 → 1.0.0 (breaking)
 - `mds_lint_check(code)` — 사용자 코드의 mds rule 위반 자동 검출
 - `mds_skills_list` — AI fill 용 skill registry (ai-fill.md)
 - `mds_responsive_check(component, viewport)` — 컴포넌트의 responsive 동작 spec
-- `mds_examples_get(component)` — 컴포넌트 사용 예 (story args + apps/web 실 사용 모음)
+- `mds_examples_get(component)` — 컴포넌트 사용 예 (story args + apps/web 실
+  사용 모음)

package/dist/catalog.d.ts

@@ -0,0 +1,16 @@
+import type { Catalog, CatalogComponent, CompoundOverview } from './types.js';
+export declare function isDefaultListable(component: CatalogComponent): boolean;
+export declare function findComponent(catalog: Catalog, name: string): CatalogComponent | undefined;
+export declare function findExactComponent(catalog: Catalog, name: string): CatalogComponent | undefined;
+export declare function componentMatchesQuery(component: CatalogComponent, queryTokens: string[]): boolean;
+export declare function scoreComponent(component: CatalogComponent, query: string): number;
+export declare function summarizeComponent(component: CatalogComponent, includeDescription: boolean): Record<string, unknown>;
+export declare function componentNamespace(componentName: string): string;
+export declare function compoundNamespaces(catalog: Catalog): string[];
+export declare function collectCompoundParts(catalog: Catalog, namespace: string): CatalogComponent[];
+export declare function findCompoundNamespace(catalog: Catalog, name: string): string | undefined;
+export declare function buildCompoundOverview(catalog: Catalog, namespace: string): CompoundOverview;
+export declare function buildComponentContract(catalog: Catalog, component: CatalogComponent): Record<string, unknown>;
+export declare function componentSuggestions(catalog: Catalog, name: string): string[];
+export declare function summarizeSearchMatch(component: CatalogComponent, queryTokens: string[]): Record<string, unknown>;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,OAAO,EACP,gBAAgB,EAIhB,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAEpB,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAQtE;AAgBD,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAK1F;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAU/F;AA0BD,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAIjG;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAcjF;AAED,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,gBAAgB,EAC3B,kBAAkB,EAAE,OAAO,GAC1B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAYzB;AAED,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,EAAE,CAM7D;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,gBAAgB,EAAE,CA8B5F;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAMxF;AAuMD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,gBAAgB,CAgC3F;AAED,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,gBAAgB,GAC1B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUzB;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAY7E;AA6BD,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,gBAAgB,EAC3B,WAAW,EAAE,MAAM,EAAE,GACpB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAsBzB"}

package/dist/catalog.js

@@ -0,0 +1,383 @@
+import { loadPlaybooks, loadRecipes } from './loaders.js';
+import { normalizeText, uniqueStrings } from './text.js';
+export function isDefaultListable(component) {
+    const kind = component.kind ?? 'component';
+    const status = component.status ?? 'implemented';
+    return (component.public !== false &&
+        status !== 'internal' &&
+        (kind === 'component' || kind === 'compoundPart'));
+}
+function buildComponentLookup(catalog) {
+    const lookup = new Map();
+    for (const component of Object.values(catalog.components)) {
+        const names = [component.name, component.displayName, ...(component.aliases ?? [])].filter((item) => Boolean(item));
+        for (const candidate of names) {
+            lookup.set(candidate.toLowerCase(), component);
+            lookup.set(normalizeText(candidate), component);
+        }
+    }
+    return lookup;
+}
+export function findComponent(catalog, name) {
+    const lookup = buildComponentLookup(catalog);
+    return (catalog.components[name] ?? lookup.get(name.toLowerCase()) ?? lookup.get(normalizeText(name)));
+}
+export function findExactComponent(catalog, name) {
+    const normalizedName = normalizeText(name);
+    return (catalog.components[name] ??
+        Object.values(catalog.components).find((component) => component.name.toLowerCase() === name.toLowerCase() ||
+            normalizeText(component.name) === normalizedName));
+}
+function componentSearchHaystack(component) {
+    const parts = [
+        component.name,
+        component.displayName,
+        ...(component.aliases ?? []),
+        component.layer,
+        component.category,
+        component.description,
+        component.import?.statement,
+        ...component.props.flatMap((prop) => [
+            prop.name,
+            prop.description,
+            prop.type,
+            prop.rawType,
+            prop.typeRef,
+            ...(prop.values ?? []).map(String),
+        ]),
+        ...(component.stories ?? []),
+        ...(component.storybook ?? []).flatMap((story) => [story.name, story.title, story.id]),
+        ...Object.keys(component.types ?? {}),
+    ];
+    return normalizeText(parts.filter((item) => Boolean(item)).join(' '));
+}
+export function componentMatchesQuery(component, queryTokens) {
+    if (queryTokens.length === 0)
+        return true;
+    const haystack = componentSearchHaystack(component);
+    return queryTokens.every((token) => haystack.includes(token));
+}
+export function scoreComponent(component, query) {
+    const normalizedQuery = normalizeText(query);
+    const normalizedName = normalizeText(component.name);
+    if (normalizedName === normalizedQuery)
+        return 1000;
+    if (normalizedName.includes(normalizedQuery))
+        return 800;
+    if (normalizedQuery.startsWith(normalizedName))
+        return 700;
+    if ((component.aliases ?? []).some((alias) => normalizeText(alias) === normalizedQuery)) {
+        return 750;
+    }
+    if ((component.aliases ?? []).some((alias) => normalizeText(alias).includes(normalizedQuery))) {
+        return 650;
+    }
+    if (component.props.some((prop) => normalizeText(prop.name) === normalizedQuery))
+        return 550;
+    return 100;
+}
+export function summarizeComponent(component, includeDescription) {
+    return {
+        name: component.name,
+        kind: component.kind ?? 'component',
+        status: component.status ?? 'implemented',
+        layer: component.layer,
+        category: component.category,
+        import: component.import?.statement,
+        hasStories: component.hasStories,
+        storyCount: component.storybook?.length ?? component.stories?.length ?? 0,
+        ...(includeDescription ? { description: component.description } : {}),
+    };
+}
+export function componentNamespace(componentName) {
+    return componentName.split('.')[0] ?? componentName;
+}
+export function compoundNamespaces(catalog) {
+    return uniqueStrings(Object.values(catalog.components)
+        .filter((component) => component.name.includes('.'))
+        .map((component) => componentNamespace(component.name)));
+}
+export function collectCompoundParts(catalog, namespace) {
+    const prefix = `${namespace}.`;
+    return Object.values(catalog.components)
+        .filter((component) => component.name.startsWith(prefix))
+        .filter(isDefaultListable)
+        .sort((a, b) => {
+        const order = [
+            'Root',
+            'Trigger',
+            'Content',
+            'Header',
+            'Title',
+            'Description',
+            'Body',
+            'Footer',
+            'Close',
+            'RawClose',
+        ];
+        const aPart = a.name.slice(prefix.length);
+        const bPart = b.name.slice(prefix.length);
+        const aIndex = order.indexOf(aPart);
+        const bIndex = order.indexOf(bPart);
+        if (aIndex !== -1 || bIndex !== -1) {
+            return ((aIndex === -1 ? Number.MAX_SAFE_INTEGER : aIndex) -
+                (bIndex === -1 ? Number.MAX_SAFE_INTEGER : bIndex));
+        }
+        return a.name.localeCompare(b.name);
+    });
+}
+export function findCompoundNamespace(catalog, name) {
+    const normalizedName = normalizeText(name);
+    return compoundNamespaces(catalog).find((namespace) => namespace.toLowerCase() === name.toLowerCase() || normalizeText(namespace) === normalizedName);
+}
+function inferRelatedPlaybooks(name, layer) {
+    const normalizedName = normalizeText(name);
+    const playbooks = new Set();
+    if (layer === 'data' ||
+        normalizedName.includes('data grid') ||
+        normalizedName.includes('table')) {
+        playbooks.add('data-grid');
+        playbooks.add('async-states');
+    }
+    if (layer === 'overlays' ||
+        /(modal|drawer|sheet|dialog|popover|tooltip|hover card)/.test(normalizedName)) {
+        playbooks.add('overlay');
+    }
+    if (/(field|text field|textarea|select|checkbox|switch|radio|date picker|time picker|file upload|number input)/.test(normalizedName)) {
+        playbooks.add('form');
+    }
+    if (/(toast|notification|banner|empty state|error state|loading state|skeleton)/.test(normalizedName)) {
+        playbooks.add('feedback');
+        playbooks.add('async-states');
+    }
+    if (/(page|page header|section|anchor nav|app shell|sidebar|topbar)/.test(normalizedName)) {
+        playbooks.add('page-layout');
+    }
+    if (/(responsive|grid|stack|container)/.test(normalizedName)) {
+        playbooks.add('responsive-tokens');
+    }
+    return Array.from(playbooks).sort();
+}
+function inferRelatedRecipes(name) {
+    const normalizedName = normalizeText(name);
+    const recipes = new Set();
+    if (/(data grid|table|pagination|menu|pill)/.test(normalizedName))
+        recipes.add('admin-list-page');
+    if (/(modal|field|text field|select|banner)/.test(normalizedName))
+        recipes.add('modal-form');
+    if (/(drawer|description list|timeline)/.test(normalizedName))
+        recipes.add('detail-drawer');
+    if (/(page|page header|section|toolbar|textarea|switch|checkbox)/.test(normalizedName)) {
+        recipes.add('settings-form-page');
+    }
+    if (/(stat card|delta|chart|data list)/.test(normalizedName))
+        recipes.add('dashboard-overview');
+    if (/(loading state|skeleton|empty state|error state|banner)/.test(normalizedName)) {
+        recipes.add('async-state-section');
+    }
+    return Array.from(recipes).sort();
+}
+function availablePlaybooks(ids) {
+    try {
+        const available = new Set(Object.keys(loadPlaybooks()));
+        return ids.filter((id) => available.has(id));
+    }
+    catch {
+        return [];
+    }
+}
+function availableRecipes(ids) {
+    try {
+        const available = new Set(Object.keys(loadRecipes()));
+        return ids.filter((id) => available.has(id));
+    }
+    catch {
+        return [];
+    }
+}
+function buildFollowUpTools(name, relatedPlaybooks, relatedRecipes) {
+    return [
+        ...relatedRecipes.slice(0, 2).map((id) => ({
+            tool: 'mds_recipes_get',
+            args: { id },
+            reason: `Confirm the MDS-only composition pattern related to ${name}.`,
+        })),
+        ...relatedPlaybooks.slice(0, 3).map((area) => ({
+            tool: 'mds_playbook_get',
+            args: { area },
+            reason: `Confirm the decision rules and anti-patterns for ${name}.`,
+        })),
+        {
+            tool: 'mds_component_examples_get',
+            args: { name },
+            reason: 'Open Storybook stories/source as the visual and usage oracle before codegen.',
+        },
+    ];
+}
+function buildComponentAgentGuide(component) {
+    const relatedPlaybooks = availablePlaybooks(inferRelatedPlaybooks(component.name, component.layer));
+    const relatedRecipes = availableRecipes(inferRelatedRecipes(component.name));
+    return {
+        intent: `Use ${component.name} from MDS; do not recreate its UI locally.`,
+        importStatement: component.import?.statement,
+        requiredProps: component.props
+            .filter((prop) => prop.required)
+            .map((prop) => ({
+            name: prop.name,
+            type: prop.rawType ?? prop.type,
+            description: prop.description,
+        })),
+        relatedPlaybooks,
+        relatedRecipes,
+        followUpTools: buildFollowUpTools(component.name, relatedPlaybooks, relatedRecipes),
+        checklist: [
+            'Use the returned import statement; prefer the public @makitt/mds entrypoint unless a subpath is explicitly better.',
+            'Use only documented props and literal values from props[].values.',
+            'Check Storybook iframe/source before final UI code when the component affects layout or interaction.',
+            'Keep app routing, data fetching, permissions, persistence, and platform rules outside this MDS contract.',
+            'Verify generated UI in desktop and mobile viewports.',
+        ],
+        pitfalls: [
+            'Do not invent local cards, fields, tables, dialogs, sidebars, or visual CSS when an MDS component exists.',
+            'Do not use playbook TBD/planned notes as implemented API unless mds_components_get confirms the prop/component.',
+            'Do not hardcode visual values; add or use MDS tokens/components.',
+        ],
+    };
+}
+function requiredCompoundParts(namespace, parts) {
+    return [`${namespace}.Root`, `${namespace}.Content`].filter((partName) => parts.some((part) => part.name === partName));
+}
+function commonCompoundComposition(namespace, parts) {
+    const commonPartNames = [
+        'Root',
+        'Trigger',
+        'Content',
+        'Header',
+        'Title',
+        'Description',
+        'Body',
+        'Footer',
+        'Close',
+    ].map((part) => `${namespace}.${part}`);
+    return parts.map((part) => part.name).filter((partName) => commonPartNames.includes(partName));
+}
+function buildCompoundAgentGuide({ namespace, representative, requiredParts, relatedPlaybooks, relatedRecipes, }) {
+    return {
+        intent: `Use the ${namespace} compound parts together; do not use a one-off local overlay/composition.`,
+        importStatement: representative.import?.statement,
+        requiredProps: [],
+        relatedPlaybooks,
+        relatedRecipes,
+        followUpTools: [
+            ...buildFollowUpTools(namespace, relatedPlaybooks, relatedRecipes),
+            ...requiredParts.map((partName) => ({
+                tool: 'mds_components_get',
+                args: { name: partName },
+                reason: `Confirm exact props for ${partName}.`,
+            })),
+        ],
+        checklist: [
+            `Import the compound namespace with: ${representative.import?.statement ?? `import { ${namespace} } from '@makitt/mds';`}`,
+            'Query each part you render when it accepts props.',
+            'Use the related playbook before choosing modal/drawer/sheet/page placement.',
+            'Keep platform behavior outside this MDS-only composition contract.',
+        ],
+        pitfalls: [
+            `Do not query only "${namespace}" and then fabricate part props; call mds_components_get for concrete parts.`,
+            'Do not nest overlays by default; check overlay/form playbooks first.',
+        ],
+    };
+}
+export function buildCompoundOverview(catalog, namespace) {
+    const parts = collectCompoundParts(catalog, namespace);
+    const representative = parts.find((part) => part.name === `${namespace}.Root`) ??
+        parts.find((part) => part.name === `${namespace}.Content`) ??
+        parts[0];
+    if (!representative)
+        throw new Error(`Compound namespace "${namespace}" has no public parts.`);
+    const relatedPlaybooks = availablePlaybooks(inferRelatedPlaybooks(namespace, representative.layer));
+    const relatedRecipes = availableRecipes(inferRelatedRecipes(namespace));
+    const requiredParts = requiredCompoundParts(namespace, parts);
+    return {
+        name: namespace,
+        kind: 'compound',
+        status: 'implemented',
+        layer: representative.layer,
+        import: representative.import,
+        description: `${namespace} is an MDS compound namespace. Query individual parts for exact props before writing code.`,
+        parts: parts.map((part) => summarizeComponent(part, true)),
+        requiredParts,
+        commonComposition: commonCompoundComposition(namespace, parts),
+        agentGuide: buildCompoundAgentGuide({
+            namespace,
+            representative,
+            requiredParts,
+            relatedPlaybooks,
+            relatedRecipes,
+        }),
+    };
+}
+export function buildComponentContract(catalog, component) {
+    return {
+        ...component,
+        agentGuide: buildComponentAgentGuide(component),
+        catalogMeta: {
+            package: catalog.package,
+            version: catalog.version,
+            generated: catalog.generated,
+        },
+    };
+}
+export function componentSuggestions(catalog, name) {
+    const queryTokens = normalizeText(name).split(' ').filter(Boolean);
+    const componentSuggestions = Object.values(catalog.components)
+        .filter((component) => componentMatchesQuery(component, queryTokens))
+        .sort((a, b) => scoreComponent(b, name) - scoreComponent(a, name))
+        .slice(0, 5)
+        .map((component) => component.name);
+    const namespaceSuggestions = compoundNamespaces(catalog).filter((namespace) => normalizeText(namespace).includes(normalizeText(name)));
+    return uniqueStrings([...namespaceSuggestions, ...componentSuggestions]).slice(0, 5);
+}
+function propMatchesQuery(component, prop, queryTokens) {
+    const aliases = [
+        prop.type,
+        prop.rawType,
+        prop.typeRef,
+        ...(prop.values ?? []).map(String),
+    ].filter((item) => Boolean(item));
+    return componentMatchesQuery({
+        ...component,
+        name: prop.name,
+        displayName: prop.name,
+        aliases,
+        description: prop.description,
+        props: [],
+        stories: [],
+        hasTests: false,
+        hasStories: false,
+    }, queryTokens);
+}
+export function summarizeSearchMatch(component, queryTokens) {
+    return {
+        name: component.name,
+        kind: component.kind ?? 'component',
+        status: component.status ?? 'implemented',
+        layer: component.layer,
+        import: component.import?.statement,
+        description: component.description?.slice(0, 200),
+        matchedProps: component.props
+            .filter((prop) => propMatchesQuery(component, prop, queryTokens))
+            .slice(0, 3)
+            .map((prop) => ({
+            name: prop.name,
+            type: prop.rawType ?? prop.type,
+            values: prop.values,
+        })),
+        stories: component.storybook?.slice(0, 3).map((story) => ({
+            name: story.name,
+            id: story.id,
+            url: story.storyUrl,
+        })),
+    };
+}
+//# sourceMappingURL=catalog.js.map