SigmaUI DS — MCP Server

Servidor MCP (Model Context Protocol) que expõe os componentes do SigmaUI DS para assistentes de IA consultarem durante o desenvolvimento de telas Vue 3 e Nuxt 3.

---

Stack

Tecnologia	Papel
Bun >= 1.1	Runtime, bundler, test runner e gerenciador de pacotes
Hono + @hono/mcp	Framework HTTP + adaptador MCP
@modelcontextprotocol/sdk ^1.29	SDK MCP (tools, resources, prompts)
AI SDK (ai, @ai-sdk/google, @ai-sdk/anthropic, @ai-sdk/openai)	Curadoria automática provider-agnostic
Zod ^4.0	Validação de schemas
Prettier	Formatação de SFC (Vue) e TypeScript gerado
@vue/compiler-sfc	Parser oficial para extração de slots via AST

---

Instalação

git clone <url-do-repositorio>
cd sigmaui-ds-mcp-server
bun install
cp .env.example .env
bun run dev

O servidor sobe em http://localhost:3333.

---

Docker

docker compose up -d

O script catalog:generate precisa de acesso ao repositório pd-sigmaui-ds — rode-o localmente antes de buildar a imagem.

---

Scripts

Script	Descrição
bun run dev	Desenvolvimento com hot-reload (HTTP)
bun run start	Produção (HTTP)
bun run stdio	Integração local com IDEs/CLIs (stdio)
bun run inspect	MCP Inspector
bun run catalog:generate	Gera e curada componentes no catálogo
bun run test	Executa testes
bun run test:watch	Testes em modo watch
bun run test:coverage	Testes com cobertura

---

Variáveis de ambiente

Variável	Padrão	Descrição
PORT	3333	Porta do servidor HTTP
ALLOWED_ORIGINS	http://localhost	Origens CORS (separadas por vírgula)
SIGMAUI_DS_PATH	../pd-sigmaui-ds	Caminho para o repositório do DS
SKIP_CURATE	false	Pula curadoria IA
CURATE_PROVIDER	google	Provider: google, anthropic ou openai
CURATE_MODEL	gemini-2.5-flash	Modelo do provider
GOOGLE_GENERATIVE_AI_API_KEY	—	API key Google AI Studio
ANTHROPIC_API_KEY	—	API key Anthropic
OPENAI_API_KEY	—	API key OpenAI

---

Ferramentas MCP

Ferramenta	Parâmetros	Descrição
list_components	category?	Lista componentes com filtro por categoria
get_component	name	Documentação completa: props, eventos, slots, exemplo
search_components	query	Busca textual por nome, descrição ou categoria
get_usage_example	name, framework?	Exemplo SFC completo (vue/nuxt)
get_design_tokens	—	Variantes de cor e tamanhos
get_form_pattern	fields, mode?	Padrão de formulário com vee-validate + Zod
suggest_components	description	Sugere componentes para um caso de uso
compare_components	component_a, component_b	Compara dois componentes lado a lado
get_data_table_columns	columns	Gera definição de colunas para DataTable

---

Recursos MCP

URI	Descrição
sigmaui://catalog	Catálogo resumido (nome, categoria, descrição)
sigmaui://component/{name}	Detalhes JSON de um componente

---

Prompts MCP

Prompt	Descrição
implement_screen	Gera prompt para implementar uma tela
create_form	Gera prompt para formulário com vee-validate + Zod
review_component_usage	Revisa uso correto dos componentes
curate_catalog_entry	Guia curadoria de uma entrada do catálogo

O argumento framework aceita "vue" (padrão) ou "nuxt".

---

Integração com clientes MCP

stdio (recomendado para uso local)

claude mcp add sigmaui-ds bun /caminho/absoluto/para/sigmaui-ds-mcp-server/src/stdio.ts

HTTP (debug, deploy remoto)

bun run dev
claude mcp add sigmaui-ds --transport http http://localhost:3333/mcp

---

Manutenção do catálogo

O source of truth é src/data/catalog.json. O arquivo src/data/catalog.ts é derivado (gerado automaticamente).

Adicionando componentes

export GOOGLE_GENERATIVE_AI_API_KEY=sua-chave
bun run catalog:generate

O pipeline:

1. Extrai metadados via @vue/compiler-sfc (props, emits, slots via AST) e Storybook stories
2. Curada via AI SDK (provider-agnostic): corrige tipos, gera descrição/whenToUse/notes/exemplo
3. Formata exemplos SFC com Prettier (Vue parser, singleAttributePerLine)
4. Serializa catalog.ts com Prettier (TypeScript parser)
5. Detecta mudanças via hash SHA-256 (só reprocessa componentes alterados)

Componentes já curados são preservados — SKIP_CURATE=true não sobrescreve dados enriquecidos.

Outro provider

CURATE_PROVIDER=openai CURATE_MODEL=gpt-4.1-mini bun run catalog:generate

---

Testes

bun run test

Arquivo	Cobertura
src/app.test.ts	Health check, middleware origin validation
src/tools/get-component.test.ts	Markdown output, lookup, sugestões
src/tools/search-components.test.ts	matchesQuery, integração com catálogo
src/prompts/templates.test.ts	Branching vue/nuxt, formulários, curadoria
scripts/generate-catalog.test.ts	Utils do pipeline (toPascalCase, poolMap, hash)
scripts/lib/utils.test.ts	resolveComponentName, parseSubComponents
scripts/lib/serialize.test.ts	formatSfcExample (Prettier)
scripts/lib/curate.test.ts	Curadoria IA (MockLanguageModelV3)

---

Estrutura

sigmaui-ds-mcp-server/
├── src/
│   ├── index.ts               # Entry HTTP (Bun.serve + graceful shutdown)
│   ├── stdio.ts               # Entry stdio (stderr logging)
│   ├── app.ts                 # Hono (CORS, origin validation, transport)
│   ├── mcp.ts                 # Orquestrador McpServer
│   ├── config.ts              # Constantes (PORT, CORS)
│   ├── types.ts               # ComponentInfo interface
│   ├── data/
│   │   ├── catalog.json       # Source of truth (71 componentes)
│   │   └── catalog.ts         # Derivado (gerado por Prettier)
│   ├── tools/                 # 9 ferramentas MCP
│   ├── resources/             # Resources MCP (sigmaui://)
│   └── prompts/               # 4 prompts MCP
├── scripts/
│   ├── generate-catalog.ts    # Orquestrador do pipeline
│   └── lib/
│       ├── extractors.ts      # Parsing via @vue/compiler-sfc + Storybook
│       ├── curate.ts          # AI SDK (provider-agnostic, .nullable() schema)
│       ├── serialize.ts       # JSON.stringify + Prettier (Vue + TS)
│       ├── hashes.ts          # SHA-256 change detection
│       ├── utils.ts           # toPascalCase, poolMap, readSafe
│       └── preload.ts         # Bun plugin (mock .vue/.css)
├── Dockerfile
├── docker-compose.yml
└── .env.example