AI · MCP 서버

packages/coui_mcp 는 Model Context Protocol 서버다. Claude Code · Cursor 같은 AI 에이전트가 이 서버에 붙으면 CoUI 컴포넌트를 검색하고, 필요한 부분만 읽고, 코드를 생성하고, 검증하는 툴을 쓸 수 있다. 통신은 표준 입출력(stdio) 위의 JSON-RPC 이고, 서버 이름은 coui-mcp 다.

이 사이트의 llms.txt 가 "무엇이 있는가" 를 한 번에 보여주는 목록이라면, MCP 서버는 에이전트가 작업 중에 그때그때 물어보는 창구다.

실행 (Run)#

레포 루트에서 워크스페이스 의존성을 받은 뒤 실행한다. coui_mcp 는 워크스페이스 멤버라 레포 루트의 pub get 한 번으로 준비된다.

dart pub get
dart run packages/coui_mcp/bin/coui_mcp.dart

서버는 표준 입력을 기다린다 — 혼자 띄워 두는 용도가 아니라 에이전트가 자식 프로세스로 실행하는 용도다. 시작 로그(데이터 경로 등)는 표준 에러로 나가므로 JSON-RPC 출력과 섞이지 않는다.

옵션#

우선순위는 CLI 옵션 → 환경변수 → 번들 데이터 순이다.

등록 (Register)#

Claude Code#

이 레포의 .mcp.json 에 이미 coui 라는 이름으로 등록돼 있다. 레포를 연 Claude Code 세션은 별도 설정 없이 이 서버를 쓴다.

{
  "mcpServers": {
    "coui": {
      "command": "dart",
      "args": ["run", "packages/coui_mcp/bin/coui_mcp.dart"]
    }
  }
}

args 의 경로는 작업 디렉터리 기준이다. 레포 밖에서 등록할 때는 CoUI 체크아웃의 절대 경로를 적는다.

claude mcp add coui -- dart run /path/to/coui/packages/coui_mcp/bin/coui_mcp.dart

다른 클라이언트#

Cursor(.cursor/mcp.json) · Claude Desktop 도 같은 mcpServers 형식을 쓴다 — command 와 args 를 위와 똑같이 적는다.

툴 (Tools)#

서버는 툴 11개를 등록한다. 아래 목록은 tools/list 응답과 대조한 것이다. target 인자를 받는 툴은 "flutter"(기본값, coui_flutter) 또는 "jaspr"(coui_web) 를 고를 수 있다.

문서#

코드 생성#

list_patterns 가 돌려주는 패턴은 login · profile · dashboard · list-detail · settings · form · crud · master-detail 이다. jaspr 타깃에서는 login · form · dashboard 만 Web 코드로 나오고, 나머지는 Flutter 코드로 대신 나온다.

검증#

리소스 (Resources)#

툴이 "해 달라" 는 요청이라면 리소스는 "읽을 것" 이다. 에이전트는 필요한 URI 만 골라 읽는다.

컴포넌트 · 토큰 · 카테고리 (템플릿)#

{name} 은 소문자 스네이크 케이스 컴포넌트 이름이다 (button, alert_dialog).

통문서 (고정 URI)#

필요한 만큼만 읽기#

템플릿 리소스가 있는 이유는 통문서를 통째로 컨텍스트에 싣지 않기 위해서다. 이 페이지를 쓰면서 서버에 실제로 요청해 잰 응답 크기는 다음과 같다.

토큰 수가 아니라 글자 수이고, 번들 데이터가 바뀌면 달라진다. 그리고 overview 가 작은 것은 담는 것이 적기 때문이기도 하다 — 이름과 한 줄 설명뿐이라, 통문서가 주는 사용법을 대신하지는 않는다.

현재 한계 (Known limitations)#

서버에 실제로 요청해 확인한 것들이다. 고쳐지기 전까지 에이전트가 내놓은 결과를 그대로 믿지 않는다.

• 코드 생성이 존재하지 않는 API 를 쓴다. 버튼은 PrimaryButton(...) (Flutter) 이나 Button.primary(...) (Web) 로 나오지만 둘 다 CoUI 에 없다. 버튼 variant 는 Button(variant: CoreButtonVariant.primary, …) 다. Web 코드의 텍스트도 CoUI Text(...) chain 이 아니라 raw text(...) 로 나온다.
• validate_component 의 이름 제안이 현재 규약과 반대다. Button 을 PrimaryButton 으로 바꾸라고 제안한다 — 따르지 않는다.
• 토큰 리소스가 coui_core 의 토큰이 아니다. coui://tokens/spacing 은 xs · sm · md 같은 이름을 주지만 실제 토큰은 CoreSpace.space4 같은 namespace 다. 토큰은 이 사이트의 디자인 토큰 페이지를 기준으로 한다.
• api · examples 리소스가 비어 있을 수 있다. 예컨대 coui://component/button/api 는 속성 목록이 빈 채로 돌아오고, examples 는 예제 대신 안내 문구만 돌려준다.
• 컴포넌트 목록이 이 사이트와 다르다. 메타데이터는 83개 컴포넌트를 담고 있어, 사이트 카탈로그에 있는 컴포넌트 일부는 MCP 에 없다.

직접 확인하기#

서버가 응답하는지는 JSON-RPC 요청을 표준 입력으로 보내 확인할 수 있다. MCP 는 initialize 로 세션을 연 뒤에 다른 요청을 받는다.

{
  echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}'
  echo '{"jsonrpc":"2.0","method":"notifications/initialized"}'
  echo '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
  echo '{"jsonrpc":"2.0","id":3,"method":"resources/read","params":{"uri":"coui://component/button/overview"}}'
  sleep 5
} | dart run packages/coui_mcp/bin/coui_mcp.dart

id: 2 응답에 툴 11개, id: 3 응답에 버튼 개요 JSON 이 돌아오면 정상이다.