palette-mcp 1.1.2 → 1.2.0

package/src/server.ts

@@ -1,6 +1,6 @@
 /**
  * Palette MCP Server - 공통 로직
- * 
+ *
  * Local(stdio) 모드와 Remote(Smithery) 모드에서 공유되는 핵심 기능을 정의합니다.
  */
 
@@ -8,44 +8,70 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
   Tool,
 } from '@modelcontextprotocol/sdk/types.js';
 import { readFile } from 'fs/promises';
 import { FigmaService } from './services/figma.js';
-import { DesignSystemService } from './services/design-system.js';
+import { DesignSystemService, type SyncConfig } from './services/design-system.js';
 import { CodeGenerator, type PreviewType } from './services/code-generator.js';
+import { validateAccess, type AuthResult } from './services/auth.js';
 
 // 서버 설정 타입
 export interface ServerConfig {
   figmaAccessToken?: string;
   githubToken?: string;
   figmaMcpServerUrl?: string;
+  /**
+   * Figma Desktop MCP 클라이언트 사용 여부
+   * Remote 모드(Smithery)에서는 false로 설정해야 함 (로컬호스트 접근 불가)
+   */
+  useFigmaMcp?: boolean;
+  /**
+   * 디자인 시스템 컴포넌트 동기화 설정
+   */
+  syncConfig?: SyncConfig;
+  /**
+   * 인증 건너뛰기 (로컬 개발용)
+   * true로 설정하면 GitHub 조직 멤버십 확인을 건너뜁니다.
+   */
+  skipAuth?: boolean;
 }
 
-// Tools 정의
+// Tools 정의 (annotations 포함)
 export const tools: Tool[] = [
   {
     name: 'convert_figma_to_react',
-    description: 'Figma 디자인을 디자인 시스템을 사용하여 React 컴포넌트로 변환합니다',
+    description: 'Figma 디자인을 @dealicious/design-system-react 컴포넌트를 사용하여 React 컴포넌트로 변환합니다. Figma 파일 URL과 컴포넌트 이름을 제공하면, 디자인 시스템 컴포넌트(Button, Text, Tag, Check, Chip 등)를 활용한 React TSX 코드를 생성합니다.',
+    annotations: {
+      title: 'Figma to React Converter',
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
     inputSchema: {
       type: 'object',
       properties: {
         figmaUrl: {
           type: 'string',
-          description: 'Figma 파일 URL 또는 파일 ID',
+          description: 'Figma 파일의 전체 URL (예: https://www.figma.com/file/ABC123/Design?node-id=1-2) 또는 파일 ID',
         },
         nodeId: {
           type: 'string',
-          description: '변환할 특정 노드 ID (선택사항)',
+          description: '변환할 특정 Figma 노드의 ID. URL에 node-id가 포함되어 있으면 생략 가능합니다.',
         },
         componentName: {
           type: 'string',
-          description: '생성할 컴포넌트 이름',
+          description: '생성될 React 컴포넌트의 이름 (예: ProductCard, LoginForm)',
         },
         previewType: {
           type: 'string',
           enum: ['html', 'image', 'both'],
-          description: '미리보기 타입: "html"은 HTML 파일, "image"는 PNG 이미지, "both"는 둘 다 (기본값: "both")',
+          description: '미리보기 생성 옵션: "html"은 브라우저에서 볼 수 있는 HTML 파일, "image"는 PNG 스크린샷, "both"는 둘 다 생성 (기본값: "both")',
           default: 'both',
         },
       },
@@ -54,26 +80,33 @@ export const tools: Tool[] = [
   },
   {
     name: 'convert_figma_to_vue',
-    description: 'Figma 디자인을 디자인 시스템을 사용하여 Vue 컴포넌트로 변환합니다',
+    description: 'Figma 디자인을 @dealicious/design-system Vue 컴포넌트를 사용하여 Vue 3 Single File Component로 변환합니다. Figma 파일 URL과 컴포넌트 이름을 제공하면, 디자인 시스템 컴포넌트를 활용한 Vue SFC 코드를 생성합니다.',
+    annotations: {
+      title: 'Figma to Vue Converter',
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
     inputSchema: {
       type: 'object',
       properties: {
         figmaUrl: {
           type: 'string',
-          description: 'Figma 파일 URL 또는 파일 ID',
+          description: 'Figma 파일의 전체 URL (예: https://www.figma.com/file/ABC123/Design?node-id=1-2) 또는 파일 ID',
         },
         nodeId: {
           type: 'string',
-          description: '변환할 특정 노드 ID (선택사항)',
+          description: '변환할 특정 Figma 노드의 ID. URL에 node-id가 포함되어 있으면 생략 가능합니다.',
         },
         componentName: {
           type: 'string',
-          description: '생성할 컴포넌트 이름',
+          description: '생성될 Vue 컴포넌트의 이름 (예: ProductCard, LoginForm)',
         },
         previewType: {
           type: 'string',
           enum: ['html', 'image', 'both'],
-          description: '미리보기 타입: "html"은 HTML 파일, "image"는 PNG 이미지, "both"는 둘 다 (기본값: "both")',
+          description: '미리보기 생성 옵션: "html"은 브라우저에서 볼 수 있는 HTML 파일, "image"는 PNG 스크린샷, "both"는 둘 다 생성 (기본값: "both")',
           default: 'both',
         },
       },
@@ -82,14 +115,21 @@ export const tools: Tool[] = [
   },
   {
     name: 'list_design_system_components',
-    description: '디자인 시스템에서 사용 가능한 컴포넌트 목록을 조회합니다',
+    description: '@dealicious/design-system에서 사용 가능한 모든 UI 컴포넌트 목록을 조회합니다. 각 컴포넌트의 이름, 설명, import 경로, 사용 가능한 props를 반환합니다.',
+    annotations: {
+      title: 'Design System Component List',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
     inputSchema: {
       type: 'object',
       properties: {
         framework: {
           type: 'string',
           enum: ['react', 'vue'],
-          description: '컴포넌트를 조회할 프레임워크',
+          description: '컴포넌트를 조회할 프레임워크: "react"는 design-system-react, "vue"는 design-system 패키지',
         },
       },
       required: ['framework'],
@@ -97,13 +137,20 @@ export const tools: Tool[] = [
   },
   {
     name: 'analyze_figma_file',
-    description: 'Figma 파일 구조와 사용 가능한 컴포넌트를 분석합니다',
+    description: 'Figma 파일의 구조를 분석하여 페이지, 프레임, 컴포넌트 계층을 파악합니다. 변환하기 전에 파일 구조를 이해하는 데 유용합니다.',
+    annotations: {
+      title: 'Figma File Analyzer',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
     inputSchema: {
       type: 'object',
       properties: {
         figmaUrl: {
           type: 'string',
-          description: 'Figma 파일 URL 또는 파일 ID',
+          description: '분석할 Figma 파일의 전체 URL 또는 파일 ID',
         },
       },
       required: ['figmaUrl'],
@@ -111,6 +158,58 @@ export const tools: Tool[] = [
   },
 ];
 
+// Prompts 정의
+const prompts = [
+  {
+    name: 'convert-design-to-component',
+    description: 'Figma 디자인을 React 또는 Vue 컴포넌트로 변환하는 가이드 프롬프트',
+    arguments: [
+      {
+        name: 'figmaUrl',
+        description: 'Figma 파일 URL',
+        required: true,
+      },
+      {
+        name: 'framework',
+        description: '프레임워크 선택 (react 또는 vue)',
+        required: true,
+      },
+      {
+        name: 'componentName',
+        description: '컴포넌트 이름',
+        required: true,
+      },
+    ],
+  },
+  {
+    name: 'explore-design-system',
+    description: '디자인 시스템 컴포넌트 탐색 가이드',
+    arguments: [
+      {
+        name: 'framework',
+        description: '프레임워크 선택 (react 또는 vue)',
+        required: false,
+      },
+    ],
+  },
+];
+
+// Resources 정의
+const resources = [
+  {
+    uri: 'palette://design-system/react/components',
+    name: 'React Design System Components',
+    description: '@dealicious/design-system-react에서 사용 가능한 컴포넌트 목록',
+    mimeType: 'application/json',
+  },
+  {
+    uri: 'palette://design-system/vue/components',
+    name: 'Vue Design System Components',
+    description: '@dealicious/design-system에서 사용 가능한 컴포넌트 목록',
+    mimeType: 'application/json',
+  },
+];
+
 /**
  * MCP 서버를 생성하고 핸들러를 등록합니다.
  * Local 모드와 Remote 모드에서 공통으로 사용됩니다.
@@ -127,27 +226,73 @@ export function createPaletteServer(config: ServerConfig = {}): Server {
     process.env.FIGMA_MCP_SERVER_URL = config.figmaMcpServerUrl;
   }
 
-  // MCP 서버 초기화
-  const server = new Server({
-    name: 'palette',
-    version: '1.0.0',
-  });
+  // MCP 서버 초기화 (모든 capabilities 활성화)
+  const server = new Server(
+    {
+      name: 'palette',
+      version: '1.0.0',
+    },
+    {
+      capabilities: {
+        tools: {},      // tools 기능 활성화
+        prompts: {},    // prompts 기능 활성화
+        resources: {},  // resources 기능 활성화
+      },
+    }
+  );
 
   // 서비스 초기화
-  const figmaService = new FigmaService();
-  const designSystemService = new DesignSystemService();
+  // Remote 모드에서는 Figma Desktop MCP 클라이언트를 사용하지 않음 (로컬호스트 접근 불가)
+  const useFigmaMcp = config.useFigmaMcp !== undefined ? config.useFigmaMcp : true;
+  const figmaService = new FigmaService(useFigmaMcp, config.figmaMcpServerUrl);
+  const designSystemService = new DesignSystemService(config.syncConfig);
   const codeGenerator = new CodeGenerator(designSystemService);
 
-  // 도구 목록 핸들러
+  // 인증 상태 캐시
+  let authResult: AuthResult | null = null;
+
+  /**
+   * 도구 실행 전 인증 확인
+   * skipAuth가 true이면 인증을 건너뜁니다.
+   */
+  async function ensureAuthenticated(): Promise<void> {
+    // 로컬 개발 모드에서는 인증 건너뛰기
+    if (config.skipAuth) {
+      console.error('[Palette Auth] ⚠️ 인증 건너뛰기 모드 (skipAuth=true)');
+      return;
+    }
+
+    // 이미 인증되었으면 건너뛰기
+    if (authResult?.authorized) {
+      return;
+    }
+
+    // 인증 수행
+    const githubToken = config.githubToken || process.env.GITHUB_TOKEN;
+    authResult = await validateAccess(githubToken);
+
+    if (!authResult.authorized) {
+      throw new Error(authResult.error || '인증에 실패했습니다.');
+    }
+  }
+
+  // 디자인 시스템 컴포넌트 비동기 초기화 (백그라운드에서 실행)
+  designSystemService.initialize().catch((error) => {
+    console.error('[Palette] 디자인 시스템 초기화 실패:', error);
+  });
+
+  // ===== Tools 핸들러 =====
   server.setRequestHandler(ListToolsRequestSchema, async () => {
     return { tools };
   });
 
-  // 도구 실행 핸들러
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
 
     try {
+      // 🔐 도구 실행 전 인증 확인
+      await ensureAuthenticated();
+
       switch (name) {
         case 'convert_figma_to_react': {
           const { figmaUrl, nodeId, componentName, previewType = 'both' } = args as {
@@ -297,5 +442,95 @@ export function createPaletteServer(config: ServerConfig = {}): Server {
     }
   });
 
+  // ===== Prompts 핸들러 =====
+  server.setRequestHandler(ListPromptsRequestSchema, async () => {
+    return { prompts };
+  });
+
+  server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+
+    switch (name) {
+      case 'convert-design-to-component': {
+        const figmaUrl = args?.figmaUrl || '<FIGMA_URL>';
+        const framework = args?.framework || 'react';
+        const componentName = args?.componentName || 'MyComponent';
+
+        return {
+          description: 'Figma 디자인을 컴포넌트로 변환하는 프롬프트',
+          messages: [
+            {
+              role: 'user',
+              content: {
+                type: 'text',
+                text: `Figma 디자인을 ${framework} 컴포넌트로 변환해주세요.\n\n- Figma URL: ${figmaUrl}\n- 컴포넌트 이름: ${componentName}\n\n디자인 시스템 컴포넌트를 최대한 활용해주세요.`,
+              },
+            },
+          ],
+        };
+      }
+
+      case 'explore-design-system': {
+        const framework = args?.framework || 'react';
+
+        return {
+          description: '디자인 시스템 탐색 프롬프트',
+          messages: [
+            {
+              role: 'user',
+              content: {
+                type: 'text',
+                text: `@dealicious/design-system${framework === 'react' ? '-react' : ''} 패키지에서 사용 가능한 컴포넌트 목록을 보여주세요. 각 컴포넌트의 사용법과 예제도 함께 알려주세요.`,
+              },
+            },
+          ],
+        };
+      }
+
+      default:
+        throw new Error(`Unknown prompt: ${name}`);
+    }
+  });
+
+  // ===== Resources 핸들러 =====
+  server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    return { resources };
+  });
+
+  server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const { uri } = request.params;
+
+    switch (uri) {
+      case 'palette://design-system/react/components': {
+        const components = await designSystemService.getAvailableComponents('react');
+        return {
+          contents: [
+            {
+              uri,
+              mimeType: 'application/json',
+              text: JSON.stringify(components, null, 2),
+            },
+          ],
+        };
+      }
+
+      case 'palette://design-system/vue/components': {
+        const components = await designSystemService.getAvailableComponents('vue');
+        return {
+          contents: [
+            {
+              uri,
+              mimeType: 'application/json',
+              text: JSON.stringify(components, null, 2),
+            },
+          ],
+        };
+      }
+
+      default:
+        throw new Error(`Unknown resource: ${uri}`);
+    }
+  });
+
   return server;
 }

package/src/services/auth.ts

@@ -0,0 +1,162 @@
+/**
+ * 인증 및 권한 검증 서비스
+ *
+ * dealicious-inc 조직 멤버십을 확인하여 서비스 접근을 제어합니다.
+ */
+
+import { Octokit } from '@octokit/rest';
+
+// 허용된 GitHub 조직 목록
+const ALLOWED_ORGANIZATIONS = ['dealicious-inc'];
+
+// 인증 상태 캐시 (토큰별로 검증 결과를 캐시)
+const authCache = new Map<string, { valid: boolean; username: string; checkedAt: Date }>();
+
+// 캐시 유효 시간 (1시간)
+const CACHE_TTL_MS = 60 * 60 * 1000;
+
+/**
+ * GitHub 토큰으로 사용자 정보 조회
+ */
+async function getAuthenticatedUser(octokit: Octokit): Promise<{ login: string; email: string | null }> {
+  const { data } = await octokit.users.getAuthenticated();
+  return { login: data.login, email: data.email };
+}
+
+/**
+ * 사용자가 허용된 조직의 멤버인지 확인
+ */
+async function checkOrganizationMembership(octokit: Octokit, org: string): Promise<boolean> {
+  try {
+    await octokit.orgs.getMembershipForAuthenticatedUser({ org });
+    return true;
+  } catch (error: any) {
+    // 404: 멤버가 아님, 403: 권한 없음
+    if (error.status === 404 || error.status === 403) {
+      return false;
+    }
+    throw error;
+  }
+}
+
+/**
+ * 캐시된 인증 결과 확인
+ */
+function getCachedAuth(githubToken: string): { valid: boolean; username: string } | null {
+  const cached = authCache.get(githubToken);
+  if (!cached) return null;
+
+  // 캐시 만료 확인
+  const now = new Date();
+  if (now.getTime() - cached.checkedAt.getTime() > CACHE_TTL_MS) {
+    authCache.delete(githubToken);
+    return null;
+  }
+
+  return { valid: cached.valid, username: cached.username };
+}
+
+/**
+ * 인증 결과 캐시 저장
+ */
+function setCachedAuth(githubToken: string, valid: boolean, username: string): void {
+  authCache.set(githubToken, { valid, username, checkedAt: new Date() });
+}
+
+export interface AuthResult {
+  authorized: boolean;
+  username?: string;
+  organization?: string;
+  error?: string;
+}
+
+/**
+ * GitHub 조직 멤버십을 확인하여 서비스 접근 권한을 검증합니다.
+ *
+ * @param githubToken GitHub Personal Access Token
+ * @returns 인증 결과
+ */
+export async function validateAccess(githubToken?: string): Promise<AuthResult> {
+  // GITHUB_TOKEN이 없으면 거부
+  if (!githubToken) {
+    return {
+      authorized: false,
+      error: 'GITHUB_TOKEN이 필요합니다. dealicious-inc 조직 멤버만 Palette MCP를 사용할 수 있습니다.',
+    };
+  }
+
+  // 캐시 확인
+  const cached = getCachedAuth(githubToken);
+  if (cached) {
+    if (cached.valid) {
+      return {
+        authorized: true,
+        username: cached.username,
+        organization: ALLOWED_ORGANIZATIONS[0],
+      };
+    } else {
+      return {
+        authorized: false,
+        username: cached.username,
+        error: `사용자 '${cached.username}'은(는) dealicious-inc 조직 멤버가 아닙니다.`,
+      };
+    }
+  }
+
+  // GitHub API로 검증
+  const octokit = new Octokit({ auth: githubToken });
+
+  try {
+    // 사용자 정보 조회
+    const user = await getAuthenticatedUser(octokit);
+
+    // 조직 멤버십 확인
+    for (const org of ALLOWED_ORGANIZATIONS) {
+      const isMember = await checkOrganizationMembership(octokit, org);
+
+      if (isMember) {
+        // 캐시 저장
+        setCachedAuth(githubToken, true, user.login);
+
+        console.error(`[Palette Auth] ✅ 인증 성공: ${user.login} (${org})`);
+        return {
+          authorized: true,
+          username: user.login,
+          organization: org,
+        };
+      }
+    }
+
+    // 어떤 조직에도 속하지 않음
+    setCachedAuth(githubToken, false, user.login);
+
+    console.error(`[Palette Auth] ❌ 인증 실패: ${user.login} - 허용된 조직 멤버 아님`);
+    return {
+      authorized: false,
+      username: user.login,
+      error: `사용자 '${user.login}'은(는) dealicious-inc 조직 멤버가 아닙니다. 조직 관리자에게 문의하세요.`,
+    };
+  } catch (error: any) {
+    // 토큰 유효성 검사 실패
+    if (error.status === 401) {
+      return {
+        authorized: false,
+        error: 'GITHUB_TOKEN이 유효하지 않습니다. 토큰을 확인해주세요.',
+      };
+    }
+
+    // 기타 오류
+    console.error('[Palette Auth] 인증 중 오류 발생:', error.message);
+    return {
+      authorized: false,
+      error: `인증 중 오류가 발생했습니다: ${error.message}`,
+    };
+  }
+}
+
+/**
+ * 인증 캐시 초기화 (테스트용)
+ */
+export function clearAuthCache(): void {
+  authCache.clear();
+}

package/src/services/code-generator.ts

@@ -4,10 +4,22 @@ import { saveFile, saveBinaryFile, saveMetadata, generateRequestId, getRequestFo
 
 // puppeteer는 optional dependency로, 없으면 이미지 프리뷰 기능이 비활성화됨
 let puppeteer: any = null;
-try {
-  puppeteer = (await import('puppeteer')).default;
-} catch (e) {
-  console.warn('puppeteer를 로드할 수 없습니다. 이미지 프리뷰 기능이 비활성화됩니다.');
+let puppeteerLoaded = false;
+
+/**
+ * puppeteer를 lazy loading으로 로드
+ */
+async function loadPuppeteer(): Promise<any> {
+  if (puppeteerLoaded) return puppeteer;
+  
+  try {
+    puppeteer = (await import('puppeteer')).default;
+  } catch (e) {
+    console.warn('puppeteer를 로드할 수 없습니다. 이미지 프리뷰 기능이 비활성화됩니다.');
+    puppeteer = null;
+  }
+  puppeteerLoaded = true;
+  return puppeteer;
 }
 
 export interface GeneratedComponent {
@@ -91,13 +103,16 @@ export class CodeGenerator {
     componentName: string,
     requestId: string
   ): Promise<string> {
+    // puppeteer를 lazy loading으로 로드
+    const pptr = await loadPuppeteer();
+    
     // puppeteer가 없으면 이미지 생성 불가
-    if (!puppeteer) {
+    if (!pptr) {
       console.warn('puppeteer가 설치되지 않아 이미지 프리뷰를 생성할 수 없습니다.');
       return '';
     }
 
-    const browser = await puppeteer.launch({
+    const browser = await pptr.launch({
       headless: true,
       args: ['--no-sandbox', '--disable-setuid-sandbox']
     });