# Guia de depuração do servidor MCP Este guia aborda técnicas de depuração específicas para servidores MCP (Protocolo de Contexto de Modelo) ao usar o SDK do Copilot. ## Sumário * [Diagnóstico Rápido](#quick-diagnostics) * [Testando servidores MCP de forma independente](#testing-mcp-servers-independently) * [Problemas comuns](#common-issues) * [Problemas específicos da plataforma](#platform-specific-issues) * [Depuração avançada](#advanced-debugging) ## Diagnóstico rápido ### Checklist 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/antivírus 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 # Windows (PowerShell) '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | C:\path\to\your\mcp-server.exe ``` **Resposta esperada:** ```json {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"your-server","version":"1.0"}}} ``` ### 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:** ```json {"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. **Causas & Soluções:** | Cause | Solução | | ---------------------------------- | --------------------------------------------------- | | Caminho de comando incorreto | Use o caminho absoluto: `/usr/local/bin/server` | | Falta permissão executável | Execute `chmod +x /path/to/server` | | Dependências ausentes | Verificar com `ldd` (Linux) ou executar manualmente | | Problemas no diretório de trabalho | Definir `cwd` em configuração | **Depurar 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. **Causas & Soluções:** 1. **Ferramentas não habilitadas na configuração:** ```typescript mcpServers: { "server": { // ... tools: ["*"], // Must be "*" or list of tool names }, } ``` 2. **O servidor não expõe ferramentas:** * Teste manualmente com a requisição `tools/list` * Verificar se o servidor implementa o método `tools/list` 3. **Falha no handshake de inicialização:** * O servidor deve responder a `initialize` corretamente * O servidor deve manipular `notifications/initialized` ### Ferramentas listadas, mas nunca chamadas **Sintomas:** As ferramentas aparecem em logs de depuração, mas o modelo não as usa. **Causas & Soluções:** 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" }); ``` 2. **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." } ``` 3. **Problemas de esquema de ferramenta:** * Garantir `inputSchema` que o esquema JSON seja válido * Os campos necessários devem estar na `required` matriz ### Erros de tempo limite **Sintomas:**`MCP tool call timed out` Erros. **Soluções**: 1. **Aumentar o tempo limite:** ```typescript mcpServers: { "slow-server": { // ... timeout: 300000, // 5 minutes }, } ``` 2. **Otimizar o desempenho do servidor:** * Adicionar registro em log de progresso para identificar gargalo * Considere operações assíncronas * Verificar se há bloqueio de E/S 3. **Para ferramentas de longa execução**, considere as respostas de streaming se houver suporte. ### JSON-RPC erros **Sintomas:** Erros de análise, erros de solicitação inválidos. **Causas comuns:** 1. **O servidor grava no stdout incorretamente:** * Saída de depuração sendo enviada para stdout em vez de stderr * Linhas adicionais ou espaço em branco ```typescript // Wrong - pollutes stdout console.log("Debug info"); // Correct - use stderr for debug console.error("Debug info"); ``` 2. **Problemas de codificação:** * Garantir a codificação UTF-8 * Sem BOM (Marca de ordem dos 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 #### .NET aplicativos/ferramentas de console ```csharp // Correct configuration for .NET exe ["my-dotnet-server"] = new McpStdioServerConfig { Command = @"C:\Tools\MyServer\MyServer.exe", // Full path with .exe Args = new List(), WorkingDirectory = @"C:\Tools\MyServer", // Set working directory Tools = new List { "*" }, } // For dotnet tool (DLL) ["my-dotnet-tool"] = new McpStdioServerConfig { Command = "dotnet", Args = new List { @"C:\Tools\MyTool\MyTool.dll" }, WorkingDirectory = @"C:\Tools\MyTool", Tools = new List { "*" }, } ``` #### Comandos npx ```csharp // Windows needs cmd /c for npx ["filesystem"] = new McpStdioServerConfig { Command = "cmd", Args = new List { "/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:\\allowed\\path" }, Tools = new List { "*" }, } ``` #### Problemas de caminho * Use strings 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 #### Antivírus/firewall Windows Defender ou outro AV pode bloquear: * Novos executáveis * Processos de comunicação via stdin/stdout **Solução:** Adicione exclusões para o executável do servidor MCP. ### macOS #### Bloqueio do gatekeeper ```bash # If the server is blocked xattr -d com.apple.quarantine /path/to/mcp-server ``` #### Caminhos do Homebrew ```typescript // GUI apps may not have /opt/homebrew in PATH mcpServers: { "my-server": { command: "/opt/homebrew/bin/node", // Full path args: ["/path/to/server.js"], }, } ``` ### Linux #### Problemas de permissão ```bash chmod +x /path/to/mcp-server ``` #### 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="./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 MCP Use a ferramenta oficial do MCP Inspector: ```bash npx @modelcontextprotocol/inspector /path/to/your/mcp-server ``` Isso fornece uma interface web para: * Enviar solicitações de teste * Exibir respostas * Inspecionar esquemas de ferramentas ### Incompatibilidades de versão do protocolo Verifique se o servidor dá suporte à versão de protocolo que o SDK usa: ```json // 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 pedir ajuda, colete: * [ ] Linguagem e versão do SDK * [ ] Versão da CLI (`copilot --version`) * [ ] Tipo de servidor MCP (Node.js, Python, .NET, Go, Rust e muito mais) * [ ] 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 ## Consulte também * [Usando servidores MCP com o SDK do GitHub Copilot](/pt/copilot/how-tos/copilot-sdk/features/mcp) - Configuração e instalação * [Guia de depuração](/pt/copilot/how-tos/copilot-sdk/troubleshooting/debugging) – Depuração em todo o SDK * [Especificação do MCP](https://modelcontextprotocol.io/) – documentos de protocolo oficiais