@makitt.io/mds-mcp-server 0.1.0

package/README.md

@@ -0,0 +1,149 @@
+# @makitt.io/mds-mcp-server
+
+MCP (Model Context Protocol) server for `@makitt/mds`. AI 가 mds 의 catalog +
+playbook 을 자동 query — fabrication 0 의 최종 layer.
+
+> **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
+- **결정 표 검색** — "modal-form vs page-form 어떻게 선택?" → playbook 안 lookup
+- **안티패턴 자동 검출** — 작성 코드의 mds rule 위반 식별
+
+## 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 |
+
+## 설치
+
+### A. NPM (외부 사용자 — 가장 단순)
+
+```bash
+claude mcp add mds -- npx -y @makitt.io/mds-mcp-server@latest
+```
+
+→ npmjs.org 에서 자동 fetch + 실행. self-contained (embedded catalog + playbook). 별도 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
+claude mcp add mds -- node /absolute/path/.../mds-mcp-server/dist/index.js
+```
+
+### C. Customize (자체 catalog/playbook)
+
+```bash
+claude mcp add mds \
+  -e MDS_CATALOG_PATH=/path/to/your/catalog.json \
+  -e MDS_PLAYBOOK_DIR=/path/to/your/playbook \
+  -- npx -y @makitt.io/mds-mcp-server@latest
+```
+
+→ 본인 design system 위에 mds 패턴 사용.
+
+### 검증
+
+```bash
+claude mcp list           # mds 등록 확인
+claude mcp get mds        # 상세
+```
+
+Claude Code 재시작 후 자동 사용:
+
+```
+사용자: 새 상품 등록 페이지 만들어줘
+AI: (mds_playbook_get 'form' 자동 호출 → 결정 표 lookup)
+    상품 등록은 6+ section 의 큰 form → Section + AnchorNav 사용.
+    (mds_components_get 'AnchorNav' → props spec lookup)
+```
+
+## Path resolution 우선순위
+
+1. **env var** (`MDS_CATALOG_PATH` / `MDS_PLAYBOOK_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
+```
+
+- `tsc` — TypeScript compile (`dist/index.js`)
+- `copy-data.mjs` — `../mds/dist/catalog.json` + `../mds/docs/playbook/` 을 `dist/data/` 로 복사
+
+→ self-contained package. `files: ["dist", "README.md"]` 가 npm publish 의 포함.
+
+## Transport
+
+stdio (Claude Code / Cursor 표준).
+
+## Publish (maintainer 용)
+
+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 자동.
+
+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`):
+   ```bash
+   npm config set //registry.npmjs.org/:_authToken=<token>
+   ```
+   → `~/.npmrc` 의 추가. git ignore 됨 (사용자 home dir).
+
+### Publish 흐름
+
+```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 의 자동)
+```
+
+### Version bump
+
+```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)
+```
+
+→ `package.json` 자동 bump + git tag 자동 생성. push 시 `git push --follow-tags`.
+
+### 보안
+
+- ❌ 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 의 안
+
+## 향후 (Step 6 follow-up)
+
+- `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 의 실 사용 모음)