Select language: current language is Portuguese
Pesquisar ou perguntar ao Copilot
Abrir menu
Open Sidebar

Depurando servidores MCP no SDK do Copilot

Diagnosticar e corrigir problemas com servidores MCP integrados SDK do Copilot, incluindo falhas de inicialização do servidor, problemas de descoberta de ferramentas e erros de protocolo.

Quem pode usar esse recurso?

SDK do GitHub Copilot está disponível com todos os Copilot planos.

Neste artigo

Observação

SDK do Copilot está em versão prévia técnica no momento. A funcionalidade e a disponibilidade estão sujeitas a alterações.

Diagnóstico rápido

Lista de Verificação

Antes de mergulhar fundo, verifique estes conceitos básicos:

  • O executável do servidor MCP existe e é executável
  • O caminho do comando está correto (use caminhos absolutos quando estiver em dúvida)
  • As ferramentas estão habilitadas (tools: ["*"] ou nomes de ferramentas específicos)
  • O servidor implementa o protocolo MCP corretamente (responde a initialize)
  • Nenhum firewall ou antivírus está bloqueando o processo (Windows)

Habilitar o registro em log de depuração do MCP

Adicione variáveis de ambiente à configuração do servidor MCP:

TypeScript
mcpServers: {
  "my-server": {
    type: "local",
    command: "/path/to/server",
    args: [],
    env: {
      MCP_DEBUG: "1",
      DEBUG: "*",
      NODE_DEBUG: "mcp",  // For Node.js MCP servers
    },
  },
}

Testar servidores MCP de forma independente

Sempre teste seu servidor MCP fora do SDK primeiro.

Teste de protocolo manual

Enviar uma solicitação initialize por meio de stdin:

Bash
# Unix/macOS
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | /path/to/your/mcp-server

          **Resposta esperada:**

{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"your-server","version":"1.0"}}}

Para obter um exemplo do Windows PowerShell, consulte o Guia de Depuração do MCP Server no github/copilot-sdk repositório.

Lista de ferramentas de teste

Após a inicialização, solicite a lista de ferramentas:

Bash
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | /path/to/your/mcp-server

          **Resposta esperada:**

{"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"my_tool","description":"Does something","inputSchema":{...}}]}}

Script de teste interativo

Crie um script de teste para depurar interativamente o servidor MCP:

Bash
#!/bin/bash
# test-mcp.sh

SERVER="$1"

# Initialize
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

# Send initialized notification
echo '{"jsonrpc":"2.0","method":"notifications/initialized"}'

# List tools
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

# Keep stdin open
cat

Uso:

Bash
./test-mcp.sh | /path/to/mcp-server

Problemas comuns

Servidor não iniciado

          **Sintomas:** Nenhuma ferramenta é exibida, nenhum erro nos logs.
MotivoSolução
Caminho de comando incorretoUse o caminho absoluto: /usr/local/bin/server
Falta permissão executávelExecute chmod +x /path/to/server
Dependências ausentesVerificar com ldd (Linux) ou executar manualmente
Problemas de diretório de trabalhoDefinir cwd em configuração

Depure executando manualmente:

Bash
# Run exactly what the SDK would run
cd /expected/working/dir
/path/to/command arg1 arg2

O servidor é iniciado, mas as ferramentas não aparecem

          **Sintomas:** O processo do servidor é executado, mas nenhuma ferramenta está disponível.

1. Ferramentas não habilitadas na configuração:

TypeScript
mcpServers: {
  "server": {
    // ...
    tools: ["*"],  // Must be "*" or list of tool names
  },
}

  1.        **O servidor não expõe ferramentas:** Teste com uma solicitação `tools/list` manualmente. Verifique se o servidor implementa o `tools/list` método.

  2.        **Falha no handshake de inicialização:** O servidor deve responder `initialize` corretamente e manipular `notifications/initialized`.

Ferramentas listadas, mas nunca chamadas

          **Sintomas:** As ferramentas aparecem em logs de depuração, mas o modelo não as usa.

1. O prompt não precisa claramente da ferramenta:

TypeScript
// Too vague
await session.sendAndWait({ prompt: "What's the weather?" });

// Better—explicitly mentions capability
await session.sendAndWait({
  prompt: "Use the weather tool to get the current temperature in Seattle"
});

  1.        **Descrição da ferramenta não clara:**
    TypeScript
    // Bad—model doesn't know when to use it
{ name: "do_thing", description: "Does a thing" }

// Good—clear purpose
{ name: "get_weather", description: "Get current weather conditions for a city. Returns temperature, humidity, and conditions." }

  2.        **Problemas de esquema de ferramenta:** Verifique se `inputSchema` o esquema JSON é válido. Os campos necessários devem ser listados na `required` matriz.

Erros do tempo limite

          **Sintomas:**`MCP tool call timed out` Erros.

  1. Aumente o tempo limite:

    TypeScript
    mcpServers: {
  "slow-server": {
    // ...
    timeout: 300000,  // 5 minutes
  },
}

  2. Otimize o desempenho do servidor adicionando log de progresso para identificar o gargalo, considerando operações assíncronas e verificando se há bloqueio de E/S.

  3. Para ferramentas que funcionam por longos períodos, considere respostas contínuas se houver suporte.

JSON-RPC erros

          **Sintomas:** Erros de análise, erros de solicitação inválidos.

Causas comuns:

  1.        **O servidor grava incorretamente no stdout:** A saída de depuração está indo para stdout em vez de stderr, ou há novas linhas extras ou espaços em branco:
    TypeScript
    // Wrong—pollutes stdout
console.log("Debug info");

// Correct—use stderr for debug
console.error("Debug info");

  2.        **Problemas de codificação:** Verifique a codificação UTF-8 sem BOM (Marca de Ordem de Bytes).

  3.        **Enquadramento de mensagem:** Cada mensagem deve ser um objeto JSON completo, delimitado por nova linha (uma mensagem por linha).

Problemas específicos da plataforma

Windows

No Windows, o software antivírus ou firewall pode bloquear novos executáveis ou processos de comunicação por meio de stdin/stdout. Adicione exclusões para o executável do servidor MCP, se necessário.

Para obter exemplos de configuração específicos do Windows para aplicativos de console do .NET e comandos NPX, consulte o Guia de Depuração do Servidor MCP no repositório github/copilot-sdk.

          **Problemas de caminho:**
  • Use cadeias de caracteres brutas (@"C:\path") ou barras ("C:/path").
  • Evite espaços em caminhos quando possível.
  • Se forem necessários espaços, certifique-se do uso adequado de aspas.

macOS

  1.        **Bloqueio do gatekeeper:** Se o servidor estiver bloqueado:
    Bash
    xattr -d com.apple.quarantine /path/to/mcp-server

  2.        **Caminhos homebrew:** Os aplicativos de GUI podem não ter `/opt/homebrew` no PATH. Use o caminho completo:
    TypeScript
    mcpServers: {
  "my-server": {
    command: "/opt/homebrew/bin/node",  // Full path
    args: ["/path/to/server.js"],
  },
}

Linux

  1.        **Problemas de permissão:**
    Bash
    chmod +x /path/to/mcp-server

  2.        **Bibliotecas compartilhadas ausentes:**
    Bash
    # Check dependencies
ldd /path/to/mcp-server

# Install missing libraries
apt install libfoo  # Debian/Ubuntu
yum install libfoo  # RHEL/CentOS

Depuração avançada

Capturar todo o tráfego MCP

Crie um script wrapper para registrar em log toda a comunicação:

Bash
#!/bin/bash
# mcp-debug-wrapper.sh

LOG="/tmp/mcp-debug-$(date +%s).log"
ACTUAL_SERVER="$1"
shift

echo "=== MCP Debug Session ===" >> "$LOG"
echo "Server: $ACTUAL_SERVER" >> "$LOG"
echo "Args: $@" >> "$LOG"
echo "=========================" >> "$LOG"

# Tee stdin/stdout to log file
tee -a "$LOG" | "$ACTUAL_SERVER" "$@" 2>> "$LOG" | tee -a "$LOG"

Use-o:

TypeScript
mcpServers: {
  "debug-server": {
    command: "/path/to/mcp-debug-wrapper.sh",
    args: ["/actual/server/path", "arg1", "arg2"],
  },
}

Inspecionar com o Inspetor do MCP

Use a ferramenta oficial do MCP Inspector:

Bash
npx @modelcontextprotocol/inspector /path/to/your/mcp-server

Isso fornece uma interface do usuário da Web para enviar solicitações de teste, exibir respostas e inspecionar esquemas de ferramentas.

Incompatibilidades de versão do protocolo

Verifique se o servidor dá suporte à versão de protocolo que o SDK usa:

// In initialize response, check protocolVersion
{"result":{"protocolVersion":"2024-11-05",...}}

Se as versões não corresponderem, atualize a biblioteca do servidor MCP.

Lista de verificação de depuração

Ao abrir um problema ou solicitar ajuda sobre problemas do GitHub, colete:

  • Linguagem e versão do SDK
  • Versão da CLI (copilot --version)
  • Tipo de servidor MCP (Node.js, Python, .NET, Go e assim por diante)
  • Configuração completa do servidor MCP (ocultar segredos)
  • Resultado do teste manual initialize
  • Resultado do teste manual tools/list
  • Logs de depuração do SDK
  • Qualquer mensagem de erro
Morty Proxy This is a proxified and sanitized view of the page, visit original site.