Hexagon Architecture Generator - MCP Server

Um servidor MCP (Model Context Protocol) para gerar automaticamente estruturas seguindo a Arquitetura Hexagonal (Ports and Adapters) com NestJS e princípios de Clean Architecture.

📋 Características

• 🏗️ Arquitetura Hexagonal completa com inversão de dependências
• 🔄 3 Padrões de Use Cases:
  • Use Cases Internos (Banco de Dados)
  • Use Cases Externos via Duck Typing
  • Use Cases Externos via Adapter Pattern
• 🎯 NestJS Integration com Dependency Injection
• 📝 TypeScript com tipagem forte
• 🧪 Testes pré-configurados
• 📚 Documentação automática
• 🤖 MCP Server para integração com assistentes de IA

🚀 Instalação

npm install -g hexagon-architecture-generator

📖 Uso como Servidor MCP

Este projeto agora funciona como um servidor MCP (Model Context Protocol), permitindo que assistentes de IA utilizem as ferramentas de geração de código.

Configuração do MCP

1. Instalação:

npm install hexagon-architecture-generator

2. Configuração no cliente MCP:

{
  "mcpServers": {
    "hexagon-generator": {
      "command": "hexagon-mcp",
      "args": []
    }
  }
}

Ferramentas Disponíveis

generate_module

Gera um módulo completo seguindo arquitetura hexagonal.

Parâmetros:

• name (obrigatório): Nome do módulo
• type: Tipo de use case (internal, duck-typing, adapter)
• externalLib: Nome da biblioteca externa (para duck-typing e adapter)
• database: Tipo de banco (mysql, postgres) via Prisma
• output: Diretório de saída (padrão: ./src/modules)
• skipTests: Pular geração de testes (padrão: false)

generate_use_case

Gera um use case específico.

Parâmetros:

• name (obrigatório): Nome do use case
• type: Tipo de use case
• module: Nome do módulo (padrão: common)
• output: Diretório de saída
• skipTests: Pular geração de testes

generate_repository

Gera um repository com interface.

Parâmetros:

• name (obrigatório): Nome do repository
• database: Tipo de banco (Prisma)
• module: Nome do módulo
• output: Diretório de saída
• skipTests: Pular geração de testes

generate_adapter

Gera um adapter para biblioteca externa.

Parâmetros:

• name (obrigatório): Nome do adapter
• externalLib: Nome da biblioteca externa
• module: Nome do módulo
• output: Diretório de saída
• skipTests: Pular geração de testes

🏗️ Estrutura Gerada

src/
├── modules/
│   └── partners/
│       ├── interfaces/
│       │   ├── controllers/
│       │   │   └── partners.controller.interface.ts
│       │   ├── services/
│       │   │   └── partners.service.interface.ts
│       │   └── repositories/
│       │       └── partner.repository.interface.ts
│       ├── controllers/
│       │   └── partners.controller.ts
│       ├── services/
│       │   └── partners.service.ts
│       ├── use-cases/
│       │   ├── create-partner/
│       │   │   └── create-partner.use-case.ts
│       │   └── find-partner/
│       │       └── find-partner.use-case.ts
│       ├── repositories/
│       │   └── partner.repository.ts
│       ├── entities/
│       │   └── partner.entity.ts
│       ├── dtos/
│       │   ├── create-partner.dto.ts
│       │   └── partner.response.dto.ts
│       └── partners.module.ts

�️ Banco de Dados com Prisma

Os repositórios gerados usam Prisma Client. Após gerar um módulo, configure o Prisma no seu projeto:

1. Instalar deps (no seu app):

npm install prisma @prisma/client

2. Criar schema.prisma e modelos (o gerador inclui um exemplo no módulo):

• Ajuste o provider (mysql ou postgresql) e a variável DATABASE_URL

3. Rodar migrações e gerar client:

npx prisma migrate dev --name init
npx prisma generate

4. Use o PrismaService gerado no módulo para acessar o banco.

�🔧 Exemplos de Uso via MCP

Gerar módulo completo

Tool: generate_module
Arguments: {
  "name": "partners",
  "type": "internal",
  "database": "postgres",
  "output": "./src/modules"
}

Gerar módulo com integração externa

Tool: generate_module
Arguments: {
  "name": "quotation",
  "type": "adapter",
  "externalLib": "stilman-integration",
  "output": "./src/modules"
}

Gerar apenas um use case

Tool: generate_use_case
Arguments: {
  "name": "send-notification",
  "type": "duck-typing",
  "module": "notifications"
}

🏭 Desenvolvimento

📚 Exemplos de Código Gerado

Controller Interface

export interface IPartnersController {
  create(dto: CreatePartnerDto): Promise<PartnerResponseDto>;
  findById(id: string): Promise<PartnerResponseDto>;
  findAll(): Promise<PartnerResponseDto[]>;
  update(id: string, dto: UpdatePartnerDto): Promise<PartnerResponseDto>;
  delete(id: string): Promise<void>;
}

Use Case

@Injectable()
export class CreatePartnerUseCase {
  constructor(
    @Inject("IPartnerRepository")
    private readonly repository: IPartnerRepository
  ) {}

  async execute(data: CreatePartnerData): Promise<Partner> {
    const partner = Partner.create(data);
    return await this.repository.save(partner);
  }
}

NestJS Module

@Module({
  imports: [],
  controllers: [PartnersController],
  providers: [
    PartnersService,
    CreatePartnerUseCase,
    FindPartnerUseCase,
    {
      provide: "IPartnersService",
      useClass: PartnersService,
    },
    {
      provide: "IPartnerRepository",
      useClass: PartnerRepository,
    },
  ],
  exports: ["IPartnersService"],
})
export class PartnersModule {}

🎯 Padrões Suportados

1. Use Cases Internos (Banco de Dados)

Controller → Service → UseCase → Repository → Database

2. Duck Typing (Bibliotecas Compatíveis)

Controller → Service → UseCase → ExternalClient (direto)

3. Adapter Pattern (Bibliotecas Incompatíveis)

Controller → Service → UseCase → Adapter → ExternalClient

🧪 Testes

Os testes são gerados automaticamente seguindo as melhores práticas:

describe("CreatePartnerUseCase", () => {
  let useCase: CreatePartnerUseCase;
  let repository: jest.Mocked<IPartnerRepository>;

  beforeEach(() => {
    const mockRepository = {
      save: jest.fn(),
      findById: jest.fn(),
    };

    useCase = new CreatePartnerUseCase(mockRepository);
    repository = mockRepository;
  });

  it("should create a partner successfully", async () => {
    // Test implementation
  });
});

🏭 Desenvolvimento

Para contribuir com o projeto:

# Clonar o repositório
git clone <repository-url>
cd hexagon-mcp

# Instalar dependências
npm install

# Desenvolver
npm run dev

# Build
npm run build

# Testar como servidor MCP
npm start

Estrutura do Projeto

src/
├── index.ts              # Servidor MCP principal
├── types.ts              # Interfaces compartilhadas
├── generators/           # Geradores de código
│   ├── base.generator.ts
│   ├── module.generator.ts
│   ├── use-case.generator.ts
│   ├── repository.generator.ts
│   └── adapter.generator.ts
└── templates/           # Templates Handlebars
    ├── controllers/
    ├── services/
    ├── use-cases/
    ├── repositories/
    ├── entities/
    ├── dtos/
    ├── interfaces/
    └── modules/

• ✅ SOLID Principles
• ✅ Clean Architecture
• ✅ Domain-Driven Design
• ✅ Dependency Inversion
• ✅ Interface Segregation
• ✅ Repository Pattern
• ✅ Adapter Pattern

🔧 Integração com Assistentes de IA

Este servidor MCP pode ser integrado com assistentes de IA como:

• Claude Desktop
• Cursor IDE
• Outros clientes MCP

Para configurar, adicione a configuração do servidor MCP no seu cliente preferido:

{
  "mcpServers": {
    "hexagon-generator": {
      "command": "hexagon-mcp",
      "args": []
    }
  }
}

🤝 Contribuindo

Contribuições são bem-vindas! Por favor, leia o CONTRIBUTING.md para detalhes.

📄 Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.