npm package: @komexa/kickoff-mcp
Description: MCP server — copilot de estrutura para vibe coders
Author: Komexa
Latest version: 0.1.2

# 🚀 Kickoff MCP — O Copilot de Estrutura para Vibe Coders

O `@komexa/kickoff-mcp` é um Servidor MCP (Model Context Protocol) e uma ferramenta de CLI desenhada para ajudar desenvolvedores a transformarem ideias em projetos estruturados em minutos. Ele atua como um **Arquiteto Lead e PM**, sintetizando requisitos em documentação técnica real (PRD, SAD, ERD) e garantindo que o seu código reflita o que foi planejado.

---

## ✨ Funcionalidades Principais

- **Kickoff Inteligente**: Uma entrevista guiada pela IA para definir identidade, stack técnica, funcionalidades e modelo de dados do seu projeto.
- **Geração de Documentação Automática**: Cria arquivos `PRD.md`, `SAD.md`, `REQUIREMENTS.md` e `ERD.md` (Mermaid) prontos para uso.
- **Rastreabilidade (REQ-ID)**: Sistema de indexação SQLite que vincula cada linha de código a um requisito de negócio.
- **Relatórios de Progresso**: Gere relatórios de cobertura para saber exatamente quanto do seu MVP já foi construído.
- **Dashboard Integrado**: Interface visual para gerenciar requisitos e progresso (em `./dist/dashboard`).

---

## 🛠️ Instalação

```bash
npm install -g @komexa/kickoff-mcp
```

### Usando como Servidor MCP (Claude Desktop)

Adicione a seguinte configuração ao seu `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "kickoff-mcp": {
      "command": "npx",
      "args": ["-y", "@komexa/kickoff-mcp"]
    }
  }
}
```

---

## 💻 Comandos CLI

Você também pode utilizar o `kickoff-mcp` diretamente no seu terminal:

- `kickoff-mcp start`: Inicia o processo de entrevista e geração de documentos.
- `kickoff-mcp add-feature <descrição>`: Registra uma nova funcionalidade no sistema e no SQLite.
- `kickoff-mcp validate <path>`: Verifica o codebase em busca de referências a requisitos (ex: `// REQ-001`).
- `kickoff-mcp report [format]`: Gera um relatório de progresso (formatos: `summary` ou `full`).
- `kickoff-mcp dashboard`: Inicia interface web para visualizar requisitos e progresso (porta 4242).
- `kickoff-mcp dev-context find <pattern>`: Busca soluções similares no histórico do projeto.
- `kickoff-mcp info`: Exibe informações sobre o projeto atual.

---

## 📖 Como funciona o Fluxo de Trabalho

1. **Definição**: Execute `kickoff-mcp start` para desenhar a arquitetura.
2. **Desenvolvimento**: Ao implementar uma funcionalidade, adicione um comentário no código: `// REQ-001`.
3. **Validação**: Rode `kickoff-mcp validate` para que o sistema reconheça a implementação.
4. **Monitoramento**: Use `kickoff-mcp report` para acompanhar o progresso do MVP.
5. **Dashboard**: Execute `kickoff-mcp dashboard` para visualizar progresso em interface web.

### 🔄 Trabalhando com Projetos Existentes

O kickoff-mcp detecta automaticamente projetos em desenvolvimento:

```bash
# Em um projeto já iniciado
cd /caminho/do/projeto-existente
kickoff-mcp start  # Detecta e oferece modo atualização
kickoff-mcp validate  # Mapeia features já implementadas
```

**Fluxo para projetos existentes:**
- ✅ **Preserva** REQ-IDs existentes
- 🔍 **Detecta** features sem rastreamento  
- ➕ **Adiciona** novos REQ-IDs para features não mapeadas
- 📝 **Atualiza** documentação incrementalmente

---

## 📊 Dashboard Visual

O kickoff-mcp inclui uma interface web para visualizar requisitos e progresso:

```bash
# Inicia o dashboard na porta 4242
kickoff-mcp dashboard

# Acesse no navegador
open http://localhost:4242
```

### Funcionalidades do Dashboard:
- **Visão geral** dos requisitos por status (coberto/parcial/pendente)
- **Timeline** de desenvolvimento por REQ-ID
- **Métricas** de progresso do MVP vs pós-lançamento
- **Histórico** de validações e mudanças

---

## 🧠 Integração com Ollama (Opcional)

Para melhorar a busca semântica e identificação automática de requisitos, você pode integrar o Ollama:

### 🚀 Setup Rápido

1. **Instale o Ollama**:
   ```bash
   # macOS/Linux
   curl -fsSL https://ollama.com/install.sh | sh
   
   # Windows: baixe de https://ollama.com/download
   ```

2. **Baixe um modelo de embeddings** (escolha por tamanho):
   ```bash
   # Modelo pequeno e rápido (23MB)
   ollama pull all-minilm
   
   # Modelo balanced (67MB) - RECOMENDADO
   ollama pull bge-small
   
   # Modelo padrão (274MB)
   ollama pull nomic-embed-text
   ```

3. **Configure as variáveis de ambiente**:
   
   Crie um arquivo `.env` na **raiz do seu projeto**:
   ```bash
   # .env (na raiz do seu projeto)
   KICKOFF_OLLAMA_URL=http://localhost:11434
   KICKOFF_OLLAMA_MODEL=bge-small
   ```
   
   **Importante**: Adicione o `.env` ao seu `.gitignore`:
   ```bash
   echo ".env" >> .gitignore
   ```

### 🎯 Modelos Recomendados por Cenário

| Cenário | Modelo | Tamanho | Comando |
|---------|---------|---------|---------|
| 💻 Laptop/desenvolvimento | `all-minilm` | 23MB | `ollama pull all-minilm` |
| 🖥️ Workstation | `bge-small` | 67MB | `ollama pull bge-small` |
| 🏢 Servidor/produção | `nomic-embed-text` | 274MB | `ollama pull nomic-embed-text` |

### 💡 Funcionalidades Habilitadas

- **Busca semântica inteligente** — `kickoff-mcp dev-context find` encontra soluções similares mesmo sem keywords exatas
- **Mapeamento automático** — Futuramente irá inferir REQ-IDs baseado no contexto do código
- **Fallback silencioso** — Se Ollama não estiver disponível, volta para busca textual normal

### ⚙️ Verificação

```bash
# Teste se o Ollama está funcionando
curl http://localhost:11434/api/tags

# Teste a busca semântica dentro de um projeto kickoff
kickoff-mcp dev-context find "autenticação usuário"

# Verifique se as variáveis estão sendo lidas
node -e "console.log('Ollama URL:', process.env.KICKOFF_OLLAMA_URL)"
```

---

## 📄 Licença

Distribuído sob a licença MIT. Veja a [LICENSE](./LICENSE) para mais informações.

---
Desenvolvido por **Komexa**. ✨