Guía de depuración

Tabla de contenido

Habilitación del registro de depuración
Problemas comunes
Depuración del servidor MCP
Problemas de conexión
Problemas de ejecución de herramientas
Problemas específicos de la plataforma

Habilitar el registro de depuración

El primer paso en la depuración es habilitar el registro detallado para ver lo que sucede en segundo plano.

TypeScript

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient({
  logLevel: "debug",  // Options: "none", "error", "warning", "info", "debug", "all"
});

Python

from copilot import CopilotClient

client = CopilotClient(log_level="debug")

package main

import copilot "github.com/github/copilot-sdk/go"

func main() {
    client := copilot.NewClient(&copilot.ClientOptions{
        LogLevel: "debug",
    })
    _ = client
}

import copilot "github.com/github/copilot-sdk/go"

client := copilot.NewClient(&copilot.ClientOptions{
    LogLevel: "debug",
})

.NET

using GitHub.Copilot;
using Microsoft.Extensions.Logging;

// Using ILogger
var loggerFactory = LoggerFactory.Create(builder =>
{
    builder.SetMinimumLevel(LogLevel.Debug);
    builder.AddConsole();
});

var client = new CopilotClient(new CopilotClientOptions
{
    LogLevel = "debug",
    Logger = loggerFactory.CreateLogger<CopilotClient>()
});

Java

import com.github.copilot.sdk.CopilotClient;
import com.github.copilot.sdk.json.*;

var client = new CopilotClient(new CopilotClientOptions()
    .setLogLevel("debug")
);

Directorio de logs

La CLI escribe registros en un directorio. Puede especificar una ubicación personalizada:

TypeScript

const client = new CopilotClient({
  cliArgs: ["--log-dir", "/path/to/logs"],
});

Python

# The Python SDK does not currently support passing extra CLI arguments.
# Logs are written to the default location or can be configured via
# the CLI when running in server mode.

Nota:

La configuración de registro del SDK de Python está limitada. Para el registro avanzado, ejecute la CLI manualmente con --log-dir y conéctese mediante RuntimeConnection.for_uri(...).

package main

import copilot "github.com/github/copilot-sdk/go"

func main() {
    client := copilot.NewClient(&copilot.ClientOptions{
        Connection: copilot.StdioConnection{
            Args: []string{"--log-dir", "/path/to/logs"},
        },
    })
    _ = client
}

client := copilot.NewClient(&copilot.ClientOptions{
    Connection: copilot.StdioConnection{
        Args: []string{"--log-dir", "/path/to/logs"},
    },
})

.NET

var client = new CopilotClient(new CopilotClientOptions
{
    Connection = RuntimeConnection.ForStdio(args: new[] { "--log-dir", "/path/to/logs" })
});

Java

// The Java SDK does not currently support passing extra CLI arguments.
// For custom log directories, run the CLI manually with --log-dir
// and connect via cliUrl.

Problemas comunes

"CLI no encontrada" / "Copilot: comando no encontrado"

Cause: La CLI de Copilot no está instalada o no en PATH.

Solution:

Instalación de la CLI: Guía de instalación
Compruebe la instalación:
```
copilot --version
```
O especifique la ruta de acceso completa:

JavaScript

const client = new CopilotClient({
  cliPath: "/usr/local/bin/copilot",
});

Python

client = CopilotClient({"cli_path": "/usr/local/bin/copilot"})

client := copilot.NewClient(&copilot.ClientOptions{
    Connection: copilot.StdioConnection{Path: "/usr/local/bin/copilot"},
})

.NET

var client = new CopilotClient(new CopilotClientOptions
{
    CliPath = "/usr/local/bin/copilot"
});

Java

var client = new CopilotClient(new CopilotClientOptions()
    .setCliPath("/usr/local/bin/copilot")
);

"No autenticado"

Cause: La CLI no se autentica con GitHub.

Solution:

Autenticar la CLI:
```
copilot auth login
```
O bien, proporcione un token mediante programación:

JavaScript

const client = new CopilotClient({
  gitHubToken: process.env.GITHUB_TOKEN,
});

Python

import os
client = CopilotClient({"github_token": os.environ.get("GITHUB_TOKEN")})

client := copilot.NewClient(&copilot.ClientOptions{
    GithubToken: os.Getenv("GITHUB_TOKEN"),
})

.NET

var client = new CopilotClient(new CopilotClientOptions
{
    GithubToken = Environment.GetEnvironmentVariable("GITHUB_TOKEN")
});

Java

var client = new CopilotClient(new CopilotClientOptions()
    .setGitHubToken(System.getenv("GITHUB_TOKEN"))
);

"Sesión no encontrada"

Causa: Intentar usar una sesión que se destruyó o no existe.

Solution:

Asegúrese de que no llama a métodos después de disconnect().

await session.disconnect();
// Don't use session after this!

Para reanudar sesiones, compruebe que el identificador de sesión existe:

const sessions = await client.listSessions();
console.log("Available sessions:", sessions);

"Conexión rechazada" / "ECONNREFUSED"

Causa: El proceso del servidor de la CLI se bloqueó o no se pudo iniciar.

Solution:

Compruebe si la CLI se ejecuta correctamente de forma independiente:
```
copilot --server --stdio
```

Compruebe si hay conflictos de puertos si usa el modo TCP:

const client = new CopilotClient({
  useStdio: false,
  port: 0,  // Use random available port
});

Depuración del servidor MCP

Los servidores MCP (Protocolo de Contexto de Modelo) pueden resultar complicados de depurar. Para obtener una guía completa sobre la depuración de MCP, consulte MCP server debugging guide.

Lista de comprobación rápida de MCP

El ejecutable del servidor MCP existe y se ejecuta de forma independiente
La ruta de acceso del comando es correcta (utilice rutas de acceso absolutas)
Las herramientas están habilitadas: tools: ["*"]
El servidor responde a la initialize solicitud correctamente
El directorio de trabajo (cwd) se establece si es necesario.

Prueba del servidor MCP

Antes de realizar la integración con el SDK, compruebe que el servidor MCP funciona:

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

Consulte MCP server debugging guide para obtener una solución de problemas detallada.

Problemas de conexión

stdio frente al modo TCP

El SDK admite dos modos de transporte:

Modo	Description	Caso de uso
Stdio (valor predeterminado)	La CLI se ejecuta como subproceso, se comunica a través de canalizaciones.	Desarrollo local, proceso único
TCP	La CLI se ejecuta por separado, se comunica a través del socket TCP.	Varios clientes, CLI remota

Modo Stdio (valor predeterminado):

const client = new CopilotClient({
  useStdio: true,  // This is the default
});

Modo TCP:

const client = new CopilotClient({
  useStdio: false,
  port: 8080,  // Or 0 for random port
});

Conéctese al servidor existente:

const client = new CopilotClient({
  cliUrl: "localhost:8080",  // Connect to running server
});

Diagnóstico de errores de conexión

Compruebe el estado del cliente:

console.log("Connection state:", client.getState());
// Should be "connected" after start()

Escuche los cambios de estado:

client.on("stateChange", (state) => {
  console.log("State changed to:", state);
});

Compruebe que el proceso de la CLI se está ejecutando:
```
# Check for copilot processes
ps aux | grep copilot
```

Problemas de ejecución de herramientas

No se llama a la herramienta personalizada

Compruebe el registro de herramientas:

const session = await client.createSession({
  tools: [myTool],
});

// Check registered tools
console.log("Registered tools:", session.getTools?.());

Comprobar el esquema de la herramienta es un esquema JSON válido:

const myTool = {
  name: "get_weather",
  description: "Get weather for a location",
  parameters: {
    type: "object",
    properties: {
      location: { type: "string", description: "City name" },
    },
    required: ["location"],
  },
  handler: async (args) => {
    return { temperature: 72 };
  },
};

Asegúrese de que el controlador devuelve un resultado válido:

handler: async (args) => {
  // Must return something JSON-serializable
  return { success: true, data: "result" };
  
  // Don't return undefined or non-serializable objects
}

Errores de herramientas que no se muestran

Suscríbase a eventos de error:

session.on("tool.execution_error", (event) => {
  console.error("Tool error:", event.data);
});

session.on("error", (event) => {
  console.error("Session error:", event.data);
});

Problemas específicos de la plataforma

Windows

Separadores de ruta: Use cadenas literales o barras diagonales:

CliPath = @"C:\Program Files\GitHub\copilot.exe"
// or
CliPath = "C:/Program Files/GitHub/copilot.exe"

Resolución PATHEXT: El SDK controla esto automáticamente, pero si los problemas persisten:
```
// Explicitly specify .exe
Command = "myserver.exe"  // Not just "myserver"
```
Codificación de la consola: Asegúrese de usar UTF-8 para un manejo correcto de JSON:
```
Console.OutputEncoding = System.Text.Encoding.UTF8;
```

macOS

Problemas de Gatekeeper: Si la CLI está bloqueada:
```
xattr -d com.apple.quarantine /path/to/copilot
```
Problemas de PATH en las aplicaciones de GUI: Es posible que las aplicaciones de GUI no hereden path del shell:
```
const client = new CopilotClient({
  cliPath: "/opt/homebrew/bin/copilot",  // Full path
});
```

Linux

Problemas de permisos:
```
chmod +x /path/to/copilot
```
Faltan bibliotecas: Compruebe si hay bibliotecas compartidas necesarias:
```
ldd /path/to/copilot
```

Obtener ayuda

Si sigues atascado:

Recopilar información de depuración:
- Versión del SDK
- Versión de la CLI (copilot --version)
- Sistema operativo
- Registros de depuración
- Código de reproducción mínimo
Search existing issues:GitHub Issues
Abrir una nueva incidencia con la información recopilada

Consulte también

Crea tu primera aplicación con tecnología Copilot
Using MCP servers with the GitHub Copilot SDK - configuración y puesta en marcha de MCP
MCP server debugging guide : solución de problemas detallada de MCP
Referencia de API

En este artículo