@teamsparta/union-mcp

v1.1.1

Published

4 days ago

MCP server for TeamSparta Union monorepo packages

Union MCP

MCP (Model Context Protocol) server for TeamSparta Union Monorepo packages.

Union MCP는 LLM이 TeamSparta 공용 패키지(@teamsparta/react, @teamsparta/utils, @teamsparta/types, @teamsparta/hackle 등)의 스펙을 이해하고 활용할 수 있도록 컨텍스트를 제공하는 서버입니다.

사용자 가이드

필수 조건

Node.js >= 18.0.0

설치 방법

Claude Code

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

Cursor / Claude Desktop

MCP 설정 파일에 다음 내용을 추가하세요:

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

설정 파일 위치:

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

제공 기능

Union 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`

Union 패키지의 전체 가이드라인을 가져옵니다.

포함 내용: 패키지 선택 가이드, import 규칙, 베스트 프랙티스, 흔한 실수

사용 시기: 패키지의 전반적인 사용 가이드를 이해할 때

사용 예제

예제 1: 사용 가능한 유틸리티 확인

@teamsparta/utils에 어떤 함수들이 있나요?

LLM이 list_components를 호출하여 Utils-String, Utils-Array, Utils-Date 등을 찾아 보여줍니다.

예제 2: 훅 사용법 확인

useDebounce 훅의 사용법을 알려주세요.

LLM이 get_component_context로 React-Hooks 스펙을 가져와 정확한 API와 사용법을 제공합니다.

예제 3: 여러 패키지 문서 조회

React-Hooks와 Utils-Date의 스펙을 한 번에 보여주세요.

LLM이 get_docs_by_names로 두 스펙을 한 번에 가져옵니다.

개발자 가이드

프로젝트 구조

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

스펙 문서 작성

각 패키지의 스펙 문서는 해당 패키지 디렉토리에 위치하며, 다음 규칙을 따릅니다:

파일 위치

packages/[package-name]/AI_[NAME]_SPEC.md

예: packages/react/AI_REACT-HOOKS_SPEC.md, packages/utils/AI_UTILS-STRING_SPEC.md

Front Matter 필수 필드

---
name: React-Hooks
package: "@teamsparta/react"
description: "React 커스텀 훅 모음"
dependencies:
  - React-Utils
---

# 상세 스펙 내용...

필드 설명:

name (필수): 패키지/유틸리티의 정확한 이름. list_components에 표시됩니다.
package (필수): npm 패키지 이름
description (필수): 한 줄 설명
dependencies (선택): 의존하는 다른 스펙의 이름 배열

빌드 프로세스

pnpm build

빌드 시 자동으로 다음이 수행됩니다 (prebuild):

copy-specs: monorepo의 모든 packages/**/AI_*_SPEC.md를 src/specs/와 dist/specs/로 복사
copy-guideline: UNION_GUIDELINE.md를 dist/로 복사
tsc: TypeScript 컴파일

업데이트 워크플로우

스펙 문서가 변경되었을 때:

# 1. 스펙 수정
vi packages/react/AI_REACT-HOOKS_SPEC.md

# 2. MCP 빌드
cd packages/mcp && pnpm build

# 3. 배포
pnpm changeset
pnpm changeset version
pnpm publish

주의: 스펙 변경 시 반드시 MCP 패키지도 함께 빌드 및 배포해야 합니다.

개발 명령어

# 개발 모드 (watch)
pnpm dev

# 프로덕션 빌드
pnpm build

# MCP Inspector로 테스트
pnpm build && npx @modelcontextprotocol/inspector node dist/index.js

# 빌드 결과 정리
pnpm clear

라이선스

MIT License - TeamSparta