Stack MCP

MCP (Model Context Protocol) server for TeamSparta Stack Design System.

Stack MCP는 LLM이 TeamSparta 디자인 시스템의 컴포넌트 스펙을 이해하고 활용할 수 있도록 컨텍스트를 제공하는 서버입니다.

목차

• 사용자 가이드
  • 필수 조건
  • 설치 방법
  • 제공 기능
  • 사용 예제
• 개발자 가이드
  • 프로젝트 구조
  • 스펙 문서 작성
  • 빌드 프로세스
  • 업데이트 워크플로우
  • 개발 명령어

사용자 가이드

필수 조건

• Node.js >= 18.0.0

설치 방법

Claude Code

claude mcp add stack-mcp -s user npx @teamsparta/stack-mcp@latest

Cursor / Claude Desktop

Claude Desktop 또는 Cursor의 MCP 설정 파일에 다음 내용을 추가하세요:

{
  "mcpServers": {
    "stack-mcp": {
      "command": "npx",
      "args": ["-y", "@teamsparta/stack-mcp@latest"]
    }
  }
}

설정 파일 위치:

• Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
• Cursor: .cursor/mcp.json (프로젝트 루트)

제공 기능

Stack MCP는 다음 5가지 도구를 제공합니다:

1. list_components

사용 가능한 모든 컴포넌트와 디자인 토큰 목록을 조회합니다.

반환 정보:

• 컴포넌트/토큰 이름
• 패키지 이름
• 간단한 설명

사용 시기: 어떤 컴포넌트가 있는지 확인할 때

2. get_component_context

특정 컴포넌트의 전체 스펙 문서를 가져옵니다.

파라미터:

• componentName (필수): 컴포넌트 이름
• includeDependencies: 의존성 포함 여부 ("all" | "none" | "auto")
• maxDepth: 의존성 탐색 깊이
• maxTotalChars: 반환될 최대 문자 수 (기본값: 50,000)
• includeDocsFor: 우선적으로 포함할 컴포넌트 목록

사용 시기: 컴포넌트의 상세 스펙과 사용법을 알고 싶을 때

3. get_component_manifest

컴포넌트의 의존성 정보만 가져옵니다 (경량).

반환 정보:

• 컴포넌트 이름, 패키지
• 문서 크기 (바이트, 예상 토큰 수)
• 의존성 목록

사용 시기: 큰 컴포넌트의 구조를 먼저 파악하고 필요한 부분만 선택적으로 가져올 때

4. get_docs_by_names

여러 컴포넌트의 스펙 문서를 한 번에 가져옵니다.

파라미터:

• names (필수): 가져올 컴포넌트 이름 배열
• mode: 반환 형식 ("merged" | "separate")

사용 시기: 특정 컴포넌트들의 문서를 배치로 가져올 때

5. get_guidelines

Stack 디자인 시스템의 전체 가이드라인을 가져옵니다.

포함 내용:

• 핵심 원칙
• 컴포넌트 사용 패턴
• 모범 사례
• 흔한 실수

사용 시기: 디자인 시스템의 전반적인 철학과 사용 가이드를 이해할 때

사용 예제

예제 1: 사용 가능한 컴포넌트 확인

Stack 디자인 시스템에 어떤 버튼 컴포넌트가 있나요?

LLM이 list_components를 호출하여 Button, IconButton, TextButton 등을 찾아 보여줍니다.

예제 2: 컴포넌트 사용법 확인

Button 컴포넌트를 사용해서 Primary 스타일의 Large 버튼을 만들고 싶어요.

LLM이 get_component_context로 Button 스펙을 가져와 정확한 props와 사용법을 제공합니다.

예제 3: 복잡한 UI 구성

BottomSheet 안에 TextInput과 Button을 배치하려고 해요. 각 컴포넌트의 스펙을 확인해주세요.

LLM이 get_docs_by_names로 BottomSheet, TextInput, Button의 스펙을 한 번에 가져와 제공합니다.

예제 4: 의존성 파악 후 선택적 로딩

CustomModal의 의존성 구조를 먼저 보여주고, 필요한 부분만 자세히 설명해주세요.

LLM이 먼저 get_component_manifest로 의존성 트리를 확인한 후, 필요한 컴포넌트만 get_docs_by_names로 가져옵니다.

개발자 가이드

프로젝트 구조

packages/mcp/
├── src/
│   ├── index.ts                 # MCP 서버 진입점
│   ├── utils/
│   │   └── spec-collector.ts    # 스펙 수집 및 의존성 관리
│   ├── specs/                   # 빌드 시 생성되는 스펙 파일 디렉토리
│   └── STACK_GUIDELINE.md       # 디자인 시스템 가이드라인
├── scripts/
│   ├── copy-specs.ts            # 스펙 파일 복사 스크립트
│   └── copy-guideline.ts        # 가이드라인 복사 스크립트
├── dist/                        # 빌드 결과물
├── package.json
├── tsconfig.json
└── README.md

주요 파일 설명:

• index.ts: MCP 서버의 메인 로직. 5가지 tool 핸들러 구현
• spec-collector.ts: 스펙 파일 로딩, 의존성 해석, 컨텍스트 생성 로직
• copy-specs.ts: monorepo 전체에서 AI_*_SPEC.md 파일을 찾아 복사
• copy-guideline.ts: 가이드라인 문서를 dist로 복사

스펙 문서 작성

각 컴포넌트의 스펙 문서는 해당 컴포넌트 패키지 내부에 위치하며, 다음 규칙을 따릅니다:

파일 위치

packages/[component-name]/AI_[COMPONENTNAME]_SPEC.md

예: packages/button/AI_BUTTON_SPEC.md

Front Matter 필수 필드

스펙 문서는 YAML front matter로 메타데이터를 포함해야 합니다:

---
name: Button
package: "@teamsparta/button"
description: "기본 버튼 컴포넌트"
dependencies:
  - Tokens
  - Icons
---

# Button 컴포넌트 상세 스펙...

필드 설명:

• name (필수): 컴포넌트의 정확한 이름. list_components에 표시됩니다.
• package (필수): npm 패키지 이름
• description (필수): 한 줄 설명
• dependencies (선택): 의존하는 다른 컴포넌트/토큰의 이름 배열

파일명 규칙

• 형식: AI_[COMPONENTNAME]_SPEC.md
• COMPONENTNAME은 대문자와 하이픈으로 구성
• 하이픈은 camelCase로 변환됨 (예: AI_TEXT-INPUT_SPEC.md → TextInput)

빌드 프로세스

빌드는 다음 단계로 진행됩니다:

1. 스펙 파일 수집 (pnpm copy-specs)

scripts/copy-specs.ts가 실행되어:

1. monorepo의 모든 packages/**/AI_*_SPEC.md 파일을 찾습니다
2. 파일들을 src/specs/ 디렉토리로 복사합니다
3. 이후 TypeScript 빌드 시 dist/specs/로도 복사됩니다

2. 가이드라인 복사 (pnpm copy-guideline)

scripts/copy-guideline.ts가 실행되어:

1. src/STACK_GUIDELINE.md를 읽습니다
2. dist/STACK_GUIDELINE.md로 복사합니다

3. TypeScript 컴파일 (pnpm build)

tsc를 실행하여 TypeScript를 JavaScript로 컴파일합니다.

전체 빌드 명령어

pnpm prebuild  # copy-specs + copy-guideline
pnpm build     # TypeScript 컴파일

또는 한 번에:

pnpm build

업데이트 워크플로우

컴포넌트 패키지에서 변경이 발생했을 때 MCP 패키지 업데이트 절차:

1. 스펙 문서 수정

# 예: Button 컴포넌트의 스펙 수정
vi packages/button/AI_BUTTON_SPEC.md

2. MCP 패키지 빌드

cd packages/mcp
pnpm build

빌드 시 자동으로 최신 스펙 파일들이 수집됩니다.

3. 버전 업데이트 및 배포

# package.json의 version 업데이트
# 또는 changeset 사용
pnpm changeset
pnpm changeset version
pnpm publish

주의사항

• 컴포넌트 패키지 변경 시, 반드시 MCP 패키지도 함께 빌드 및 배포해야 합니다
• 스펙 문서의 front matter 필드가 올바른지 확인하세요

개발 명령어

로컬 개발

# 개발 모드 (watch 모드)
pnpm dev

파일 변경 시 자동으로 재시작됩니다.

테스트

MCP Inspector를 사용한 인터랙티브 테스트 (권장)

MCP Inspector는 서버를 인터랙티브하게 테스트할 수 있는 공식 도구입니다.

# 1. 빌드
pnpm build

# 2. Inspector 실행
npx @modelcontextprotocol/inspector node dist/index.js

Inspector는 다음 기능을 제공합니다:

• Tools 탭: 제공하는 5가지 tool 테스트
• Resources 탭: 리소스 메타데이터 확인
• Notifications 패널: 서버 로그 및 에러 메시지 확인

개발 워크플로우:

1. 코드 수정
2. pnpm build로 재빌드
3. Inspector에서 "Reconnect" 클릭
4. 변경된 기능 테스트

자세한 사용법은 MCP Inspector 공식 문서를 참고하세요.

직접 실행

# 빌드
pnpm build

# 직접 실행
node dist/index.js

Claude Desktop/Cursor에서 로컬 경로 사용

Claude Desktop 또는 Cursor 설정에서 로컬 빌드를 직접 연결:

{
  "mcpServers": {
    "stack-mcp-local": {
      "command": "node",
      "args": ["/absolute/path/to/stack/packages/mcp/dist/index.js"]
    }
  }
}

빌드

# 프로덕션 빌드
pnpm build

# 빌드 결과 정리
pnpm clear

라이선스

MIT License - TeamSparta

문의

문제가 발생하거나 제안사항이 있으시면 이슈를 등록해주세요.