# Guía de depuración del servidor MCP Esta guía abarca técnicas de depuración específicas de los servidores MCP (Model Context Protocol) cuando se utiliza el SDK de Copilot. ## Tabla de contenido * [Diagnóstico rápido](#quick-diagnostics) * [Probar servidores MCP de forma independiente](#testing-mcp-servers-independently) * [Problemas comunes](#common-issues) * [Problemas específicos de la plataforma](#platform-specific-issues) * [Depuración avanzada](#advanced-debugging) ## Diagnóstico rápido ### Checklist Antes de profundizar, compruebe estos aspectos básicos: * [ ] El ejecutable del servidor MCP existe y se puede ejecutar. * [ ] La ruta de acceso del comando es correcta (use rutas de acceso absolutas cuando tenga dudas) * [ ] Las herramientas están habilitadas (`tools: ["*"]` o nombres de herramientas específicos) * [ ] El servidor implementa correctamente el protocolo MCP (responde a `initialize`) * [ ] No hay firewall o antivirus que bloquee el proceso (Windows) ### Habilite el registro de depuración MCP Agregue variables de entorno a la configuración del 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 }, }, } ``` ## Prueba de servidores MCP de forma independiente Pruebe siempre el servidor MCP fuera del SDK en primer lugar. ### Prueba manual del protocolo Envíe una `initialize` solicitud a través 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 ``` **Respuesta esperada:** ```json {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"your-server","version":"1.0"}}} ``` ### Lista de herramientas de prueba Después de la inicialización, solicite la lista de herramientas: ```bash echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | /path/to/your/mcp-server ``` **Respuesta esperada:** ```json {"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"my_tool","description":"Does something","inputSchema":{...}}]}} ``` ### Script de prueba interactiva Cree un script de prueba para depurar interactivamente el 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 comunes ### El servidor no se inicia **Síntomas:** No aparece ninguna herramienta, no hay errores en los registros. **Causas y soluciones:** | Causa | Solución | | ----------------------------------- | ----------------------------------------------------------- | | Ruta de comando incorrecta | Utilice la ruta de acceso absoluta: `/usr/local/bin/server` | | Falta el permiso ejecutable | Ejecute `chmod +x /path/to/server`: | | Dependencias faltantes | Comprobación con `ldd` (Linux) o ejecución manual | | Problemas del directorio de trabajo | Establecer `cwd` en la configuración | **Para depurar, ejecute manualmente:** ```bash # Run exactly what the SDK would run cd /expected/working/dir /path/to/command arg1 arg2 ``` ### El servidor se inicia, pero las herramientas no aparecen **Síntomas:** El proceso de servidor se ejecuta, pero no hay herramientas disponibles. **Causas y soluciones:** 1. **Herramientas no habilitadas en la configuración:** ```typescript mcpServers: { "server": { // ... tools: ["*"], // Must be "*" or list of tool names }, } ``` 2. **El servidor no expone herramientas:** * Prueba manualmente con la solicitud `tools/list` * Comprobar que el servidor implementa el método `tools/list` 3. **Error en el protocolo de enlace de inicialización:** * El servidor debe responder correctamente a `initialize` * El servidor debe gestionar `notifications/initialized` ### Herramientas enumeradas pero nunca llamadas **Síntomas:** Las herramientas aparecen en los registros de depuración, pero el modelo no los usa. **Causas y soluciones:** 1. **Prompt no necesita claramente la herramienta:** ```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. **Descripción de la herramienta no 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 herramientas:** * Asegúrese de que `inputSchema` es un esquema JSON válido * Los campos obligatorios deben estar en el array `required` ### Errores de tiempo de espera **Síntomas:**`MCP tool call timed out` errores. **Soluciones**: 1. **Aumento del tiempo de espera:** ```typescript mcpServers: { "slow-server": { // ... timeout: 300000, // 5 minutes }, } ``` 2. **Optimizar el rendimiento del servidor:** * Agregar el registro del progreso para identificar el cuello de botella * Tener en cuenta las operaciones asíncronas * Compruebe si hay operaciones de E/S que bloquean el sistema 3. **Para herramientas de ejecución prolongada**, considere transmitir respuestas en streaming si es compatible. ### errores de JSON-RPC **Síntomas:** Errores de análisis, errores de solicitud no válidos. **Causas comunes:** 1. **El servidor escribe en stdout incorrectamente:** * Salida de depuración dirigida a stdout en lugar de stderr * Nuevas líneas adicionales o espacios en blanco ```typescript // Wrong - pollutes stdout console.log("Debug info"); // Correct - use stderr for debug console.error("Debug info"); ``` 2. **Problemas de codificación:** * Asegurar la codificación UTF-8 * Sin BOM (marca de orden de bytes) 3. **Trama de mensajes:** * Cada mensaje debe ser un objeto JSON completo. * Delimitado por nueva línea (un mensaje por línea) ## Problemas específicos de la plataforma ### Windows #### aplicaciones o herramientas de consola de .NET ```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 ruta * Usar cadenas sin formato (`@"C:\path"`) o barras diagonales (`"C:/path"`) * Evitar espacios en rutas siempre que sea posible * Si se requieren espacios, asegúrese de que las comillas sean adecuadas #### Antivirus o firewall Windows Defender u otro antivirus pueden bloquear: * Nuevos ejecutables * Procesos que se comunican a través de stdin/stdout **Solución:** Agregue exclusiones para el ejecutable del servidor MCP. ### macOS #### Bloqueo del controlador de acceso ```bash # If the server is blocked xattr -d com.apple.quarantine /path/to/mcp-server ``` #### Rutas de acceso de 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 permisos ```bash chmod +x /path/to/mcp-server ``` #### Faltan bibliotecas compartidas ```bash # Check dependencies ldd /path/to/mcp-server # Install missing libraries apt install libfoo # Debian/Ubuntu yum install libfoo # RHEL/CentOS ``` ## Depuración avanzada ### Captura todo el tráfico MCP Cree un script contenedor para registrar toda la comunicación: ```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" ``` Usa esto: ```typescript mcpServers: { "debug-server": { command: "/path/to/mcp-debug-wrapper.sh", args: ["/actual/server/path", "arg1", "arg2"], }, } ``` ### Inspección con el inspector de MCP Use la herramienta oficial MCP Inspector: ```bash npx @modelcontextprotocol/inspector /path/to/your/mcp-server ``` Esto proporciona una interfaz de usuario web para: * Envío de solicitudes de prueba * Ver respuestas * Inspección de esquemas de herramientas ### Errores de coincidencia de versiones del protocolo Compruebe que el servidor admite la versión del protocolo que usa el SDK: ```json // In initialize response, check protocolVersion {"result":{"protocolVersion":"2024-11-05",...}} ``` Si las versiones no coinciden, actualice la biblioteca del servidor MCP. ## Lista de comprobación de depuración Al abrir un problema o pedir ayuda, recopile: * [ ] Lenguaje y versión del SDK * [ ] Versión de la CLI (`copilot --version`) * [ ] Tipo de servidor MCP (Node.js, Python, .NET, Go, Rust, etc.) * [ ] Configuración completa del servidor MCP (ocultar secretos) * [ ] Resultado de la prueba manual `initialize` * [ ] Resultado de la prueba manual `tools/list` * [ ] Depurar registros del SDK * [ ] Cualquier mensaje de error ## Consulte también * [Uso de servidores MCP con el SDK de GitHub Copilot](/es/copilot/how-tos/copilot-sdk/features/mcp) - Configuración y puesta en marcha * [Guía de depuración](/es/copilot/how-tos/copilot-sdk/troubleshooting/debugging) - depuración de todo el SDK * [Especificación de MCP](https://modelcontextprotocol.io/) : documentos de protocolo oficiales