clickbus-prompts

frafaelcb/clickbus-prompts

3.1

If you are the rightful owner of clickbus-prompts and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The ClickBus Prompts MCP Server is a NestJS and TypeScript-based server designed to store and organize development team prompts efficiently.

Tools
3
Resources
0
Prompts
0

ClickBus Prompts MCP Server

MCP Server desenvolvido com NestJS e TypeScript para armazenar e organizar prompts do time de desenvolvimento da ClickBus.

Funcionalidades

  • Armazenamento de Prompts: Organiza prompts por tipo e time
  • API MCP: Implementa o protocolo Model Context Protocol
  • Busca e Filtros: Permite buscar prompts por tipo, time ou ID
  • Arquitetura NestJS: Estrutura modular e escalável
  • Tipagem Completa: TypeScript com interfaces robustas e type safety
  • Validação de Dados: DTOs para validação de entrada
  • Tratamento de Erros: Sistema de erros tipados e informativos
  • Docker Ready: Pronto para execução em container

Estrutura dos Prompts

Cada prompt contém os seguintes metadados:

  • type: Categoria do prompt (ex: "Code Review", "Documentation", "Testing")
  • team: Time responsável (ex: "Global", "GDS")
  • description: Texto explicativo sobre o uso do prompt
  • content: Conteúdo completo do prompt (opcional)
  • id: Identificador único
  • createdAt / updatedAt: Timestamps de criação e atualização

Tools Disponíveis

list_prompts

Lista todos os prompts armazenados com opções de formatação e filtros.

Parâmetros:

  • format: Formato de retorno (grouped, flat, groups)
  • type: Filtrar por tipo específico (opcional)
  • team: Filtrar por time específico (opcional)

Exemplos:

{
  "name": "list_prompts",
  "arguments": {
    "format": "grouped"
  }
}

{
  "name": "list_prompts",
  "arguments": {
    "format": "flat",
    "type": "Code Review",
    "team": "GDS"
  }
}

get_prompt

Obtém um prompt específico pelo ID.

Parâmetros:

  • id: ID do prompt (obrigatório)

Exemplo:

{
  "name": "get_prompt",
  "arguments": {
    "id": "code-review-global-1"
  }
}

get_prompts_stats

Obtém estatísticas dos prompts (contadores por tipo e time).

Exemplo:

{
  "name": "get_prompts_stats",
  "arguments": {}
}

Instalação e Execução

Desenvolvimento Local

# Instalar dependências
npm install

# Executar em modo desenvolvimento (com watch)
npm run start:dev

# Executar em modo debug
npm run start:debug

# Compilar com NestJS
npm run build

# Executar versão compilada
npm run start:prod

# Executar testes
npm test

# Executar testes com coverage
npm run test:cov

# Executar testes específicos das MCP Tools
npm run test:mcp

# Executar testes E2E
npm run test:e2e

Docker

# Build da imagem
npm run docker:build

# Executar container
npm run docker:run

# Usar Docker Compose
npm run docker:up

# Parar Docker Compose
npm run docker:down

# Validar Dockerfile e build
./scripts/validate-docker.sh

# Executar testes no Docker
npm run test:mcp:docker

Docker Compose (Exemplo)

version: '3.8'
services:
  prompts-server:
    build: .
    container_name: clickbus-prompts-mcp
    restart: unless-stopped
    stdin_open: true
    tty: true

Exemplos de Prompts Incluídos

O servidor vem pré-configurado com exemplos de prompts:

  1. Code Review (Global): Prompt genérico para revisão de código
  2. Code Review (GDS): Prompt específico do time GDS
  3. Documentation (Global): Geração de documentação técnica
  4. Testing (GDS): Criação de testes unitários específicos do GDS
  5. Refactoring (Global): Sugestões de refatoração de código legado
  6. API Design (Global): Design e review de APIs REST
  7. Database Optimization (GDS): Otimização de queries e estrutura de banco

Arquitetura NestJS

src/
├── main.ts                           # Ponto de entrada da aplicação
├── app.module.ts                     # Módulo principal da aplicação
├── types/                            # Tipos globais
│   ├── global.types.ts              # Tipos utilitários globais
│   └── index.ts                     # Exportações de tipos
├── common/                           # Módulos compartilhados
│   └── interfaces/
│       ├── error.interface.ts       # Interfaces de erro tipadas
│       └── index.ts                 # Exportações comuns
├── prompts/                          # Módulo de prompts
│   ├── prompts.module.ts            # Módulo de prompts
│   ├── prompts.service.ts           # Service com lógica de negócio
│   ├── prompts.service.spec.ts      # Testes unitários
│   ├── interfaces/
│   │   └── prompt.interface.ts      # Interfaces e enums tipados
│   ├── dto/                         # Data Transfer Objects
│   │   ├── list-prompts.dto.ts      # DTO para listagem
│   │   ├── get-prompt.dto.ts        # DTO para busca por ID
│   │   └── index.ts                 # Exportações DTOs
│   └── data/
│       └── prompts.data.ts          # Dados tipados dos prompts
└── mcp/                             # Módulo MCP
    ├── mcp.module.ts                # Módulo MCP
    └── mcp-server.service.ts        # Service do servidor MCP tipado

Tipagem e Type Safety

O projeto utiliza TypeScript de forma robusta com:

Enums Tipados

export enum PromptType {
  CODE_REVIEW = 'Code Review',
  DOCUMENTATION = 'Documentation',
  TESTING = 'Testing',
  REFACTORING = 'Refactoring',
  API_DESIGN = 'API Design',
  DATABASE_OPTIMIZATION = 'Database Optimization',
}

export enum TeamType {
  GLOBAL = 'Global',
  GDS = 'GDS',
}

Interfaces Imutáveis

export interface Prompt {
  readonly id: string;
  readonly type: PromptType;
  readonly team: TeamType;
  readonly description: string;
  readonly content?: string;
  readonly createdAt: string;
  readonly updatedAt: string;
}

DTOs com Validação

export class ListPromptsDto {
  readonly format?: PromptFormat = 'grouped';
  readonly type?: string;
  readonly team?: string;

  static create(args: any): ListPromptsDto {
    return new ListPromptsDto({
      format: args?.format,
      type: args?.type,
      team: args?.team,
    });
  }

  isValidFormat(): boolean {
    return ['grouped', 'flat', 'groups'].includes(this.format || 'grouped');
  }
}

Tratamento de Erros Tipado

export class PromptNotFoundError extends Error {
  readonly code = 'PROMPT_NOT_FOUND';
  readonly timestamp: string;

  constructor(id: string) {
    super(`Prompt com ID '${id}' não encontrado`);
    this.name = 'PromptNotFoundError';
    this.timestamp = new Date().toISOString();
  }
}

Testes

O projeto inclui uma suíte completa de testes para garantir o funcionamento correto das MCP Tools:

Tipos de Testes

Testes Unitários
# Executar todos os testes unitários
npm test

# Executar com coverage
npm run test:cov

# Executar em modo watch
npm run test:watch
Testes E2E das MCP Tools
# Testes end-to-end específicos das tools MCP
npm run test:e2e
Testes Práticos das MCP Tools
# Script personalizado para testar todas as tools
npm run test:mcp

Cobertura de Testes

Os testes cobrem:

  • ✅ list_prompts: Todos os formatos (grouped, flat, groups) e filtros
  • ✅ get_prompt: IDs válidos, inválidos e ausentes
  • ✅ get_prompts_stats: Estrutura e consistência das estatísticas
  • ✅ Validação de entrada: DTOs e tratamento de erros
  • ✅ Consistência de dados: Entre service e MCP tools
  • ✅ Tratamento de erros: Códigos de erro e mensagens
  • ✅ Tipagem: Verificação de tipos em runtime

Testes no Docker

# Executar testes dentro do container Docker
npm run test:mcp:docker

# Validar build e funcionamento do Docker
./scripts/validate-docker.sh

Exemplo de Saída dos Testes

🚀 Iniciando testes das MCP Tools...

⏳ list_prompts (grouped)...
✅ list_prompts (grouped) - 45ms

⏳ list_prompts (flat)...
✅ list_prompts (flat) - 32ms

⏳ get_prompt (ID válido)...
✅ get_prompt (ID válido) - 28ms

📊 Resultados dos Testes:
============================================================
✅ Sucessos: 10
❌ Falhas: 0
⏱️  Tempo total: 285ms
📈 Taxa de sucesso: 100.0%

🎉 Todos os testes passaram!

Extensibilidade

O servidor foi projetado para ser facilmente extensível com NestJS:

  • Novos Prompts: Adicione em src/prompts/data/prompts.data.ts
  • Persistência: Injete um repositório no PromptsService para conexão com banco de dados
  • Novas Tools: Adicione handlers no McpServerService
  • Novos Módulos: Crie módulos NestJS para funcionalidades adicionais
  • Validações: Use decorators de validação do NestJS
  • Interceptors/Guards: Adicione middleware para autenticação e logging

Protocolo MCP

Este servidor implementa o Model Context Protocol, permitindo integração com diversos clientes MCP como Claude Desktop, Continue, e outros.

🚀 Deploy e Configuração

🎯 NOVA FUNCIONALIDADE: execute_prompt

Agora você pode executar prompts diretamente no chat do Cursor IDE!

  • 🚀 execute_prompt - Executa prompts como instruções prontas
  • 💡 Sem copy/paste - Prompt aparece formatado no chat
  • 🎯 Busca inteligente - Por ID, tipo, time ou combinação
  • 📋 Controle de contexto - Com ou sem cabeçalho

Exemplo: "Execute o prompt de code review" → Prompt pronto para usar! ✨

Guias Completos

  • - NOVA funcionalidade de execução
  • - Guia completo de deploy com Docker
  • - Como usar no Cursor IDE com exemplos
  • - Revisão técnica do Docker e testes

Scripts de Automação

# Deploy completo (build + start)
./scripts/deploy.sh

# Configurar Cursor IDE automaticamente  
./scripts/configure-cursor.sh

# Testar MCP tools
npm run test:mcp

# Validar Docker setup
./scripts/validate-docker.sh

Quick Start

# 1. Deploy da aplicação
./scripts/deploy.sh

# 2. Configurar Cursor IDE
./scripts/configure-cursor.sh

# 3. Reiniciar Cursor IDE

# 4. Testar: "Execute o prompt de code review" (NOVA funcionalidade!)

Licença

MIT