@maestro-ai/mcp-server 1.2.0 → 2.1.0

package/dist/content/prompts/apis/idempotencia.md

@@ -1,254 +0,0 @@
-# Prompt: Idempotência em APIs
-
-> **Prioridade**: 🔴 CRÍTICA  
-> **Aplicável a**: Projetos Nível 2 (Médio) e Nível 3 (Complexo)
-
----
-
-## Por que é Crítico?
-
-Sem idempotência, operações podem ser duplicadas em caso de:
-- Retry automático de clientes
-- Timeout de rede seguido de retry manual
-- Falha de conexão após processamento
-
-**Consequências em produção:**
-- Cobranças duplicadas em pagamentos
-- Pedidos duplicados em e-commerce
-- Criação de recursos duplicados
-- Inconsistência de dados
-
----
-
-## Conceito
-
-> **Idempotência**: Uma operação que pode ser executada múltiplas vezes produzindo o mesmo resultado.
-
-| Método HTTP | Naturalmente Idempotente? |
-|-------------|---------------------------|
-| GET | ✅ Sim |
-| PUT | ✅ Sim (substitui recurso) |
-| DELETE | ✅ Sim (recurso já deletado = ok) |
-| POST | ❌ **Não** - Requer implementação |
-| PATCH | ⚠️ Depende da implementação |
-
----
-
-## Prompt Base
-
-```text
-Atue como arquiteto de APIs com foco em resiliência.
-
-Preciso implementar idempotência no seguinte endpoint:
-- Método: [POST/PATCH]
-- Rota: [ex: /api/v1/payments]
-- Operação: [ex: criar pagamento, processar pedido]
-
-Stack: [ex: Node.js + Express + Redis / Java + Spring + PostgreSQL]
-
-Gere uma implementação completa com:
-
-1. **Estratégia de Idempotency Key**
-   - Via header `Idempotency-Key`
-   - Formato: UUID v4
-   - Validação de formato
-
-2. **Armazenamento de Estado**
-   - Schema para Redis ou tabela em banco
-   - Estados: PROCESSING, COMPLETED, FAILED
-   - TTL apropriado (mínimo 24h)
-
-3. **Fluxo de Processamento**
-   - Verificar se key já existe
-   - Se PROCESSING: retornar 409 Conflict
-   - Se COMPLETED: retornar resposta cacheada
-   - Se nova: processar e armazenar resultado
-
-4. **Middleware/Interceptor**
-   - Código reutilizável para decorar endpoints
-
-5. **Testes**
-   - Request normal (200)
-   - Request duplicada (resposta cached)
-   - Request durante processamento (409)
-   - Request com key inválida (400)
-
-Inclua:
-- Código completo e comentado
-- Schema de armazenamento
-- Exemplos de uso
-```
-
----
-
-## Padrões Obrigatórios
-
-### Header Padrão
-
-```http
-POST /api/v1/orders HTTP/1.1
-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
-Content-Type: application/json
-
-{
-  "product_id": "123",
-  "quantity": 1
-}
-```
-
-### Respostas
-
-| Cenário | Status Code | Body |
-|---------|-------------|------|
-| Primeira execução com sucesso | 200/201 | Recurso criado |
-| Key já processada com sucesso | 200/201 | Resposta cacheada (idêntica) |
-| Key em processamento | 409 Conflict | `{"error": "Request already in progress"}` |
-| Key inválida/ausente | 400 Bad Request | `{"error": "Invalid Idempotency-Key"}` |
-| Primeira execução com erro | 4xx/5xx | Erro original (cachear também) |
-
-### Schema Redis
-
-```plaintext
-Key: idempotency:{idempotency_key}
-TTL: 86400 (24 horas)
-Value: {
-  "status": "PROCESSING" | "COMPLETED" | "FAILED",
-  "response_code": 201,
-  "response_body": {...},
-  "created_at": "2024-01-01T00:00:00Z"
-}
-```
-
-### Schema SQL (Alternativa)
-
-```sql
-CREATE TABLE idempotency_keys (
-    key VARCHAR(36) PRIMARY KEY,
-    status VARCHAR(20) NOT NULL DEFAULT 'PROCESSING',
-    response_code INT,
-    response_body JSONB,
-    created_at TIMESTAMP DEFAULT NOW(),
-    updated_at TIMESTAMP DEFAULT NOW()
-);
-
-CREATE INDEX idx_idempotency_created ON idempotency_keys(created_at);
-
--- Job para limpar keys antigas (> 24h)
-DELETE FROM idempotency_keys WHERE created_at < NOW() - INTERVAL '24 hours';
-```
-
----
-
-## Exemplo de Implementação (Node.js + Express + Redis)
-
-```typescript
-import { Redis } from 'ioredis';
-import { Request, Response, NextFunction } from 'express';
-
-const redis = new Redis();
-const TTL_SECONDS = 86400; // 24 horas
-
-interface IdempotencyRecord {
-  status: 'PROCESSING' | 'COMPLETED' | 'FAILED';
-  responseCode?: number;
-  responseBody?: any;
-  createdAt: string;
-}
-
-export function idempotent() {
-  return async (req: Request, res: Response, next: NextFunction) => {
-    const idempotencyKey = req.headers['idempotency-key'] as string;
-
-    // Validar presença e formato
-    if (!idempotencyKey) {
-      return res.status(400).json({ error: 'Idempotency-Key header required' });
-    }
-
-    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-    if (!uuidRegex.test(idempotencyKey)) {
-      return res.status(400).json({ error: 'Invalid Idempotency-Key format' });
-    }
-
-    const redisKey = `idempotency:${idempotencyKey}`;
-
-    // Verificar se já existe
-    const existing = await redis.get(redisKey);
-    
-    if (existing) {
-      const record: IdempotencyRecord = JSON.parse(existing);
-      
-      if (record.status === 'PROCESSING') {
-        return res.status(409).json({ 
-          error: 'Request already in progress',
-          idempotency_key: idempotencyKey
-        });
-      }
-      
-      // Retornar resposta cacheada
-      return res.status(record.responseCode!).json(record.responseBody);
-    }
-
-    // Marcar como em processamento
-    const processingRecord: IdempotencyRecord = {
-      status: 'PROCESSING',
-      createdAt: new Date().toISOString()
-    };
-    
-    await redis.setex(redisKey, TTL_SECONDS, JSON.stringify(processingRecord));
-
-    // Interceptar a resposta para cachear
-    const originalJson = res.json.bind(res);
-    res.json = (body: any) => {
-      const completedRecord: IdempotencyRecord = {
-        status: res.statusCode >= 400 ? 'FAILED' : 'COMPLETED',
-        responseCode: res.statusCode,
-        responseBody: body,
-        createdAt: processingRecord.createdAt
-      };
-      
-      redis.setex(redisKey, TTL_SECONDS, JSON.stringify(completedRecord));
-      
-      return originalJson(body);
-    };
-
-    next();
-  };
-}
-
-// Uso no router
-app.post('/api/v1/orders', idempotent(), createOrderHandler);
-```
-
----
-
-## Prompt para Revisar Idempotência Existente
-
-```text
-Tenho este endpoint que realiza operações que não podem ser duplicadas:
-[COLE O CÓDIGO DO ENDPOINT]
-
-Analise:
-1. O endpoint é idempotente? Se não, por quê?
-2. Quais operações podem causar problemas se duplicadas?
-3. Sugira como adicionar idempotência mantendo compatibilidade.
-```
-
----
-
-## Checklist de Implementação
-
-- [ ] Header `Idempotency-Key` definido
-- [ ] Validação de formato (UUID v4)
-- [ ] Armazenamento de estado configurado (Redis/DB)
-- [ ] TTL mínimo de 24 horas
-- [ ] Tratamento de requisição em andamento (409)
-- [ ] Cache de resposta para requests duplicadas
-- [ ] Testes automatizados cobrindo todos os cenários
-- [ ] Documentação na OpenAPI/Swagger
-
----
-
-## Referências
-
-- [Stripe - Idempotent Requests](https://stripe.com/docs/api/idempotent_requests)
-- [Idempotency Patterns](https://blog.bitsrc.io/design-patterns-for-microservices-idempotency/)

package/dist/content/prompts/apis/versionamento.md

@@ -1,313 +0,0 @@
-# Prompt: Versionamento de APIs
-
-> **Prioridade**: 🟠 ALTA  
-> **Aplicável a**: APIs públicas, integrações com terceiros, sistemas com múltiplos clientes
-
----
-
-## Por que Versionar?
-
-- **Breaking changes** sem quebrar clientes existentes
-- **Deprecação gradual** de funcionalidades
-- **Múltiplas versões** em produção simultaneamente
-- **Contratos estáveis** para integradores
-
----
-
-## Estratégias de Versionamento
-
-| Estratégia | Exemplo | Prós | Contras |
-|------------|---------|------|---------|
-| **URL Path** | `/v1/users` | Simples, cache-friendly | Mudança de URL |
-| **Query Param** | `/users?version=1` | Fácil de adicionar | Menos RESTful |
-| **Header** | `Accept: application/vnd.api.v1+json` | Não polui URL | Menos visível |
-| **Content Negotiation** | `Accept: application/vnd.company.v2+json` | Padrão HTTP | Mais complexo |
-
----
-
-## Prompt Base: Estratégia de Versionamento
-
-```text
-Atue como arquiteto de APIs.
-
-Estou criando uma API com as seguintes características:
-- Tipo: [REST/GraphQL]
-- Clientes: [internos/externos/públicos]
-- Frequência de breaking changes esperada: [alta/média/baixa]
-- Suporte simultâneo de versões: [ex. 2 versões, 6 meses]
-
-Recomende uma estratégia de versionamento considerando:
-
-1. **Mecanismo de Versão**
-   - URL path, header, query param, ou híbrido
-   - Justificativa para o contexto
-
-2. **Política de Deprecação**
-   - Quanto tempo uma versão é suportada?
-   - Como comunicar deprecação aos clientes?
-   - Headers de deprecação
-
-3. **O que constitui uma nova versão?**
-   - Breaking vs non-breaking changes
-   - Quando incrementar major/minor
-
-4. **Implementação**
-   - Estrutura de código para múltiplas versões
-   - Como compartilhar lógica entre versões
-   - Testes por versão
-
-5. **Documentação**
-   - OpenAPI por versão ou unificado?
-   - Changelog entre versões
-```
-
----
-
-## Prompt: Implementar Versionamento
-
-```text
-Tenho uma API existente que precisa de versionamento:
-[COLE ESTRUTURA DE ENDPOINTS ATUAL]
-
-Stack: [ex. Node.js + Express / Java + Spring]
-
-Estratégia escolhida: [URL Path / Header / etc]
-
-Gere:
-1. Middleware/interceptor para roteamento de versões
-2. Estrutura de pastas para organizar versões
-3. Exemplo de endpoint com v1 e v2
-4. Headers de deprecação (Sunset, Deprecation)
-5. Testes para verificar compatibilidade
-```
-
----
-
-## Prompt: Migrar de v1 para v2
-
-```text
-Tenho esta API v1:
-[COLE ENDPOINTS E SCHEMAS]
-
-Preciso criar v2 com estas mudanças:
-[DESCREVA BREAKING CHANGES]
-
-Gere:
-1. API v2 com as mudanças
-2. Estratégia de migração para clientes
-3. Período de dual-support recomendado
-4. Guia de migração para documentação
-5. Headers para comunicar deprecação de v1
-```
-
----
-
-## Headers de Deprecação (RFC 8594)
-
-```http
-HTTP/1.1 200 OK
-Deprecation: @1735689600
-Sunset: Sat, 01 Jan 2025 00:00:00 GMT
-Link: <https://api.example.com/docs/v2>; rel="successor-version"
-```
-
-| Header | Significado |
-|--------|-------------|
-| `Deprecation` | Timestamp Unix de quando foi marcado como deprecated |
-| `Sunset` | Data após a qual não será mais disponível |
-| `Link: rel="successor-version"` | Link para nova versão |
-
----
-
-## Exemplo: Versionamento por URL (Node.js + Express)
-
-```typescript
-// src/app.ts
-import express from 'express';
-import v1Router from './routes/v1';
-import v2Router from './routes/v2';
-
-const app = express();
-
-// Versionamento por URL
-app.use('/api/v1', v1Router);
-app.use('/api/v2', v2Router);
-
-// Fallback para versão padrão
-app.use('/api', (req, res, next) => {
-  res.redirect(301, `/api/v2${req.path}`);
-});
-```
-
-```typescript
-// src/routes/v1/users.ts
-router.get('/', async (req, res) => {
-  const users = await userService.getAll();
-  
-  // v1: resposta com formato antigo
-  res.json({
-    data: users.map(u => ({
-      id: u.id,
-      name: u.full_name, // v1 usa "name"
-      email: u.email
-    }))
-  });
-});
-```
-
-```typescript
-// src/routes/v2/users.ts
-router.get('/', async (req, res) => {
-  const users = await userService.getAll();
-  
-  // v2: resposta com novo formato
-  res.json({
-    data: users.map(u => ({
-      id: u.id,
-      full_name: u.full_name, // v2 usa "full_name"
-      email: u.email,
-      profile: u.profile // v2 adiciona profile
-    })),
-    meta: {
-      total: users.length,
-      version: 'v2'
-    }
-  });
-});
-```
-
----
-
-## Exemplo: Versionamento por Header
-
-```typescript
-// src/middleware/versioning.ts
-const VERSION_HEADER = 'X-API-Version';
-const DEFAULT_VERSION = '2';
-
-export function versionRouter(req, res, next) {
-  const version = req.headers[VERSION_HEADER.toLowerCase()] || DEFAULT_VERSION;
-  
-  // Anexar versão ao request
-  req.apiVersion = version;
-  
-  // Adicionar headers de resposta
-  res.setHeader(VERSION_HEADER, version);
-  
-  if (version === '1') {
-    res.setHeader('Deprecation', '@1704067200');
-    res.setHeader('Sunset', 'Mon, 01 Jul 2024 00:00:00 GMT');
-  }
-  
-  next();
-}
-
-// No controller
-export function getUsers(req, res) {
-  const users = userService.getAll();
-  
-  if (req.apiVersion === '1') {
-    return res.json(formatV1(users));
-  }
-  
-  return res.json(formatV2(users));
-}
-```
-
----
-
-## Política de Breaking Changes
-
-### O que é Breaking Change?
-
-| Tipo de Mudança | Breaking? | Ação |
-|-----------------|-----------|------|
-| Remover endpoint | ✅ Sim | Nova versão major |
-| Remover campo da resposta | ✅ Sim | Nova versão major |
-| Renomear campo | ✅ Sim | Nova versão major |
-| Alterar tipo de campo | ✅ Sim | Nova versão major |
-| Adicionar campo obrigatório no request | ✅ Sim | Nova versão major |
-| Adicionar campo opcional na resposta | ❌ Não | Versão atual |
-| Adicionar endpoint | ❌ Não | Versão atual |
-| Adicionar campo opcional no request | ❌ Não | Versão atual |
-
-### Exemplo de Política
-
-```markdown
-## Política de Versionamento - API [NOME]
-
-### Versões Suportadas
-- Máximo de 2 versões major em produção
-- Versão deprecated tem suporte por 6 meses após lançamento da próxima
-- Versão sunset é comunicada com 3 meses de antecedência
-
-### Comunicação
-- Changelog público em /docs/changelog
-- Email para clientes cadastrados em mudanças major
-- Headers Deprecation e Sunset em respostas
-
-### SLA de Deprecação
-1. Anúncio: -6 meses do sunset
-2. Deprecation header: -3 meses do sunset
-3. Sunset: remoção completa
-```
-
----
-
-## Documentação Multi-Versão
-
-### OpenAPI por Versão
-
-```yaml
-# openapi-v1.yaml
-openapi: 3.0.0
-info:
-  title: API v1 (Deprecated)
-  version: 1.0.0
-  x-deprecation-date: 2024-01-01
-
-# openapi-v2.yaml
-openapi: 3.0.0
-info:
-  title: API v2 (Current)
-  version: 2.0.0
-```
-
-### Changelog
-
-```markdown
-# Changelog
-
-## v2.0.0 (2024-01-15)
-
-### Breaking Changes
-- `GET /users`: Campo `name` renomeado para `full_name`
-- `POST /users`: Campo `profile_url` agora é obrigatório
-
-### Migração de v1 para v2
-1. Substituir `name` por `full_name` em todas as requisições
-2. Adicionar `profile_url` ao criar usuários
-
-## v1.0.0 (2023-06-01)
-- Release inicial
-```
-
----
-
-## Checklist
-
-- [ ] Estratégia de versionamento definida e documentada
-- [ ] Política de breaking changes clara
-- [ ] Headers de deprecação implementados
-- [ ] Documentação separada por versão
-- [ ] Changelog atualizado
-- [ ] Testes para todas as versões ativas
-- [ ] Roteamento de versões testado
-
----
-
-## Referências
-
-- [RFC 8594 - The Sunset HTTP Header](https://tools.ietf.org/html/rfc8594)
-- [API Versioning Best Practices](https://www.mnot.net/blog/2012/12/04/api-evolution)
-- [Stripe API Versioning](https://stripe.com/docs/api/versioning)