npm package: @justmpm/quest
Description: MCP Server for Quest management - task orchestration system for AI agents
Latest version: 0.3.0

# @justmpm/quest

MCP Server para gerenciamento de quests - sistema de orquestração de tarefas para agents AI.

## Instalação

```bash
npm install -g @justmpm/quest
```

## Configuração no Claude Desktop

Adicione ao seu `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "quest": {
      "command": "quest",
      "args": []
    }
  }
}
```

Ou com npx (sem instalar):
```json
{
  "mcpServers": {
    "quest": {
      "command": "npx",
      "args": ["-y", "@justmpm/quest"]
    }
  }
}
```

## Como Funciona

O sistema gerencia **conjuntos de quests** dentro de cada projeto:

```
meu-projeto/
└── .quests/
    ├── .quest-lock          # Indica o conjunto ativo
    ├── sprint-1/
    │   └── quests.json      # Todas as quests da sprint 1
    ├── bugfixes/
    │   └── quests.json      # Quests de bugfix
    └── default/
        └── quests.json      # Conjunto padrão
```

## Tools Disponíveis

### quest_create

Cria uma nova quest no sistema.

```json
{
  "subject": "[Grupo 1.1] Implementar autenticação JWT",
  "description": "## Objetivo\nImplementar...\n\n## Critérios\n- ...",
  "activeForm": "Implementando autenticação JWT",
  "set": "sprint-1"
}
```

### quest_update

Atualiza uma quest existente.

```json
{
  "id": "quest-001",
  "status": "in_progress",
  "addBlockedBy": ["quest-002", "quest-003"]
}
```

**Context Bridge - Adicionar contexto sem perder o original:**

```json
{
  "id": "quest-005",
  "newDescription": "Contexto do Grupo 1:\n- Arquivos criados: src/auth/login.ts\n- Decisões: Usar bcrypt para hash"
}
```

> 💡 O `newDescription` **adiciona** ao invés de substituir. O contexto original é preservado e o novo conteúdo é anexado com timestamp.

### quest_list

Lista as quests do conjunto ativo.

```json
{
  "available": true,
  "compact": false,
  "set": "sprint-1"
}
```

**Destaques automáticos:**
- ⏭️ **PRÓXIMA RECOMENDADA**: primeira quest disponível na ordem
- ⭐ **BRIDGE**: quest que desbloqueia o próximo grupo
- **Ordenação por ID**: quest-001, quest-002, etc. (sempre em ordem)

### quest_get

Mostra detalhes completos de uma quest.

```json
{
  "id": "quest-001",
  "set": "sprint-1"
}
```

### quest_switch_set

Muda o conjunto ativo de quests.

```json
{
  "name": "sprint-2",
  "create": true
}
```

### quest_list_sets

Lista todos os conjuntos de quests disponíveis.

```json
{}
```

## Mensagens Otimizadas para IA

Todas as mensagens de erro e respostas são projetadas para serem **100% acionáveis por agents AI**:

### Estrutura das Mensagens de Erro

```
❌ ERRO: [o que deu errado - claro e direto]

CAUSAS POSSÍVEIS:
1. [explicação do problema]
2. [outra possibilidade]

O QUE FAZER:
1. [passo para corrigir]
2. [próximo passo]

EXEMPLO CORRETO:
  [parâmetros corretos]

💡 DICA: [sugestão adicional]
```

### Exemplos de Mensagens

**Erro: Subject faltando no create**
```
❌ ERRO: "subject" é obrigatório para criar quest.

O QUE FAZER:
1. Adicione o parâmetro "subject" com um título claro e acionável
2. Inclua prefixo do grupo se aplicável

EXEMPLO CORRETO:
  subject="[Grupo 1.1] Implementar autenticação JWT"
  description="## Objetivo\n..."

DICA: Use [Grupo X.Y] para organizar quests relacionadas
```

**Erro: Quest bloqueada**
```
🚫 AÇÃO BLOQUEADA: Não é possível avançar "quest-003"

POR QUE:
Esta quest depende de outras que ainda não foram completadas.

BLOQUEADORES PENDENTES:
  • quest-001: Setup do projeto (pending)
  • quest-002: Configurar banco (in_progress)

O QUE FAZER:
1. Complete as quests listadas acima primeiro
2. Use: quest_update com id="<blocker-id>", status="completed"
3. Depois retorne a esta: quest_update com id="quest-003", status="in_progress"

💡 DICA: Use quest_list com available=true para ver quests prontas
```

## Validações Inteligentes

O servidor inclui validações que protegem contra erros comuns:

### ✅ Validação de IDs
- Verifica se todos os `addBlockedBy` existem antes de adicionar
- Retorna erro claro com lista de IDs válidos

### ✅ Detecção de Dependência Circular
- Impede criar bloqueios que causem deadlock (A→B→A)
- Retorna o ciclo detectado para fácil correção

### ✅ Validação de Bloqueios
- Impede avançar (`in_progress` ou `completed`) se houver bloqueios pendentes
- Lista os bloqueadores que precisam ser completados

### ✅ Conjunto Mais Recente
- Se não houver `.quest-lock`, usa o conjunto modificado mais recentemente
- Útil quando agent esquece de especificar `set`

## Workflow com Subagents

1. **Agent Principal** cria quests em um conjunto
2. **Subagent** (sem especificar `set`) automaticamente usa o conjunto do `.quest-lock`
3. **Bloqueios** são validados automaticamente
4. **Contexto completo** é retornado ao iniciar uma quest (`status: in_progress`)
5. **Context bridges** preservam o histórico completo das descrições

## Bridge Quests ⭐

Uma **bridge quest** é a última quest de um grupo que, ao ser completada, desbloqueia quests do próximo grupo.

### Identificação automática

Ao usar `quest_list` com `available=true`, bridge quests são marcadas com ⭐:

```
📋 Quests Disponíveis [grupo-1] (3)

⏭️ PRÓXIMA RECOMENDADA: quest-003 - Implementar auth ⭐ BRIDGE

⏳ quest-001: Setup inicial
⏳ quest-002: Configurar API  
⏳ quest-003: Implementar auth ⭐ BRIDGE
```

### Instruções especiais no `quest_get`

Ao visualizar uma bridge quest, você recebe instruções detalhadas:

```
# ⏳ quest-003: Implementar auth ⭐ QUEST BRIDGE

---
⚠️ ATENÇÃO: Esta é uma QUEST BRIDGE!

Ao completar esta quest, você desbloqueará 3 quest(s) do próximo grupo.

QUESTS QUE SERÃO DESBLOQUEADAS:
  • quest-004: Criar endpoints
  • quest-005: Testar integração
  • quest-006: Documentar API

📋 INSTRUÇÕES PARA BRIDGE:
1. Complete o trabalho desta quest normalmente
2. Ao finalizar, use newDescription para adicionar contexto às quests acima
3. Depois marque como completed
```

## Exemplo de Context Bridge

```javascript
// Grupo 1 completa e atualiza a bridge
{
  "id": "quest-005", // Bridge quest
  "newDescription": "## Contexto Transferido do Grupo 1\n\n**Arquivos criados:**\n- src/auth/login.ts\n- src/auth/jwt.ts\n\n**Decisões:**\n- Usar bcrypt para hash\n- JWT expira em 24h\n\n**Importante:** Revisar validação no frontend"
}
```

Resultado na descrição:
```markdown
## Objetivo
[original preservado]

## 📌 Atualização (2026-02-08 10:30:00)

## Contexto Transferido do Grupo 1
[novo contexto anexado]
```

## Funcionalidades

- ✅ Criar, atualizar, listar e ler quests
- ✅ **Ordenação automática por ID** (quest-001, quest-002, etc.)
- ✅ **Destaque da próxima recomendada** (⏭️) na lista
- ✅ **Detecção automática de bridge quests** (⭐)
- ✅ Instruções especiais para bridge quests no `quest_get`
- ✅ Lista de quests que serão desbloqueadas
- ✅ Sistema de bloqueios entre quests com validações
- ✅ Validação de dependências circulares
- ✅ Validação de IDs de bloqueadores
- ✅ Múltiplos conjuntos de quests por projeto
- ✅ Auto-detecção do conjunto ativo via `.quest-lock`
- ✅ Formato compacto para listas grandes
- ✅ Mensagens ricas com contexto completo
- ✅ Descrições com histórico preservado (context bridges)
- ✅ Mensagens de erro otimizadas para IA (sempre acionáveis)

## Desenvolvimento

```bash
# Clonar e instalar
git clone <repo>
cd quest-mcp
npm install

# Build
npm run build

# Dev mode
npm run dev
```

## Licença

MIT