@teamsparta/union-mcp

TeamSparta Union 모노레포의 코드 스펙(hook/util/component/type)을 MCP 호환 에이전트에 서빙하는 stdio MCP 서버입니다. search_union_api 단일 도구로 심볼·카테고리·키워드 질의에 정확한 스펙을 반환합니다.

역할 분리

union-mcp는 정확한 스펙을 서빙하는 역할만 담당합니다. "언제 union util/hook을 써야 하는가"의 트리거와 코드 작성 규칙은 별도의 union-code-rules Skill(ts-fe 플러그인)이 담당합니다.

| 구성요소 | 담당 | 배포 | |---|---|---| | union-code-rules (Skill) | 트리거 + 코드 작성 규칙. "코드 작성 전 union-mcp로 스펙 확인" 지시 | ts-fe 플러그인 마켓플레이스 | | union-mcp (이 패키지) | search_union_api로 정확한 스펙 서빙 | MCP 서버 (npx @teamsparta/union-mcp) |

Skill의 description이 Claude Code startup에 상주하여 자동 트리거를 책임지고, Skill 본문이 union-mcp 호출을 지시합니다. 따라서 union-mcp 자체는 트리거를 신경 쓸 필요 없이 서빙에 집중합니다.

목차

• 설치
• 제공 도구
• 사용 예제
• 개발자 가이드

설치

Claude Code (권장)

ts-fe 플러그인 마켓플레이스가 union-code-rules Skill 복사와 union-mcp 등록을 함께 처리합니다. 별도의 설치 CLI는 없습니다.

비-Claude-Code 클라이언트 (Cursor, Claude Desktop 등)

MCP 설정에 다음 한 줄을 추가하면 search_union_api 도구를 사용할 수 있습니다.

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

Skill은 Claude Code 전용이므로, 이 클라이언트들은 코드 작성 규칙(Skill) 없이 MCP search 도구만 사용하게 됩니다.

제공 도구

search_union_api

자연어 query → 매칭 spec 반환. 5단계 폴백 검색으로 동작합니다:

1. exact: useDebounce → 정확 매칭
2. substring: Debounce → 부분 매칭
3. keyword: 디바운스 → useDebounce (한국어·의도 매칭)
4. fuzzy (Levenshtein ≤ 2): useDebouce → useDebounce 오타 복구
5. category: react-hooks → 카테고리 인덱스 / 매칭 0건 → 후보 안내

파라미터:

• query (필수): 심볼명, 카테고리, 키워드
• maxChars (옵션, 기본 8000): 응답 최대 크기

Legacy 도구 (deprecated, v3에서 제거)

list_components, get_component_context, get_component_manifest, get_docs_by_names, get_guidelines — 모두 search_union_api로 자동 위임됩니다. 호출 시 stderr에 deprecation 안내가 표시됩니다.

사용 예제

"useDebounce 어떻게 써?"
→ search_union_api({ query: "useDebounce" }) → 스펙 반환

"디바운스 처리하고 싶어"
→ search_union_api({ query: "디바운스" }) → keyword 매칭 → useDebounce

"react-hooks 전체 보여줘"
→ search_union_api({ query: "react-hooks" }) → 카테고리 인덱스 반환

개발자 가이드

프로젝트 구조

packages/mcp/
├── src/
│   ├── index.ts                  # stdio 엔트리포인트
│   ├── server.ts                 # MCP 서버 (search_union_api + legacy shim)
│   ├── search.ts                 # 5단계 폴백 검색
│   ├── format-result.ts          # 검색 결과 포맷
│   ├── schemas.ts                # zod 스키마 (SPEC/INDEX/SearchArgs)
│   ├── build/                    # 빌드 파이프라인 (SPEC → MCP 서빙 데이터)
│   │   ├── build-from-specs.ts   # 메인 빌드
│   │   ├── parse-spec.ts         # front-matter + H2 split
│   │   ├── generate-index.ts     # INDEX.json 생성
│   │   ├── generate-references.ts# references/*.md 생성
│   │   ├── category-dir.ts       # 카테고리 → 디렉터리 매핑
│   │   └── verify-output.ts      # postbuild 무결성 검증
│   └── utils/levenshtein.ts
└── dist/
    ├── index.js / server.js
    └── skill/
        ├── INDEX.json            # 검색 인덱스
        └── references/{...}/*.md # 심볼별 스펙 (MCP 서빙 데이터)

빌드는 packages/*/AI_*_SPEC.md 단일 진실 원천에서 dist/skill/INDEX.json과 dist/skill/references/*.md(MCP 서빙 데이터)를 생성합니다. SKILL.md나 HTTPS 배포용 산출물은 생성하지 않습니다.

SPEC 작성

각 패키지의 SPEC 문서는 packages/[package-name]/AI_[NAME]_SPEC.md에 위치합니다 (ruletani auto-PR로 자동 생성).

---
name: React-Hooks
package: "@teamsparta/react"
description: "React custom hooks for state management"
dependencies:
  - Utils-Predicate
---

## useBoolean
... (각 심볼이 H2 헤딩 단위)

빌드

pnpm --filter @teamsparta/union-mcp build        # clear + build:specs + tsc
pnpm --filter @teamsparta/union-mcp build:specs  # SPEC → dist/skill/ (재빌드)

MCP Inspector로 수동 검증

pnpm --filter @teamsparta/union-mcp build
npx @modelcontextprotocol/inspector node packages/mcp/dist/index.js

브라우저 UI에서 search_union_api({ query: "useDebounce" }) 호출.

라이선스

MIT License — TeamSparta