# SigmaUI DS — MCP Server

Servidor [MCP (Model Context Protocol)](https://modelcontextprotocol.io) 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](https://bun.sh) `>= 1.1` | Runtime, bundler, test runner e gerenciador de pacotes |
| [Hono](https://hono.dev) + [`@hono/mcp`](https://github.com/honojs/middleware/tree/main/packages/mcp) | Framework HTTP + adaptador MCP |
| [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk) `^1.29` | SDK MCP (tools, resources, prompts) |
| [AI SDK](https://ai-sdk.dev) (`ai`, `@ai-sdk/google`, `@ai-sdk/anthropic`, `@ai-sdk/openai`) | Curadoria automática provider-agnostic |
| [Zod](https://zod.dev) `^4.0` | Validação de schemas |
| [Prettier](https://prettier.io) | Formatação de SFC (Vue) e TypeScript gerado |
| [`@vue/compiler-sfc`](https://github.com/vuejs/core) | Parser oficial para extração de slots via AST |

---

## Instalação

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

```bash
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)

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

### HTTP (debug, deploy remoto)

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

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

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

---

## Testes

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