Gandalf MCP Server

O Gandalf MCP é um servidor Model Context Protocol (MCP) que conecta o Claude Code CLI ao Gandalf. Funciona como uma ponte bidirecional — permitindo que você crie tarefas, consulte specs, atualize contexto e dispare gerações de artefatos, tudo de dentro do Claude Code sem sair do terminal.

O MCP roda localmente no seu computador como um processo stdio. Ele traduz chamadas MCP para requests HTTP à Internal API do Gandalf — sem lógica de negócio própria, é um adapter fino.

Por que MCP? O protocolo MCP permite que o Claude Code descubra automaticamente as capabilities do Gandalf. Cada tool tem descrições em linguagem natural — você fala naturalmente ("qual a spec da feature X?") e o Claude mapeia para a tool correta.

Pré-requisitos

• Node.js 18+ (o MCP usa fetch nativo)
• Claude Code CLI instalado e configurado
• Acesso à Internal API do Gandalf (URL + token de autenticação)

Configuração

1. Obter credenciais

Você precisa de:

• URL da API — endereço da Internal API do Gandalf (ex: https://gandalf.example.com ou http://localhost:3001)
• Token de autenticação — bearer token para a API (peça ao admin do Gandalf)

2. Configurar o .mcp.json

Adicione a configuração do Gandalf MCP no arquivo .mcp.json do Claude Code (na raiz do seu projeto ou no diretório home):

{
  "mcpServers": {
    "gandalf": {
      "command": "npx",
      "args": ["gandalf-mcp"],
      "env": {
        "GANDALF_API_URL": "https://gandalf.example.com",
        "GANDALF_API_TOKEN": "seu-token-aqui",
        "GANDALF_PROJECT": "meu-projeto"
      }
    }
  }
}

3. Reiniciar o Claude Code

Após salvar o .mcp.json, reinicie o Claude Code para que ele detecte o novo MCP server. As tools do Gandalf estarão disponíveis automaticamente.

Variáveis de ambiente

| Variável | Obrigatória | Descrição | |----------|:-----------:|-----------| | GANDALF_API_URL | ✅ | URL base da Internal API do Gandalf (ex: https://gandalf.example.com ou http://localhost:3001) | | GANDALF_API_TOKEN | ✅ | Bearer token para autenticação na Internal API | | GANDALF_PROJECT | ❌ | Projeto default — evita ter que informar o projeto em toda chamada. Quando não definido, o MCP tenta auto-detectar o projeto a partir do diretório atual (CWD) comparando com local_path, git remote origin e nome do diretório. | | GANDALF_MCP_LOG_LEVEL | ❌ | Nível de log: debug, info (default), warn, error |

Nota: Se GANDALF_API_URL ou GANDALF_API_TOKEN não estiverem definidas, o server falha no startup com uma mensagem de erro indicando o que está faltando.

Tools disponíveis

Features

| Tool | Descrição | |------|-----------| | create_feature | Cria uma nova feature (tarefa) no Gandalf. Aceita nome, descrição, prioridade e feature relacionada. | | list_features | Lista features de um projeto com filtro opcional por stage e arquivadas. | | get_feature_status | Consulta o status atual de uma feature — stage, se está rodando, pausada ou com erro. | | update_feature | Atualiza nome, descrição ou prioridade de uma feature. |

Artefatos (leitura)

| Tool | Descrição | |------|-----------| | get_spec | Busca a especificação (spec) de uma feature. | | get_discovery_report | Busca o relatório de discovery — viabilidade técnica e análise inicial. | | get_queue | Busca a fila de tarefas de implementação. | | get_qa_report | Busca o relatório de QA. | | get_decisions_log | Busca o log de decisões — registro cronológico de tudo que aconteceu. | | get_risk_assessment | Busca a avaliação de risco. | | get_coherence_report | Busca o relatório de coerência entre artefatos. |

Chat-context

| Tool | Descrição | |------|-----------| | get_chat_context | Busca o chat-context (notas e contexto acumulado) de uma feature. | | update_chat_context | Atualiza o chat-context. O fluxo recomendado: ler o atual, avaliar o que manter/adicionar, e enviar a versão consolidada. |

Protótipos

| Tool | Descrição | |------|-----------| | get_prototype | Consulta o manifest do protótipo — lista de telas com status de aprovação. | | download_prototype_screen | Baixa o HTML de uma tela específica do protótipo. | | regenerate_prototype_screen | Re-gera uma tela do protótipo com novas instruções (assíncrono). |

Geração de artefatos

| Tool | Descrição | |------|-----------| | generate_artifact | Dispara a geração de um artefato (discovery, spec, prototype, risk, resources, human-tasks, coherence-review). A geração é assíncrona — retorna confirmação de início. | | get_ai_status | Verifica se há uma geração AI ativa para a feature. |

Links entre features

| Tool | Descrição | |------|-----------| | create_feature_link | Cria uma relação entre duas features: blocks, depends_on ou related_to. | | get_feature_links | Lista todos os links de uma feature (ambas as direções). |

Exemplos de uso

Uma vez configurado, você pode interagir com o Gandalf naturalmente no Claude Code:

• "Cria uma tarefa para corrigir o bug de login" → create_feature
• "Quais são as tarefas em implementação no projeto X?" → list_features
• "Mostra a spec da feature f-abc123" → get_spec
• "Qual o status da feature X?" → get_feature_status
• "Salva essas decisões no contexto da feature" → update_chat_context
• "Gera o discovery da feature X" → generate_artifact
• "A geração terminou?" → get_ai_status

Troubleshooting

"Variáveis de ambiente obrigatórias ausentes"

O MCP não conseguiu encontrar GANDALF_API_URL e/ou GANDALF_API_TOKEN. Verifique:

• O .mcp.json está no local correto (raiz do projeto ou ~/.mcp.json)
• As variáveis estão dentro da chave "env" na configuração do server
• Não há erros de digitação nos nomes das variáveis

"API do Gandalf inacessível"

O MCP não conseguiu se conectar à Internal API. Verifique:

• A URL em GANDALF_API_URL está correta e acessível da sua máquina
• O Gandalf está rodando (teste com curl $GANDALF_API_URL/api/health)
• Se a API está atrás de VPN/firewall, verifique sua conexão de rede

"Token de autenticação inválido ou expirado"

O bearer token foi rejeitado pela API. Verifique:

• O valor de GANDALF_API_TOKEN está correto
• O token não expirou (peça um novo ao admin se necessário)

Tools não aparecem no Claude Code

• Reinicie o Claude Code após modificar o .mcp.json
• Verifique se o JSON está válido (sem vírgulas extras, aspas corretas)
• Confirme que npx gandalf-mcp roda sem erros: GANDALF_API_URL=http://localhost:3001 GANDALF_API_TOKEN=test npx gandalf-mcp

Logs de debug

Para ver logs detalhados das chamadas HTTP, defina o nível de log como debug:

{
  "mcpServers": {
    "gandalf": {
      "command": "npx",
      "args": ["gandalf-mcp"],
      "env": {
        "GANDALF_API_URL": "https://gandalf.example.com",
        "GANDALF_API_TOKEN": "seu-token-aqui",
        "GANDALF_MCP_LOG_LEVEL": "debug"
      }
    }
  }
}

Os logs são enviados para stderr (capturados pelo Claude Code) no formato:

[gandalf-mcp] GET /api/features/f-abc123/artifacts/spec → 200 (142ms)

Desenvolvimento

cd packages/mcp
npm install
npm test          # Rodar testes
npm run test:watch # Testes em modo watch

O pacote vive em packages/mcp/ no monorepo do Gandalf, mas é independente — tem seu próprio package.json e não importa módulos internos do Gandalf.