@maestro-ai/mcp-server 1.2.0 → 2.1.0

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

@@ -0,0 +1,137 @@
+# Exemplos Práticos - Contrato de API
+
+## Exemplo 1: REST API Completa (CRUD de Usuários)
+
+**OpenAPI:**
+```yaml
+openapi: 3.0.0
+info:
+  title: Users API
+  version: 1.0.0
+paths:
+  /users:
+    get:
+      summary: List users
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/User'
+    post:
+      summary: Create user
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateUserDto'
+      responses:
+        '201':
+          description: Created
+components:
+  schemas:
+    User:
+      type: object
+      properties:
+        id: { type: string }
+        name: { type: string }
+        email: { type: string }
+    CreateUserDto:
+      type: object
+      required: [name, email]
+      properties:
+        name: { type: string }
+        email: { type: string, format: email }
+```
+
+**Types Gerados:**
+```typescript
+export interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+export interface CreateUserDto {
+  name: string;
+  email: string;
+}
+```
+
+---
+
+## Exemplo 2: GraphQL API
+
+**Schema:**
+```graphql
+type User {
+  id: ID!
+  name: String!
+  email: String!
+}
+
+type Query {
+  users: [User!]!
+  user(id: ID!): User
+}
+
+type Mutation {
+  createUser(input: CreateUserInput!): User!
+}
+
+input CreateUserInput {
+  name: String!
+  email: String!
+}
+```
+
+---
+
+## Exemplo 3: WebSocket API
+
+**Events:**
+```typescript
+// Client → Server
+interface ClientEvents {
+  'message:send': (data: { text: string }) => void;
+  'typing:start': () => void;
+}
+
+// Server → Client
+interface ServerEvents {
+  'message:received': (data: { id: string; text: string; from: string }) => void;
+  'user:typing': (data: { userId: string }) => void;
+}
+```
+
+---
+
+## Exemplo 4: gRPC API
+
+**Proto:**
+```protobuf
+syntax = "proto3";
+
+service UserService {
+  rpc GetUser (GetUserRequest) returns (User);
+  rpc CreateUser (CreateUserRequest) returns (User);
+}
+
+message User {
+  string id = 1;
+  string name = 2;
+  string email = 3;
+}
+
+message GetUserRequest {
+  string id = 1;
+}
+
+message CreateUserRequest {
+  string name = 1;
+  string email = 2;
+}
+```

package/dist/content/skills/specialist-contrato-api/resources/reference/api-guide.md

@@ -0,0 +1,96 @@
+# Guia Completo - Contrato de API
+
+## OpenAPI 3.0 Specification
+
+### Estrutura Básica
+```yaml
+openapi: 3.0.0
+info:
+  title: API Name
+  version: 1.0.0
+  description: API description
+servers:
+  - url: http://localhost:3000/api/v1
+paths:
+  /resource:
+    get:
+      summary: Get resources
+      responses:
+        '200':
+          description: Success
+components:
+  schemas:
+    Resource:
+      type: object
+      properties:
+        id: { type: string }
+```
+
+---
+
+## Contract-First Development
+
+### Benefícios
+1. Frontend e Backend trabalham em paralelo
+2. Mocks permitem desenvolvimento independente
+3. Validação antecipada de erros
+4. Documentação sempre atualizada
+
+### Fluxo
+```
+1. Definir Contrato OpenAPI
+2. Gerar Types (frontend)
+3. Gerar DTOs (backend)
+4. Criar Mocks
+5. Frontend desenvolve contra mocks
+6. Backend implementa contrato
+7. Integração
+```
+
+---
+
+## API Design Patterns
+
+### REST Best Practices
+- Use substantivos para recursos (`/users`, não `/getUsers`)
+- Verbos HTTP corretos (GET, POST, PUT, DELETE)
+- Status codes apropriados
+- Versionamento na URL (`/v1/users`)
+- Paginação, filtros e ordenação
+
+### Error Handling
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid email format",
+    "details": [
+      { "field": "email", "message": "Must be valid email" }
+    ]
+  }
+}
+```
+
+---
+
+## Versionamento Semântico
+
+**Formato:** MAJOR.MINOR.PATCH
+
+- **MAJOR:** Breaking changes
+- **MINOR:** New features (backward compatible)
+- **PATCH:** Bug fixes
+
+**Exemplo:**
+- 1.0.0 → 1.1.0: Novo endpoint (backward compatible)
+- 1.1.0 → 2.0.0: Campo obrigatório removido (breaking)
+
+---
+
+## Ferramentas
+
+- **swagger-cli:** Validar OpenAPI
+- **openapi-typescript:** Gerar types TS
+- **MSW:** Mock Service Worker
+- **Prism:** Mock server OpenAPI
+- **orval:** Gerar hooks React Query

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

@@ -0,0 +1,165 @@
+# Contrato de API - {{NOME_PROJETO}}
+
+**Versão:** {{VERSAO}}  
+**Data:** {{DATA}}  
+**Status:** 🔄 Em Desenvolvimento
+
+---
+
+## 📋 Informações Gerais
+
+### **API**
+- **Nome:** {{NOME_API}}
+- **Versão:** {{VERSAO_API}}
+- **Base URL:** {{BASE_URL}}
+- **Autenticação:** {{TIPO_AUTH}}
+
+### **Stack Técnica**
+- **Frontend:** {{STACK_FRONTEND}}
+- **Backend:** {{STACK_BACKEND}}
+- **Banco de Dados:** {{BANCO_DADOS}}
+
+### **Regra Frontend-First**
+- **Contrato validado** antes de qualquer implementação FE/BE
+- **Mocks obrigatórios** gerados a partir deste contrato
+- **Frontend** deve consumir **somente** mocks do contrato
+- **Backend** deve seguir **exatamente** o contrato (alterações → versionamento)
+
+---
+
+## 🔌 Endpoints
+
+### **{{RECURSO_1}}**
+
+#### **GET /api/{{RECURSO_1}}**
+**Descrição:** {{DESCRICAO_GET}}
+
+**Query Parameters:**
+- `page` (number, opcional): Página (default: 1)
+- `limit` (number, opcional): Itens por página (default: 10)
+- `search` (string, opcional): Busca
+
+**Response 200:**
+```json
+{
+  "data": [
+    {
+      "id": "{{ID}}",
+      "{{CAMPO_1}}": "{{VALOR_1}}",
+      "{{CAMPO_2}}": "{{VALOR_2}}",
+      "createdAt": "2026-01-31T22:00:00Z"
+    }
+  ],
+  "meta": {
+    "total": 100,
+    "page": 1,
+    "limit": 10
+  }
+}
+```
+
+#### **POST /api/{{RECURSO_1}}**
+**Descrição:** {{DESCRICAO_POST}}
+
+**Request Body:**
+```json
+{
+  "{{CAMPO_1}}": "{{VALOR_1}}",
+  "{{CAMPO_2}}": "{{VALOR_2}}"
+}
+```
+
+**Response 201:**
+```json
+{
+  "id": "{{ID}}",
+  "{{CAMPO_1}}": "{{VALOR_1}}",
+  "{{CAMPO_2}}": "{{VALOR_2}}",
+  "createdAt": "2026-01-31T22:00:00Z"
+}
+```
+
+**Errors:**
+- `400 Bad Request`: Dados inválidos
+- `401 Unauthorized`: Não autenticado
+- `409 Conflict`: Recurso já existe
+
+---
+
+## 📦 Schemas
+
+### **{{SCHEMA_1}}**
+```typescript
+interface {{SCHEMA_1}} {
+  id: string;
+  {{CAMPO_1}}: string;
+  {{CAMPO_2}}: number;
+  createdAt: string;
+  updatedAt: string;
+}
+```
+
+### **Create{{SCHEMA_1}}Dto**
+```typescript
+interface Create{{SCHEMA_1}}Dto {
+  {{CAMPO_1}}: string;  // Required
+  {{CAMPO_2}}: number;  // Required
+}
+```
+
+---
+
+## 🔐 Autenticação
+
+**Tipo:** {{TIPO_AUTH}}
+
+**Header:**
+```
+Authorization: Bearer {{TOKEN}}
+```
+
+**Scopes:**
+- `read:{{RECURSO}}`: Leitura
+- `write:{{RECURSO}}`: Escrita
+- `delete:{{RECURSO}}`: Exclusão
+
+---
+
+## 🎯 Versionamento
+
+**Estratégia:** Versionamento Semântico (SemVer)
+
+- **Major (X.0.0):** Breaking changes
+- **Minor (0.X.0):** Novas features (backward compatible)
+- **Patch (0.0.X):** Bug fixes
+
+**Versão Atual:** {{VERSAO_API}}
+
+---
+
+## 🧪 Mocks
+
+### **MSW Handlers**
+```typescript
+// mocks/handlers/{{RECURSO}}.ts
+export const {{RECURSO}}Handlers = [
+  rest.get('/api/{{RECURSO}}', (req, res, ctx) => {
+    return res(ctx.json({
+      data: [/* mock data */],
+      meta: { total: 10, page: 1, limit: 10 }
+    }));
+  }),
+  
+  rest.post('/api/{{RECURSO}}', (req, res, ctx) => {
+    return res(ctx.status(201), ctx.json({
+      id: 'mock-id',
+      ...req.body,
+      createdAt: new Date().toISOString()
+    }));
+  }),
+];
+```
+
+---
+
+**Próxima Ação:** Gerar types e implementar endpoints