@makitt.io/mds-mcp-server

MCP (Model Context Protocol) server for @makitt/mds. AI 가 mds 의 catalog + playbook + recipe 를 자동 query — fabrication 0 보장의 최종 layer.

Registry: npmjs.org (표준 public npm registry). .npmrc 별도 setup 없이 install 가능.

무엇을 하는가

Claude Code / Cursor 같은 AI 도구가 다음을 자동 query:

• 컴포넌트 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
• 안티패턴 조회/가드레일 — playbook 기반으로 사용 전 금지 패턴 확인

Tools

| 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 을 확인한다.

설치

A. NPM (외부 사용자 — 가장 단순)

claude mcp add mds -- npx -y @makitt.io/mds-mcp-server@latest

→ npmjs.org 에서 자동 fetch + 실행. self-contained (embedded catalog + playbook + recipe). 별도 auth / scope mapping 없음.

B. Local build (mds 개발자 monorepo)

cd packages/mds && pnpm build       # catalog.json 생성
cd ../mds-mcp-server && pnpm build  # tsc + data verify + dogfood/evals + stdio/pack smoke
claude mcp add mds -- node /absolute/path/.../mds-mcp-server/dist/index.js

C. Customize (자체 catalog/playbook)

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

→ 본인 design system 위에 mds 패턴 사용.

검증

claude mcp list           # mds 등록 확인
claude mcp get mds        # 상세

Published package smoke:

cd packages/mds-mcp-server
pnpm smoke:published

smoke:published 는 현재 package.json 버전의 @makitt.io/mds-mcp-server 를 npm registry 에서 받아 stdio MCP handshake, tool list, component lookup, embedded playbook 응답을 검증한다. 다른 버전을 확인할 때는 spec 을 override 한다.

[email protected]/mds-mcp-server@latest pnpm smoke:published

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 / MDS_RECIPE_DIR) — 외부 customize
2. embedded data (dist/data/) — published package 의 self-contained
3. monorepo relative (../../mds/) — dev fallback

Build (data 자동 embed)

pnpm build  # tsc + copy:data + verify:data + dogfood/evals + stdio/pack smoke

• tsc — TypeScript compile (dist/index.js)
• 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 시나리오 검증
• eval-tools.mjs — 고정 fixture 로 codegen recipe 선택, component search ranking, playbook search, invalid argument rejection 을 회귀 검증
• smoke-stdio.mjs — MCP SDK client 로 node dist/index.js 실제 stdio transport 호출 검증
• verify-pack.mjs — npm pack --dry-run payload 에 embedded data 포함, source/script 누출 없음 검증
• smoke-packed.mjs — publish 전 실제 npm pack tarball 을 임시 project 에 설치하고 .bin/mds-mcp-server 로 stdio MCP handshake/tool 호출 검증

→ self-contained package. files: ["dist", "README.md"] 가 npm publish 에 포함됨.

Release policy

pnpm verify:release

• verify-release.mjs — Changesets/publish policy, npm files contract, README publish guide 검증
• CI와 prepublishOnly에서 실행한다. 앱/로컬 빌드가 루트 .changeset 메타데이터에 묶이지 않도록 pnpm build에는 포함하지 않는다.

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//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 에 보관. 채팅 / 코드에 직접 노출 금지
3. 각 maintainer 의 local setup — ~/.npmrc 에 직접 entry 추가 (또는 npm config set):

   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

pnpm changeset

예:

---
'@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 에서:

pnpm version-packages  # changeset version: package.json + changelog 갱신
pnpm release           # packages build + changeset publish

로컬 검증은 publish 전 항상:

cd packages/mds-mcp-server
pnpm build             # data/release verify + dogfood + stdio smoke + pack verify

verify:pack 이 이미 npm pack --dry-run --json payload 를 검사하므로 별도 수동 npm publish --dry-run 은 보조 확인용이다.

보안

• ❌ 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 실 사용 모음)