Guia de solução de problemas e tratamento de erros

Este guia ajuda você a diagnosticar e resolver problemas comuns na integração MCP do Priorize.me, com explicações detalhadas de erro e passos de resolução.

Referência rápida: problemas comuns

Mensagens de erro

Na inicialização

O servidor valida a configuração e a sessão antes de aceitar qualquer chamada. Se algo falha, ele encerra com código de saída 1 e escreve no stderr uma linha como:

{ "level": "error", "message": "Startup blocked", "meta": { "reason": "Session is invalid or expired" } }

A mensagem nunca inclui o conteúdo do arquivo, porque ele contém os tokens.

Nas chamadas de ferramenta

Erros de ferramenta voltam com isError: true e uma mensagem de texto.

Board not found or not accessible

O board não está em allowedBoardIds, não existe ou a sessão não tem acesso a ele. As três situações respondem igual de propósito, para não revelar se um board existe.

Para achar o UUID, abra o board no app: ele aparece na URL, depois de /boards/.

Permissão negada em escrita

Leitores não escrevem, e boards arquivados não aceitam escrita. A mensagem vem do banco; confira o seu papel no board e se ele está arquivado.

VERSION_CONFLICT: ...

A expectedVersion enviada não é mais a atual, ou a tarefa está arquivada. Nada foi gravado. Leia a tarefa de novo com list_tasks, confira se a mudança ainda faz sentido e envie a nova version com um requestId novo.

{
  "name": "list_tasks",
  "arguments": { "boardId": "550e8400-e29b-41d4-a716-446655440000", "status": "active" }
}

REQUEST_ID_REUSED: ...

O mesmo requestId já foi usado com argumentos diferentes, inclusive em outro board. Nada foi gravado. Gere um UUID novo por operação; reutilize-o só para repetir exatamente a mesma chamada depois de uma falha de rede.

Erros de validação

Argumento ausente, UUID inválido ou valor fora da lista (por exemplo, um quadrante que não seja um dos identificadores técnicos). Compare a chamada com a referência de ferramentas.

Problemas comuns e soluções

Problema 1: o servidor MCP não inicia

Sintomas:

• O processo encerra imediatamente
• Nenhuma saída ou mensagem de erro
• "Command failed" no cliente

Passos de diagnóstico:

# 1. Teste a configuração
MCP_LOCAL_CONFIG_PATH=/path/to/config.json \
  npx -y @priorize-me/mcp

# 2. Confira o código de saída
echo $?

# 3. Capture o stderr
MCP_LOCAL_CONFIG_PATH=/path/to/config.json \
  npx -y @priorize-me/mcp 2>&1 | head -20

Soluções comuns:

Variável de ambiente ausente:

export MCP_LOCAL_CONFIG_PATH="/absolute/path/to/config.json"

Arquivo de configuração inválido:

# Valide o JSON
jsonlint /path/to/config.json

Versão antiga no cache do npm:

# Força a versão mais recente publicada
MCP_LOCAL_CONFIG_PATH=/path/to/config.json npx -y @priorize-me/mcp@latest

Incompatibilidade de versão do Node.js:

# Confira a versão
node --version
# Precisa ser 24 ou mais recente

Problema 2: ferramentas indisponíveis

Sintomas:

• O cliente não mostra nenhuma ferramenta do Priorize.me
• Ferramentas específicas ausentes (de escrita)
• Mensagem "No tools available"

Diagnóstico:

1. Confira a configuração de allowWrites para as ferramentas de escrita
2. Verifique se a sessão tem permissões
3. Confira a descoberta de ferramentas do cliente
4. Teste com uma ferramenta básica (list_boards)

Ferramentas de escrita ausentes:

// Configuração que causa a ausência das ferramentas de escrita
{ "allowWrites": false }

// Configuração que habilita as ferramentas de escrita
{ "allowWrites": true }

Todas as ferramentas ausentes:

1. Sessão expirada → renove os tokens
2. Sem acesso a board → atualize o allowedBoardIds
3. Erro de configuração → valide o arquivo de configuração
4. Problema de rede → confira a conectividade com o Supabase

Problema 3: problemas de desempenho

Sintomas:

• Respostas lentas das ferramentas
• Alta latência
• Erros de timeout
• Desconexões do cliente

Passos de otimização:

1. Reduza o volume de tarefas

// Use paginação para boards grandes
const result = await mcpClient.callTool({
  name: "list_tasks",
  arguments: {
    boardId: boardId,
    cursor: cursor  // Páginas de 25 tarefas; repita enquanto nextCursor não for null
  }
});

2. Faça cache das informações de board

// Faz cache dos IDs de board para reduzir chamadas a list_boards
let cachedBoards = null;

async function getBoardsCached(mcpClient) {
  if (!cachedBoards) {
    const result = await mcpClient.callTool({
      name: "list_boards",
      arguments: {}
    });
    cachedBoards = JSON.parse(result.content[0].text).boards;
    
    // Invalida o cache após 5 minutos
    setTimeout(() => { cachedBoards = null; }, 5 * 60 * 1000);
  }
  return cachedBoards;
}

3. Operações em paralelo

// Processa boards em paralelo quando apropriado
async function processMultipleBoards(mcpClient, boardIds) {
  const promises = boardIds.map(boardId =>
    mcpClient.callTool({
      name: "list_tasks",
      arguments: { boardId, status: "active" }
    })
  );
  
  return Promise.all(promises);
}

4. Pool de conexões

Para múltiplas operações, mantenha uma conexão persistente em vez de reconectar a cada vez.

Problema 4: inconsistência de dados

Sintomas:

• Tarefas aparecem/desaparecem
• Mudanças de status não refletidas
• Operações duplicadas
• Histórico de atividade ausente

Causas e soluções:

1. Problemas de cache

Problema: cache do cliente fora de sincronia com o servidor Solução: implemente invalidação de cache ou TTL mais curto

2. Modificações concorrentes

Problema: múltiplos clientes modificando a mesma tarefa Solução: use expectedVersion e lógica de nova tentativa

3. Latência de rede

Problema: operações aplicadas fora de ordem Solução: implemente uma fila de operações no cliente

4. Violações de idempotência

Problema: a mesma operação é aplicada múltiplas vezes Solução: uso correto de requestId e checagens de idempotência

Técnicas de depuração

Depuração básica

1. Ative o log detalhado

# Define as variáveis de ambiente de depuração
export DEBUG=mcp-server:*
export NODE_ENV=development

MCP_LOCAL_CONFIG_PATH=/path/to/config.json \
  npx -y @priorize-me/mcp 2>&1 | tee mcp-debug.log

2. Teste com um cliente simples

cat > test-client.js << 'EOF'
import { Client } from '@modelcontextprotocol/client';
import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';

const client = new Client({ name: 'debug-client', version: '1.0.0' });

await client.connect(
  new StdioClientTransport({
    command: 'npx',
    args: ['-y', '@priorize-me/mcp'],
    env: { PATH: process.env.PATH, MCP_LOCAL_CONFIG_PATH: process.env.MCP_LOCAL_CONFIG_PATH }
  })
);

console.log('Conectado');
const tools = await client.listTools();
console.log('Ferramentas:', JSON.stringify(tools, null, 2));
await client.close();
EOF

MCP_LOCAL_CONFIG_PATH=/path/to/config.json node test-client.js

3. Verifique os recursos do sistema

# Monitora o processo do servidor MCP
ps aux | grep "priorize-me-mcp"

# Confere o uso de memória
top -p $(pgrep -f "priorize-me-mcp")

# Confere os descritores de arquivo
lsof -p $(pgrep -f "priorize-me-mcp")

Depuração avançada

1. Análise de tráfego de rede

# Monitora as chamadas à API do Supabase (se usando Supabase local)
sudo tcpdump -i lo port 5432 -A  # PostgreSQL
sudo tcpdump -i lo port 5433 -A  # API do Supabase

2. Análise de consultas do banco de dados

-- Confere a tabela mcp_request_log
SELECT * FROM mcp_request_log 
WHERE user_id = 'your-user-id'
ORDER BY created_at DESC 
LIMIT 10;

-- Confere as versões das tarefas
SELECT id, title, version, updated_at 
FROM tasks 
WHERE board_id IN ('your-board-ids')
ORDER BY updated_at DESC;

3. Profiling de desempenho

# Profiling de CPU
NODE_OPTIONS=--cpu-prof npx -y @priorize-me/mcp

# Profiling de memória
NODE_OPTIONS=--heap-prof npx -y @priorize-me/mcp

# Eventos de rastreamento
NODE_OPTIONS=--trace-events-enabled npx -y @priorize-me/mcp

Problemas específicos de cliente

Problemas do Claude Desktop

Problema: a configuração não carrega

Solução:

1. Feche o Claude Desktop completamente (não só a janela)
2. Apague a configuração corrompida e recrie
3. Confira as permissões do arquivo (deve ser legível pelo usuário)

Problema: ferramentas não aparecem

Solução:

1. Confira a versão do Claude Desktop (precisa ter suporte a MCP)
2. Veja o console em busca de erros: View → Developer → Show Console
3. Reinicie com um perfil limpo

Problemas do Cursor

Problema: timeout do servidor MCP

Solução:

1. Aumente o timeout nas configurações do Cursor
2. Confira a versão do Cursor quanto à compatibilidade com MCP
3. Teste com uma configuração mais simples

Problema: conflito de configuração de workspace

Solução:

1. Confira as configurações global e de workspace
2. Limpe o cache do Cursor: rm -rf ~/.cursor/cache
3. Reinicie o Cursor com estado limpo

Problemas de clientes personalizados

Problema: conformidade com JSON-RPC

Solução: implemente o protocolo JSON-RPC 2.0 de forma estrita:

// Formato correto de mensagem
const message = {
  jsonrpc: "2.0",
  id: 1,
  method: "tools/list",
  params: {}
};

// Campos obrigatórios: jsonrpc, id, method
// Opcional: params

Problema: gestão de conexão

Solução: implemente um ciclo de vida de conexão adequado:

class MCPConnection {
  constructor() {
    this.client = null;
    this.transport = null;
    this.reconnectAttempts = 0;
  }
  
  async connect(config) {
    try {
      this.client = new Client({ name: 'client', version: '1.0.0' });
      this.transport = new StdioClientTransport(config);
      await this.client.connect(this.transport);
      this.reconnectAttempts = 0;
    } catch (error) {
      this.reconnectAttempts++;
      if (this.reconnectAttempts < 3) {
        await this.delay(Math.pow(2, this.reconnectAttempts) * 100);
        return this.connect(config);
      }
      throw error;
    }
  }
  
  async delay(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
  }
}

Boas práticas de prevenção

1. Manutenção regular

• Rotacione os tokens de sessão regularmente
• Revise o allowedBoardIds periodicamente
• Atualize a configuração para boards que mudaram
• Limpe logs antigos de requestId, se implementados

2. Configuração de monitoramento

# Script simples de monitoramento
#!/bin/bash
CONFIG_PATH="/path/to/config.json"
LOG_FILE="/tmp/mcp-health.log"

# Testa a conexão
MCP_LOCAL_CONFIG_PATH="$CONFIG_PATH" \
  timeout 10 npx -y @priorize-me/mcp < /dev/null 2>&1

if [ $? -eq 0 ]; then
  echo "$(date): ✅ Servidor MCP saudável" >> "$LOG_FILE"
else
  echo "$(date): ❌ Falha no servidor MCP" >> "$LOG_FILE"
  # Envia alerta
fi

3. Backup de configuração

# Script de backup
#!/bin/bash
BACKUP_DIR="$HOME/.config/priorize-me/backups"
CONFIG_FILE="$HOME/.config/priorize-me/mcp-config.json"

mkdir -p "$BACKUP_DIR"
cp "$CONFIG_FILE" "$BACKUP_DIR/mcp-config-$(date +%Y%m%d-%H%M%S).json"

# Mantém os últimos 7 backups
ls -t "$BACKUP_DIR"/mcp-config-*.json | tail -n +8 | xargs rm -f

4. Documentação

• Documente sua configuração (sem segredos)
• Registre os passos de solução de problemas bem-sucedidos
• Compartilhe soluções com o time
• Atualize este guia com novos problemas encontrados

Obtendo ajuda

Se você já tentou todos os passos de solução de problemas e ainda tem dificuldades:

1. Confira a documentação: revise os guias de Instalação, Configuração e Segurança

2. Reúna informações:

   • Mensagens de erro (texto exato)
   • Configuração (com dados sensíveis removidos)
   • Passos para reproduzir
   • Versões do cliente e do servidor

3. Recursos da comunidade:

   • GitHub Discussions
   • Fórum da comunidade do Priorize.me
   • Comunidade do protocolo MCP

4. Suporte profissional:

   • Opções de suporte empresarial
   • Serviços de consultoria
   • Ajuda com integração personalizada

Próximos passos

Depois de resolver seu problema:

1. Teste a correção minuciosamente
2. Documente a solução para referência futura
3. Considere medidas de prevenção para evitar recorrência
4. Compartilhe o conhecimento com seu time ou a comunidade

Lembre-se: a maioria dos problemas de integração MCP é relacionada à configuração. Confira sua configuração antes de investigar problemas mais profundos.