sh-ui-cli 0.21.2 → 0.22.0

package/README.md

@@ -51,6 +51,79 @@ npx sh-ui list
 npx sh-ui remove button
 ```
 
+### mcp — AI 에게 sh-ui 를 알려주기 (v0.21.0+)
+
+`sh-ui mcp` 는 [Model Context Protocol](https://modelcontextprotocol.io) 서버를 stdio 로 시작한다. IDE-내 AI(Claude Code, Cursor, Windsurf 등) 가 sh-ui 컴포넌트를 자동으로 검색·설치할 수 있게 7개 툴을 노출한다.
+
+**한 번만 등록하면 끝** — 빈 폴더에서도 _"다크 모던 sh-ui 로 세팅하고 button 추가해줘"_ 만 말하면 AI 가 알아서 처리.
+
+#### 자동 등록 (권장, v0.22.0+)
+
+```bash
+# 프로젝트 루트에서 — IDE 별로 한 줄
+npx sh-ui mcp init --client claude-code      # → .mcp.json
+npx sh-ui mcp init --client cursor           # → .cursor/mcp.json
+npx sh-ui mcp init --client claude-desktop   # → 사용자 전역 (재시작 필요)
+
+# 사용자 전역 설정에 등록하려면
+npx sh-ui mcp init --client claude-code --scope user
+```
+
+기존 설정 파일이 있으면 다른 MCP 서버 엔트리를 보존하며 `sh-ui` 만 머지·갱신.
+
+#### 수동 등록
+
+**Claude Code** — `~/.claude/mcp.json` 또는 프로젝트 `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "sh-ui": {
+      "command": "npx",
+      "args": ["-y", "sh-ui-cli", "mcp"]
+    }
+  }
+}
+```
+
+**Cursor** — `~/.cursor/mcp.json` 또는 `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "sh-ui": {
+      "command": "npx",
+      "args": ["-y", "sh-ui-cli", "mcp"]
+    }
+  }
+}
+```
+
+**Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
+
+```json
+{
+  "mcpServers": {
+    "sh-ui": {
+      "command": "npx",
+      "args": ["-y", "sh-ui-cli", "mcp"]
+    }
+  }
+}
+```
+
+#### 노출되는 툴
+
+| 툴 | 설명 |
+|---|---|
+| `sh_ui_describe_init` | platform/base/radius/mode 선택지 + 한글 설명 — 자연어 의도("다크 모던") → enum 매핑용 |
+| `sh_ui_init` | `sh-ui.config.json` 생성 (비대화형) |
+| `sh_ui_list_components` | 플랫폼별 전체 컴포넌트 + 요약 + deps |
+| `sh_ui_get_component` | 단일 컴포넌트 메타·소스파일·deps |
+| `sh_ui_add_component` | 컴포넌트 설치 (외부 패키지 자동 설치) |
+| `sh_ui_remove_component` | 삭제 (수정 파일 보호) |
+| `sh_ui_get_changelog` | 변경 내역 조회 |
+
 ## 지원 플랫폼
 
 - **React (Next.js)** — `src/shared/ui/` 또는 `sh-ui.config.json` 에 지정된 경로로 복사

package/bin/sh-ui.mjs

@@ -14,6 +14,8 @@ const usage = `사용법:
   sh-ui list                       현재 설치된 컴포넌트 목록 표시
   sh-ui remove <component...>      설치된 컴포넌트 파일 삭제
   sh-ui mcp                        MCP 서버(stdio) 시작 — IDE-내 AI용
+  sh-ui mcp init --client <name>   IDE MCP 설정 파일에 sh-ui 엔트리 자동 추가
+                                   (claude-code | cursor | claude-desktop)
   옵션:
     --skip-install                 (add) 외부 패키지 자동 설치 생략
     --diff                         (add) 파일을 쓰지 않고 변경 내역만 출력
@@ -45,8 +47,15 @@ try {
       break;
     }
     case "mcp": {
-      const { startMcpServer } = await import("../src/mcp.mjs");
-      await startMcpServer();
+      // `sh-ui mcp init ...` → 설정 파일에 엔트리 추가
+      // `sh-ui mcp`         → MCP 서버 시작
+      if (rest[0] === "init") {
+        const { mcpInit } = await import("../src/mcp-init.mjs");
+        await mcpInit({ cwd: process.cwd(), args: rest.slice(1) });
+      } else {
+        const { startMcpServer } = await import("../src/mcp.mjs");
+        await startMcpServer();
+      }
       break;
     }
     case "remove":

package/data/changelog/versions.json

@@ -2,6 +2,19 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$description": "sh-ui 릴리즈 노트 단일 소스. docs(React)와 showcase(Flutter)가 함께 읽는다. 새 릴리즈마다 맨 앞에 추가.",
   "versions": [
+    {
+      "version": "0.22.0",
+      "date": "2026-04-27",
+      "title": "sh-ui mcp init — IDE MCP 설정 자동 등록",
+      "type": "minor",
+      "highlights": [
+        "sh-ui mcp init --client <claude-code|cursor|claude-desktop> 추가 — IDE 별 MCP 설정 파일을 자동으로 찾아 sh-ui 엔트리 머지",
+        "스코프 분기 — 기본 project(.mcp.json / .cursor/mcp.json), --scope user 로 전역(~/.claude/mcp.json 등) 선택 가능. claude-desktop 은 user 전용(OS 별 경로 자동 분기)",
+        "기존 JSON 보존 — 다른 MCP 서버 엔트리·기타 키를 건드리지 않고 sh-ui 만 머지·갱신",
+        "수동 JSON 편집 없이 npx sh-ui mcp init --client cursor 한 줄로 끝"
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.22.0"
+    },
     {
       "version": "0.21.2",
       "date": "2026-04-27",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sh-ui-cli",
-  "version": "0.21.2",
+  "version": "0.22.0",
   "description": "sh-ui CLI — 디자인 시스템 컴포넌트를 프로젝트로 복사하는 CLI (sh-ui init / add / list / remove)",
   "license": "MIT",
   "repository": {

package/src/mcp-init.mjs

@@ -0,0 +1,141 @@
+// sh-ui mcp init — 타깃 IDE 의 MCP 설정 파일에 sh-ui 엔트리를 자동 추가.
+//
+// 지원 클라이언트:
+//   claude-code     — project: <cwd>/.mcp.json,           user: ~/.claude/mcp.json
+//   cursor          — project: <cwd>/.cursor/mcp.json,    user: ~/.cursor/mcp.json
+//   claude-desktop  — user 만 (OS 별 경로 자동 분기)
+//
+// 동작: 기존 JSON 의 mcpServers.sh-ui 를 머지(있으면 덮어쓰기), 디렉토리 자동 생성.
+
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, resolve, relative } from "node:path";
+import { homedir, platform as osPlatform } from "node:os";
+
+const CLIENTS = ["claude-code", "cursor", "claude-desktop"];
+
+const SH_UI_ENTRY = {
+  command: "npx",
+  args: ["-y", "sh-ui-cli", "mcp"],
+};
+
+/** 클라이언트·스코프별 설정 파일 절대 경로. */
+function resolveConfigPath(client, scope, cwd) {
+  const home = homedir();
+  if (client === "claude-code") {
+    return scope === "user"
+      ? resolve(home, ".claude", "mcp.json")
+      : resolve(cwd, ".mcp.json");
+  }
+  if (client === "cursor") {
+    return scope === "user"
+      ? resolve(home, ".cursor", "mcp.json")
+      : resolve(cwd, ".cursor", "mcp.json");
+  }
+  if (client === "claude-desktop") {
+    if (scope !== "user") {
+      throw new Error(
+        "claude-desktop 은 user 스코프만 지원합니다. --scope user 또는 --scope 생략.",
+      );
+    }
+    const os = osPlatform();
+    if (os === "darwin") {
+      return resolve(
+        home,
+        "Library",
+        "Application Support",
+        "Claude",
+        "claude_desktop_config.json",
+      );
+    }
+    if (os === "win32") {
+      const appData = process.env.APPDATA ?? resolve(home, "AppData", "Roaming");
+      return resolve(appData, "Claude", "claude_desktop_config.json");
+    }
+    // linux + 기타
+    return resolve(home, ".config", "Claude", "claude_desktop_config.json");
+  }
+  throw new Error(`알 수 없는 클라이언트: ${client}. 허용: ${CLIENTS.join(", ")}`);
+}
+
+/** 클라이언트별 기본 스코프. claude-desktop 은 user 강제. */
+function defaultScope(client) {
+  return client === "claude-desktop" ? "user" : "project";
+}
+
+/** JSON 읽기 (없으면 빈 객체). 깨진 JSON 은 명시적 에러. */
+async function readJsonOrEmpty(path) {
+  if (!existsSync(path)) return {};
+  let raw;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (err) {
+    throw new Error(`설정 파일 읽기 실패: ${path}\n  ${err.message}`);
+  }
+  if (raw.trim() === "") return {};
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `기존 ${path} 가 유효한 JSON 이 아닙니다. 수동으로 고치고 다시 시도하세요.\n  ${err.message}`,
+    );
+  }
+}
+
+export async function mcpInit({ cwd, args }) {
+  const flags = parseFlags(args);
+  const client = flags.client;
+  if (!client) {
+    throw new Error(
+      `--client 가 필요합니다. 허용: ${CLIENTS.join(", ")}\n` +
+        `예: sh-ui mcp init --client claude-code`,
+    );
+  }
+  if (!CLIENTS.includes(client)) {
+    throw new Error(
+      `알 수 없는 클라이언트: '${client}'. 허용: ${CLIENTS.join(", ")}`,
+    );
+  }
+
+  const scope = flags.scope ?? defaultScope(client);
+  if (!["user", "project"].includes(scope)) {
+    throw new Error(`--scope 는 'user' 또는 'project' 여야 합니다.`);
+  }
+
+  const configPath = resolveConfigPath(client, scope, cwd);
+  const config = await readJsonOrEmpty(configPath);
+
+  if (!config.mcpServers || typeof config.mcpServers !== "object") {
+    config.mcpServers = {};
+  }
+
+  const before = config.mcpServers["sh-ui"];
+  config.mcpServers["sh-ui"] = SH_UI_ENTRY;
+
+  await mkdir(dirname(configPath), { recursive: true });
+  await writeFile(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+
+  const rel = relative(cwd, configPath);
+  const display = rel.startsWith("..") ? configPath : rel;
+  const verb = before ? "갱신" : "추가";
+  console.log(`✓ sh-ui MCP 엔트리 ${verb} → ${display}`);
+  console.log(`  client: ${client} (scope: ${scope})`);
+  if (client === "claude-code" || client === "cursor") {
+    console.log(`\n다음 단계: ${client === "claude-code" ? "Claude Code" : "Cursor"} 를 재시작하면 sh-ui 툴이 활성화됩니다.`);
+  } else {
+    console.log(`\n다음 단계: Claude Desktop 을 종료 후 재시작하면 sh-ui 툴이 활성화됩니다.`);
+  }
+}
+
+/** --key=value / --key value 파싱 */
+function parseFlags(args) {
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (!a.startsWith("--")) continue;
+    const eq = a.indexOf("=");
+    if (eq > -1) flags[a.slice(2, eq)] = a.slice(eq + 1);
+    else flags[a.slice(2)] = args[++i];
+  }
+  return flags;
+}

package/src/mcp.mjs

@@ -102,7 +102,7 @@ function resolveCwd(input) {
 
 export async function startMcpServer() {
   const server = new McpServer(
-    { name: "sh-ui", version: "0.21.2" },
+    { name: "sh-ui", version: "0.22.0" },
     { capabilities: { tools: {} } },
   );