@justmpm/quest

MCP Server para gerenciamento de quests - sistema de orquestração de tarefas para agents AI.

Instalação

npm install -g @justmpm/quest

Configuração no Claude Desktop

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "quest": {
      "command": "quest",
      "args": []
    }
  }
}

Ou com npx (sem instalar):

{
  "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.

{
  "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.

{
  "id": "quest-001",
  "status": "in_progress",
  "addBlockedBy": ["quest-002", "quest-003"]
}

Context Bridge - Adicionar contexto sem perder o original:

{
  "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.

{
  "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.

{
  "id": "quest-001",
  "set": "sprint-1"
}

quest_switch_set

Muda o conjunto ativo de quests.

{
  "name": "sprint-2",
  "create": true
}

quest_list_sets

Lista todos os conjuntos de quests disponíveis.

{}

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

// 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:

## 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

# Clonar e instalar
git clone <repo>
cd quest-mcp
npm install

# Build
npm run build

# Dev mode
npm run dev

Licença

MIT