@maestro-ai/mcp-server 1.2.0 → 2.1.0

package/dist/content/skills/specialist-contrato-api/MCP_INTEGRATION.md

@@ -0,0 +1,152 @@
+# Integração MCP - Contrato de API
+
+**Versão:** 2.0  
+**Última Atualização:** 31/01/2026
+
+---
+
+## 🤖 Funções MCP Disponíveis
+
+### **1. init_api_contract**
+
+**Propósito:** Inicializar contrato OpenAPI a partir de requisitos e modelo de domínio
+
+**Input:**
+```typescript
+{
+  requisitos: string;
+  modeloDominio: string;
+  arquitetura: string;
+  stack: {
+    frontend: string;    // "React", "Vue", etc.
+    backend: string;     // "NestJS", "Express", etc.
+    database: string;    // "PostgreSQL", "MongoDB", etc.
+  };
+}
+```
+
+**Output:**
+```typescript
+{
+  openapi: string;         // OpenAPI 3.0 YAML
+  endpoints: Endpoint[];   // Lista de endpoints
+  schemas: Schema[];       // Schemas reutilizáveis
+  version: string;         // Versão semântica
+}
+```
+
+---
+
+### **2. validate_api_contract**
+
+**Propósito:** Validar contrato OpenAPI e gerar score de qualidade
+
+**Input:**
+```typescript
+{
+  openapi: string;         // OpenAPI YAML
+  strictMode?: boolean;    // Modo rigoroso
+}
+```
+
+**Output:**
+```typescript
+{
+  score: number;           // 0-100
+  aprovado: boolean;       // true se >= 75
+  detalhes: {
+    schemaOpenAPI: { score: number; itens: ChecklistItem[]; };
+    typesEDTOs: { score: number; itens: ChecklistItem[]; };
+    mocks: { score: number; itens: ChecklistItem[]; };
+    documentacao: { score: number; itens: ChecklistItem[]; };
+    backwardCompatibility: { score: number; itens: ChecklistItem[]; };
+  };
+  recomendacoes: string[];
+}
+```
+
+**Checklist (100 pontos):**
+- Schema OpenAPI (30 pts): Válido, completo, versionado
+- Types e DTOs (25 pts): Gerados sem erros
+- Mocks (20 pts): Configurados e funcionais
+- Documentação (15 pts): Swagger UI + exemplos
+- Backward Compatibility (10 pts): Breaking changes documentados
+
+---
+
+### **3. process_api_contract**
+
+**Propósito:** Gerar types, DTOs e mocks a partir do contrato
+
+**Input:**
+```typescript
+{
+  openapi: string;
+  stack: {
+    frontend: string;
+    backend: string;
+  };
+  validacao: ValidationResult;
+}
+```
+
+**Output:**
+```typescript
+{
+  typesFrontend: string;   // TypeScript interfaces
+  dtosBackend: string[];   // DTOs com validações
+  mockHandlers: string;    // MSW handlers
+  swaggerUI: string;       // HTML Swagger UI
+  proximaFase: {
+    nome: string;
+    especialista: string;
+    artefatosEntrada: string[];
+  };
+}
+```
+
+---
+
+## 📊 Quality Gates
+
+**Score Mínimo:** 75/100  
+**Modo Rigoroso:** 85/100
+
+**Critérios de Bloqueio:**
+- OpenAPI inválido (erros de lint)
+- Endpoints sem schemas
+- Sem exemplos de request/response
+- Types com erros TypeScript
+
+---
+
+## 🔄 Fluxo Completo
+
+```typescript
+// 1. Inicializar contrato
+const contrato = await mcp.initApiContract({
+  requisitos, modeloDominio, arquitetura, stack
+});
+
+// 2. Validar qualidade
+const validacao = await mcp.validateApiContract({
+  openapi: contrato.openapi
+});
+
+// 3. Se aprovado, processar
+if (validacao.aprovado) {
+  const resultado = await mcp.processApiContract({
+    openapi: contrato.openapi,
+    stack,
+    validacao
+  });
+  
+  // Salvar artefatos gerados
+  await saveGeneratedFiles(resultado);
+}
+```
+
+---
+
+**Versão:** 2.0  
+**Arquitetura:** Skill Descritiva + Automação MCP

package/dist/content/skills/specialist-contrato-api/README.md

@@ -0,0 +1,183 @@
+# Especialista em Contrato de API
+
+**Versão:** 2.0  
+**Última Atualização:** 31/01/2026  
+**Status:** ✅ Estrutura Moderna Completa
+
+---
+
+## 📋 Visão Geral
+
+Especialista em definir contratos de API usando OpenAPI/Swagger, garantindo que frontend e backend compartilhem a mesma fonte de verdade através de contract-first development com mocks, types gerados e validação automatizada.
+
+### **Quando Usar**
+
+- **Fase:** Fase 9 - Contrato de API
+- **Após:** Requisitos, Modelo de Domínio e Arquitetura definidos
+- **Antes:** Desenvolvimento Frontend e Backend
+- **Workflows:** `/implementar-historia`, `/refatorar-codigo`
+
+### **Valor Entregue**
+
+- Contrato OpenAPI 3.0 completo e validado
+- Types TypeScript gerados para frontend
+- DTOs gerados para backend
+- Mock server configurado (MSW, json-server ou Prism)
+- Documentação interativa (Swagger UI)
+- Versionamento semântico definido
+
+---
+
+## 📥 Artefatos de Entrada
+
+| Artefato | Localização | Obrigatório |
+|----------|-------------|-------------|
+| **Requisitos** | `docs/02-requisitos/requisitos.md` | ✅ Sim |
+| **Modelo de Domínio** | `docs/04-modelo/modelo-dominio.md` | ✅ Sim |
+| **Arquitetura** | `docs/06-arquitetura/arquitetura.md` | ✅ Sim |
+| **Casos de Uso** | Dentro de requisitos | ✅ Sim |
+| **Stack Técnica** | Dentro de arquitetura | ✅ Sim |
+
+---
+
+## 📤 Artefatos de Saída
+
+| Artefato | Localização | Descrição |
+|----------|-------------|-----------|
+| **Contrato API** | `docs/09-api/contrato-api.md` | Especificação OpenAPI completa |
+| **OpenAPI YAML** | `docs/09-api/openapi.yaml` | Schema validado |
+| **Types Frontend** | `src/types/api.ts` | Interfaces TypeScript |
+| **DTOs Backend** | `src/dtos/` | Data Transfer Objects |
+| **Mock Handlers** | `mocks/handlers/` | Handlers MSW |
+
+---
+
+## 🎯 Processo de Criação
+
+### **1. Definir Schema OpenAPI**
+
+**Ordem:**
+1. Info (title, version, description)
+2. Servers (dev, staging, prod)
+3. Paths (endpoints com verbos HTTP)
+4. Components (schemas reutilizáveis)
+5. Security (autenticação)
+6. Examples (request/response)
+
+### **2. Gerar Types Frontend**
+
+**Ferramentas:**
+- `openapi-typescript` - Gera types TS
+- `orval` - Gera hooks React Query
+- `swagger-codegen` - Gera SDKs
+
+### **3. Gerar DTOs Backend**
+
+**Padrão NestJS:**
+- CreateXxxDto (validação com class-validator)
+- UpdateXxxDto (campos opcionais)
+- XxxResponseDto (formato de saída)
+
+### **4. Configurar Mock Server**
+
+**Opções:**
+- **MSW:** Mock Service Worker (browser + Node)
+- **json-server:** API REST rápida
+- **Prism:** Mock server OpenAPI nativo
+
+---
+
+## ✅ Quality Gates
+
+### **Checklist Obrigatório (Score Mínimo: 75/100)**
+
+**Schema OpenAPI (30 pontos):**
+- [ ] OpenAPI 3.0 válido (sem erros de lint)
+- [ ] Todos os endpoints documentados
+- [ ] Request/Response schemas definidos
+- [ ] Códigos de erro (400, 401, 404, 500)
+- [ ] Versionamento semântico
+
+**Types e DTOs (25 pontos):**
+- [ ] Types TypeScript gerados sem erros
+- [ ] DTOs backend com validações
+- [ ] Enums e interfaces reutilizáveis
+
+**Mocks (20 pontos):**
+- [ ] Mock server configurado
+- [ ] Dados de exemplo realistas
+- [ ] Response time < 100ms
+
+**Documentação (15 pontos):**
+- [ ] Swagger UI funcionando
+- [ ] Exemplos de uso
+- [ ] Guia de versionamento
+
+**Backward Compatibility (10 pontos):**
+- [ ] Breaking changes documentados
+- [ ] Estratégia de migração definida
+
+---
+
+## 🔄 Context Flow
+
+### **Entrada desta Fase**
+- Requisitos validados (Engenharia de Requisitos)
+- Modelo de domínio aprovado (Modelagem de Domínio)
+- Arquitetura definida (Arquitetura de Software)
+
+### **Saída para Próxima Fase**
+- Contrato para desenvolvimento Frontend (contra mocks)
+- Contrato para desenvolvimento Backend (implementação)
+- Types compartilhados entre FE e BE
+
+---
+
+## 📚 Estrutura de Recursos
+
+### **Templates** (`resources/templates/`)
+- `contrato-api.md` - Template de documentação
+- `api-endpoints.md` - Template de endpoints
+- `api-types.md` - Template de types/DTOs
+
+### **Examples** (`resources/examples/`)
+- REST API completa (CRUD)
+- GraphQL API
+- WebSocket API
+- gRPC API
+
+### **Checklists** (`resources/checklists/`)
+- Validação OpenAPI (100+ pontos)
+- Critérios de qualidade
+- Score mínimo de 75/100
+
+### **Reference** (`resources/reference/`)
+- OpenAPI 3.0 specification
+- Contract-first development
+- API design patterns
+- Versionamento semântico
+
+---
+
+## 🤖 Funções MCP
+
+1. **init_api_contract** - Inicializar contrato OpenAPI
+2. **validate_api_contract** - Validar schema e gerar score
+3. **process_api_contract** - Gerar types, DTOs e mocks
+
+Ver `MCP_INTEGRATION.md` para detalhes.
+
+---
+
+## 🎓 Skills Complementares
+
+- `api-patterns` - Padrões de API
+- `documentation-templates` - Templates de documentação
+- `testing-patterns` - Testes de contrato
+- `typescript-patterns` - Padrões TypeScript
+
+---
+
+**Versão:** 2.0  
+**Framework:** Skills Modernas com Progressive Disclosure  
+**Arquitetura:** Skill Descritiva + Automação MCP

package/dist/content/skills/specialist-contrato-api/SKILL.md

@@ -0,0 +1,317 @@
+---
+name: specialist-contrato-api
+description: Definição de OpenAPI, mocks, types e versionamento.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# Contrato de API · Skill do Especialista
+
+## Missão
+Especificar contrato frontend-first com OpenAPI, mocks e tipagens, garantindo que frontend e backend compartilhem a mesma fonte de verdade.
+
+## Quando ativar
+- Fase: Fase 9 · Execução
+- Workflows recomendados: /implementar-historia, /refatorar-codigo
+- Use quando precisar antes de desenvolvimento FE/BE para sincronizar interfaces.
+
+## Inputs obrigatórios
+- Requisitos (`docs/02-requisitos/requisitos.md`)
+- Modelo de Domínio (`docs/04-modelo/modelo-dominio.md`)
+- Arquitetura (`docs/06-arquitetura/arquitetura.md`)
+- Casos de uso críticos
+- Stack tecnológica definida
+
+## Outputs gerados
+- `docs/09-api/contrato-api.md` — contrato completo
+- OpenAPI/Swagger YAML validado
+- Types gerados para frontend e backend
+- Mock server configurado
+- Documentação interativa
+
+## Quality Gate
+- OpenAPI válido (sem erros de lint)
+- Todos os endpoints documentados
+- Exemplos de request/response
+- Types gerados para frontend
+- Types gerados para backend
+- Mock server funcionando
+- Versionamento definido
+
+## Fluxo de Criação de Contrato
+
+### Ordem de Execução Obrigatória
+
+| # | Bloco | Descrição | Validação |
+|---|-------|-----------|-----------|
+| 1 | **Schema** | Definir OpenAPI/GraphQL | Lint válido |
+| 2 | **Types Frontend** | Gerar tipos TypeScript | Sem erros TS |
+| 3 | **Types Backend** | Gerar DTOs | Sem erros TS |
+| 4 | **Mock Server** | Configurar MSW/json-server | Mock respondendo |
+
+### Fluxo Visual
+```
+┌─────────┐   ┌───────────┐   ┌──────────┐   ┌─────────────┐
+│ Schema  │ → │ Types FE  │ → │ Types BE │ → │ Mock Server │
+└────┬────┘   └─────┬─────┘   └────┬─────┘   └──────┬──────┘
+     │              │               │                 │
+     ▼              ▼               ▼                 ▼
+[lint]       [no errors]     [no errors]     [responding]
+     ✓              ✓               ✓                 ✓
+```
+
+## Prompts por Bloco
+
+### Bloco 1: Definir Schema OpenAPI
+```text
+Com base nos requisitos e modelo de domínio:
+[COLE REQUISITOS E MODELO]
+
+Gere um contrato OpenAPI 3.0 para a feature [NOME]:
+- Endpoints necessários (GET, POST, PUT, DELETE)
+- Request bodies com validações
+- Response schemas
+- Códigos de erro (400, 401, 404, 500)
+- Exemplos de request/response
+
+Formato: YAML válido
+```
+
+### Bloco 2: Gerar Types Frontend
+```text
+Com base neste OpenAPI:
+[COLE OPENAPI]
+
+Gere types TypeScript para o frontend:
+- Interfaces para request/response
+- Tipos para parâmetros
+- Enums se necessário
+
+Formato compatível com fetch/axios.
+```
+
+### Bloco 3: Gerar DTOs Backend
+```text
+Com base neste OpenAPI:
+[COLE OPENAPI]
+
+Gere DTOs para backend [STACK]:
+- CreateXxxDto
+- UpdateXxxDto
+- XxxResponseDto
+- Validações (class-validator ou equivalente)
+```
+
+### Bloco 4: Configurar Mock Server
+```text
+Com base neste OpenAPI:
+[COLE OPENAPI]
+
+Configure mock server usando [MSW/json-server/Prism]:
+- Respostas mockadas para cada endpoint
+- Dados de exemplo realistas
+- Simulação de delays e erros
+```
+
+## Ferramentas Recomendadas
+
+| Ferramenta | Uso | Stack |
+|------------|-----|-------|
+| **swagger-cli** | Validar OpenAPI | Todas |
+| **openapi-typescript** | Gerar types frontend | TypeScript |
+| **MSW** | Mock Service Worker | Browser + Node |
+| **json-server** | Mock API rápido | Desenvolvimento |
+| **Prism** | Mock server OpenAPI | Produção |
+| **orval** | Gerar clients TypeScript | React/Vue |
+| **swagger-codegen** | Gerar SDKs | Java/C#/Python |
+
+## Estrutura do Contrato OpenAPI
+
+### Seções Obrigatórias
+1. **Info**
+   - Title, version, description
+   - Contact e license
+   - Servers (dev, staging, prod)
+
+2. **Paths**
+   - Todos os endpoints com verbos HTTP
+   - Parâmetros (path, query, header)
+   - Request bodies com schemas
+   - Responses com status codes
+
+3. **Components**
+   - Schemas reutilizáveis
+   - Parameters comuns
+   - Responses padrão
+   - Security schemes
+
+4. **Security**
+   - Autenticação (JWT, API Key, OAuth)
+   - Autorização por scopes
+   - Rate limiting
+
+5. **Examples**
+   - Request/response examples
+   - Mock data realista
+   - Error cases
+
+## Guardrails Críticos
+
+### NUNCA Faça
+- **NUNCA** pule validação do OpenAPI
+- **NUNCA** use exemplos genéricos
+- **NUNCA** ignore códigos de erro
+- **NUNCA** quebre backward compatibility
+
+### SEMPRE Faça
+- **SEMPRE** versione o contrato com o código
+- **SEMPRE** use exemplos realistas nos mocks
+- **SEMPRE** defina todos os códigos de erro
+- **SEMPRE** mantenha backward compatibility
+
+### Versionamento Obrigatório
+```yaml
+# Versionamento Semântico
+version: 1.0.0  # Major.Minor.Patch
+
+# Major: Breaking changes
+# Minor: New features (backward compatible)
+# Patch: Bug fixes (backward compatible)
+
+# Exemplo de evolução:
+# 1.0.0 → 1.1.0 (novo endpoint)
+# 1.1.0 → 2.0.0 (campo obrigatório removido)
+```
+
+## Context Flow
+
+### Artefatos Obrigatórios para Iniciar
+Cole no início:
+1. Requisitos com endpoints necessários
+2. Modelo de domínio com entidades
+3. Arquitetura com stack definida
+4. Casos de uso críticos
+
+### Prompt de Continuação
+```
+Atue como Arquiteto de API Sênior.
+
+Requisitos:
+[COLE docs/02-requisitos/requisitos.md]
+
+Modelo de Domínio:
+[COLE docs/04-modelo/modelo-dominio.md]
+
+Arquitetura:
+[COLE docs/06-arquitetura/arquitetura.md]
+
+Preciso definir o contrato OpenAPI para sincronizar frontend e backend.
+```
+
+### Ao Concluir Esta Fase
+1. **Valide o OpenAPI** com swagger-cli
+2. **Gere os types** para frontend e backend
+3. **Configure o mock server**
+4. **Teste o contrato** com exemplos
+5. **Documente o versionamento**
+6. **Salve os artefatos** nos caminhos corretos
+
+## Métricas de Qualidade
+
+### Indicadores Obrigatórios
+- **Schema Validation:** 100% sem erros
+- **Coverage:** Todos os endpoints documentados
+- **Examples:** 100% com exemplos
+- **Types Generation:** Sem erros TS
+- **Mock Response Time:** < 100ms
+
+### Metas de Excelência
+- Schema Validation: 100%
+- Documentation Coverage: 100%
+- Mock Accuracy: ≥ 95%
+- Developer Experience: Score ≥ 9/10
+
+## Templates Prontos
+
+### Estrutura OpenAPI Básica
+```yaml
+openapi: 3.0.0
+info:
+  title: API do Projeto
+  version: 1.0.0
+  description: API para [descrição]
+servers:
+  - url: http://localhost:3000/api/v1
+    description: Development
+  - url: https://api.projeto.com/v1
+    description: Production
+
+paths:
+  /users:
+    get:
+      summary: Listar usuários
+      responses:
+        '200':
+          description: Lista de usuários
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/User'
+```
+
+### TypeScript Frontend
+```typescript
+// Generated types
+export interface User {
+  id: string;
+  name: string;
+  email: string;
+  createdAt: string;
+}
+
+export interface CreateUserRequest {
+  name: string;
+  email: string;
+}
+
+export interface ApiResponse<T> {
+  data: T;
+  message?: string;
+}
+```
+
+### DTO Backend (NestJS)
+```typescript
+import { IsEmail, IsString, MinLength } from 'class-validator';
+
+export class CreateUserDto {
+  @IsString()
+  @MinLength(3)
+  name: string;
+
+  @IsEmail()
+  email: string;
+}
+
+export class UserResponseDto {
+  id: string;
+  name: string;
+  email: string;
+  createdAt: Date;
+}
+```
+
+## Skills complementares
+- `api-patterns`
+- `documentation-templates`
+- `testing-patterns`
+- `typescript-patterns`
+
+## Referências essenciais
+- **Especialista original:** `content/specialists/Especialista em Contrato de API.md`
+- **Artefatos alvo:**
+  - `docs/09-api/contrato-api.md`
+  - OpenAPI/Swagger YAML validado
+  - Types gerados para frontend e backend
+  - Mock server configurado

package/dist/content/skills/specialist-contrato-api/mcp_functions/README.md

@@ -0,0 +1,17 @@
+# Funções MCP - Contrato de API
+
+**Versão:** 2.0
+
+Este diretório contém **referências** para implementação das funções MCP.
+
+## Funções
+
+1. **init_api_contract** - Inicializar contrato OpenAPI
+2. **validate_api_contract** - Validar schema e gerar score
+3. **process_api_contract** - Gerar types, DTOs e mocks
+
+Ver `MCP_INTEGRATION.md` para documentação completa.
+
+---
+
+**Arquitetura:** Skills Descritivas + Automação MCP

package/dist/content/skills/specialist-contrato-api/resources/checklists/api-validation.md

@@ -0,0 +1,44 @@
+# Checklist de Validação - Contrato de API
+
+**Score Mínimo:** 75/100 pontos
+
+---
+
+## Schema OpenAPI (30 pontos)
+
+- [ ] **[10 pts]** OpenAPI 3.0 válido (sem erros de lint)
+- [ ] **[8 pts]** Todos os endpoints documentados
+- [ ] **[6 pts]** Request/Response schemas definidos
+- [ ] **[4 pts]** Códigos de erro (400, 401, 404, 500)
+- [ ] **[2 pts]** Versionamento semântico
+
+## Types e DTOs (25 pontos)
+
+- [ ] **[10 pts]** Types TypeScript gerados sem erros
+- [ ] **[8 pts]** DTOs backend com validações
+- [ ] **[7 pts]** Enums e interfaces reutilizáveis
+
+## Mocks (20 pontos)
+
+- [ ] **[8 pts]** Mock server configurado
+- [ ] **[7 pts]** Dados de exemplo realistas
+- [ ] **[5 pts]** Response time < 100ms
+
+## Documentação (15 pontos)
+
+- [ ] **[8 pts]** Swagger UI funcionando
+- [ ] **[4 pts]** Exemplos de uso
+- [ ] **[3 pts]** Guia de versionamento
+
+## Backward Compatibility (10 pontos)
+
+- [ ] **[6 pts]** Breaking changes documentados
+- [ ] **[4 pts]** Estratégia de migração definida
+
+---
+
+**Thresholds:**
+- **>= 85:** ✅ Excelente
+- **75-84:** ✅ Bom
+- **70-74:** ⚠️ Aceitável (aprovação manual)
+- **< 70:** ❌ Bloqueado