@makitt.io/mds-mcp-server 0.1.2 → 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
 
@@ -93,57 +159,92 @@ stdio (Claude Code / Cursor 표준).
 
 ## Publish (maintainer 용)
 
-npm registry (`registry.npmjs.org`) 의 `@makitt.io/mds-mcp-server` 의 publish.
+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)
    - **Packages and scopes**:
      - "Only select packages and scopes" → **`@makitt.io`** scope 추가
      - Permissions: **Read and write**
-   - **Bypass 2FA**: ✓ enable (publish 의 OTP 안 필요)
-   - Generate token → 값 복사 (한 번 만 표시)
-2. **token 의 공용 vault share** — 1Password / LastPass / Bitwarden 등 의 team 의 공유 entry. 채팅 / 코드 에 직접 X
-3. **각 maintainer 의 local setup** — `~/.npmrc` 의 직접 entry (또는 `npm config set`):
+   - **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`):
    ```bash
    npm config set //registry.npmjs.org/:_authToken=<token>
    ```
-   → `~/.npmrc` 의 추가. git ignore 됨 (사용자 home dir).
+   → `~/.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 의 안
+- ❌ "Read and write" 모든 scope 허용 — `@makitt.io` specific scope 만 허용
+- ✓ Bypass 2FA enable — 공용 계정 publish 시 OTP race 방지
 
 ## 향후 (Step 6 follow-up)
 
 - `mds_lint_check(code)` — 사용자 코드의 mds rule 위반 자동 검출
-- `mds_skills_list` — AI fill 의 skill registry (ai-fill.md)
+- `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"}