MCP 서버 (AI 연동)

Atomic CSS는 AI 어시스턴트를 위한 MCP(Model Context Protocol) 서버를 제공합니다. Claude, Cursor, Windsurf 같은 AI 도구가 Atomic CSS 클래스를 프로그래밍 방식으로 조회하고 사용할 수 있습니다.

MCP란?

MCP(Model Context Protocol)는 AI 모델이 외부 도구와 데이터에 접근할 수 있게 하는 표준 프로토콜입니다. Atomic CSS MCP 서버를 연결하면 AI가 정확한 클래스명을 조회하고, CSS 속성에서 클래스를 검색하고, 유효성을 검증할 수 있습니다.

1AI에게 "flexbox 센터 정렬 해줘"라고 요청

2AI가 MCP 서버의 도구를 호출하여 정확한 클래스를 조회

3MCP 서버가 df jcc aic 등 정확한 클래스와 CSS를 반환

✓AI가 올바른 Atomic CSS 클래스로 코드 작성

설정 방법

프로젝트 또는 AI 도구에 MCP 서버를 등록합니다.

Streamable HTTP (권장) — 최신 MCP 사양의 표준 전송 방식입니다. 엔드포인트: https://mcp.atomiccss.dev/mcp

SSE (레거시) — 현행 MCP 사양에서 더 이상 권장되지 않는(deprecated) 전송 방식이지만, 구버전 클라이언트 호환을 위해 계속 제공됩니다. 엔드포인트: https://mcp.atomiccss.dev/sse

.mcp.json (프로젝트 설정)

프로젝트 루트에 .mcp.json 파일을 생성하면, 해당 프로젝트에서 AI가 자동으로 MCP 서버를 인식합니다. 팀원과 공유할 수 있어 가장 권장하는 방법입니다.

.mcp.json

{
    "mcpServers": {
        "atomic-css": {
            "type": "http",
            "url": "https://mcp.atomiccss.dev/mcp"
        }
    }
}

Streamable HTTP를 지원하지 않는 구버전 클라이언트라면 레거시 SSE 설정을 사용하세요.

.mcp.json

{
    "mcpServers": {
        "atomic-css": {
            "type": "http",
            "url": "https://mcp.atomiccss.dev/mcp"
        }
    }
}

참고: 프로젝트 스코프 MCP 서버는 처음 사용 시 승인 프롬프트가 표시됩니다.

CLI로 추가

터미널에서 직접 MCP 서버를 등록할 수도 있습니다.

# Add via Claude Code (Streamable HTTP, recommended)
claude mcp add --transport http atomic-css https://mcp.atomiccss.dev/mcp

# Add to project scope (saved in .mcp.json)
claude mcp add --transport http --scope project atomic-css https://mcp.atomiccss.dev/mcp

# Add to user scope (available in all projects)
claude mcp add --transport http --scope user atomic-css https://mcp.atomiccss.dev/mcp

# Legacy SSE transport (fallback for older clients)
claude mcp add --transport sse atomic-css https://mcp.atomiccss.dev/sse

Claude Desktop

Claude Desktop 앱에서는 설정 파일에 추가합니다.

claude_desktop_config.json

{
    "mcpServers": {
        "atomic-css": {
            "type": "http",
            "url": "https://mcp.atomiccss.dev/mcp"
        }
    }
}

Cursor

Cursor에서는 Settings > MCP Servers에서 추가합니다.

{
    "name": "atomic-css",
    "url": "https://mcp.atomiccss.dev/mcp"
}

설정 스코프 비교

스코프	위치	공유	용도
`project`	프로젝트 루트 .mcp.json	예 (git으로 공유)	팀 공유·프로젝트별 설정 (권장)
`local`	~/.claude.json	X	개인 설정·현재 프로젝트만
`user`	~/.claude.json	X	모든 프로젝트에서 사용

제공 도구

MCP 서버를 연결하면 AI가 자동으로 아래 도구들을 사용합니다. 사용자가 직접 호출할 필요는 없습니다.

도구	설명
`get_guide`	Atomic CSS 전체 사용 가이드 반환 (네이밍 규칙, 단위, 미디어쿼리, 의사클래스 등)
`lookup_class`	클래스명 → CSS 출력 조회 (여러 클래스 한 번에 가능)
`search_by_css`	CSS 속성/값으로 Atomic CSS 클래스 검색
`css_to_classes`	CSS 코드를 Atomic CSS 클래스로 변환
`validate_classes`	클래스 유효성 검증 + 유사 클래스 추천
`list_classes`	카테고리별 클래스 목록 조회

팁: AI에게 처음 Atomic CSS 작업을 시킬 때 "get_guide를 먼저 호출해서 규칙을 학습해"라고 지시하면 더 정확한 클래스를 생성합니다.

도구 상세 사용법 (입력 → 출력)

각 도구의 실제 입력과 출력입니다. 어떤 LLM이든 이 예시만 보고도 Atomic CSS를 즉시 생성·검증할 수 있습니다.

아래 입출력 예시는 실제 서버(v1.2.0) 응답을 그대로 옮긴 것입니다. 서버 응답 문구는 한국어로 제공됩니다.

get_guide처음 1회 호출. Atomic CSS의 네이밍 규칙·워크플로우·전체 클래스 맵을 한 번에 학습합니다.

입력 예(none)출력 예Atomic CSS full guide: naming rules, workflow, class map

css_to_classes머릿속에 CSS가 있을 때 → 대응하는 Atomic 클래스로 변환합니다.

입력 예display: flex; gap: 20px; padding: 16px출력 예

변환 결과 (3개):
  display: flex → df
  gap: 20px → gap20px
  padding: 16px → p16px

클래스 조합: df gap20px p16px

validate_classes작성한 클래스가 유효한지 확인합니다. 무효한 클래스는 이유와 대안을 추천합니다.

입력 예df jcm gap2rem출력 예

2개 유효, 1개 무효

✗ 무효한 클래스:
  jcm — 인식할 수 없는 클래스
    추천: jcc, cm, jcfs

lookup_class특정 클래스가 실제로 어떤 CSS를 생성하는지 확인합니다.

입력 예dfi gap2rem출력 예

dfi → .dfi { display:flex !important; }

gap2rem → .gap2rem { row-gap: 2rem; column-gap: 2rem; }

search_by_css원하는 CSS 속성/값에 해당하는 클래스를 찾습니다.

입력 예justify-content출력 예

7개 결과:

jcfs → justify-content:flex-start
jcfe → justify-content:flex-end
jcc → justify-content:center
jcsb → justify-content:space-between
jcsa → justify-content:space-around
jcse → justify-content:space-evenly
jc--<var> → justify-content: var(--<var>) (단위 필요)

list_classes카테고리(flexbox, grid, spacing 등)의 전체 클래스를 조회합니다.

입력 예flexbox출력 예

[flexbox] 24개:

df dif fa fi fdr fdrr fdc fdcr fwn fww fwr fgu
jcfs jcfe acfs acfe aifs aife asfs asfe
fshi fshu jife jsfe

LLM 권장 워크플로우

어떤 언어모델이든 아래 3단계로 Atomic CSS를 정확하게 생성할 수 있습니다. 규칙을 익히면 도구 호출 없이 직접 작성하는 게 가장 빠릅니다.

1. 학습 — 처음 한 번 get_guide를 호출해 네이밍 규칙과 전체 클래스 체계를 익힙니다.

2. 작성 — 규칙을 알면 클래스를 직접 작성합니다(가장 빠름). 확신이 없으면 css_to_classes로 CSS를 변환하거나 search_by_css로 찾습니다.

3. 검증 — 작성한 클래스 전체를 validate_classes에 넣어 유효성을 확인하고, 무효 클래스는 추천대로 교정합니다.

Atomic CSS 100% 활용 규칙

아래는 get_guide가 LLM에게 전달하는 핵심 규칙입니다. 이 규칙만 지키면 어떤 UI든 Atomic CSS만으로 완성할 수 있습니다.

스타일은 100% Atomic 클래스로 — 인라인 style 속성이나 별도 CSS 파일을 만들지 않습니다.

시맨틱 클래스엔 CSS 정의 금지 — class="product-card"는 JS·시맨틱용으로만. 시각 스타일은 Atomic 클래스로 붙입니다.

atomic.min.css는 항상 마지막에 로드 — 기존 어떤 CSS보다 뒤에 두어 캐스케이드 우선순위를 확보합니다.

레이아웃은 Grid 우선 — dg + gtc 조합을 먼저 고려합니다.

단위 규칙 — 20px 미만은 px, 20px 이상은 rem(1rem = 10px). 단, 어떤 단위·수치든 자유롭게 쓸 수 있습니다.

간격은 4의 배수 권장 — 4·8·12·16·20·24·32… (강제가 아니라 권장. 값은 완전히 자유입니다).

올바른 예 — 시맨틱 클래스 + Atomic 클래스 조합

<!-- Semantic class (JS/meaning) + Atomic classes (all visual style) -->
<section class="product-card dg gtcr3-1fr gap2rem p2rem bg0F0F17 br8px">
  <article class="df fdc gap12px">
    <img class="w100p h20rem ofc br8px" src="photo.jpg" />
    <h3 class="fs1-8rem fw700 cFAFAFA">Title</h3>
    <p class="fs14px c71717A lh1-7">Description text</p>
  </article>
</section>

<!-- Load atomic.min.css LAST so it wins the cascade -->
<link rel="stylesheet" href="/css/your-styles.css" />
<link rel="stylesheet" href="/assets/css/atomic.min.css" />

공식 MCP Registry

Atomic CSS MCP 서버는 공식 MCP Registry에 등록되어 있습니다. 별도 설치 없이 https://mcp.atomiccss.dev/mcp URL만으로 바로 연동할 수 있습니다.

Registry ID	`io.github.Yoodaekyung/atomic-css`
상태	Active
연동 URL	`https://mcp.atomiccss.dev/mcp`

인증 불필요: 공개 API로 누구나 바로 사용 가능합니다. 설정에 URL만 추가하면 됩니다.

서버 정보

URL	`https://mcp.atomiccss.dev`
Streamable HTTP 엔드포인트	`https://mcp.atomiccss.dev/mcp`
SSE 엔드포인트 (레거시)	`https://mcp.atomiccss.dev/sse`
프로토콜	Streamable HTTP (권장) / SSE (레거시, deprecated)
인증	기본값은 인증 없는 공개 접근입니다. 서버는 Bearer 토큰 방식의 API 키 인증(MCP_API_KEY)을 지원하지만 현재 공개 서버에는 설정되어 있지 않아, 별도 헤더 없이 바로 연결할 수 있습니다.
요청 제한	IP당 분당 100회. 초과 시 Retry-After 헤더와 함께 429를 반환합니다. 상태 확인용 /health 경로는 제외됩니다.