Guia de depuração

Sumário

Habilitar registro de depuração
Problemas comuns
Depuração do servidor MCP
Problemas de conexão
Problemas de execução da ferramenta
Problemas específicos da plataforma

Habilitar o log de depuração

A primeira etapa na depuração é habilitar o log detalhado para ver o que está acontecendo sob o capô.

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")
);

Diretório de log

A CLI grava logs em um diretório. Você pode especificar um local personalizado:

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.

Observação

A configuração de logging do SDK do Python é limitada. Para logs avançados, execute a CLI manualmente com --log-dir e conecte-se por meio de 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 comuns

"CLI não encontrada" / "Copilot: comando não encontrado"

Cause: A CLI do Copilot não está instalada ou não está no PATH.

Solution:

Instalar a CLI: Guia de instalação
Verifique a instalação:
```
copilot --version
```
Ou especifique o caminho completo:

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")
);

"Não autenticado"

Cause: a CLI não é autenticada com GitHub.

Solution:

Autenticar a interface de linha de comando (CLI):
```
copilot auth login
```
Ou forneça um token programaticamente:

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"))
);

"Sessão não encontrada"

Causa: Tentando usar uma sessão que foi destruída ou não existe.

Solution:

Verifique se você não está chamando métodos após disconnect():
```
await session.disconnect();
// Don't use session after this!
```

Para retomar as sessões, verifique se a ID da sessão existe:

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

"Conexão recusada" / "ECONNREFUSED"

Causa: O processo do servidor da CLI falhou ou falhou ao iniciar.

Solution:

Verifique se a CLI é executada corretamente autônoma:
```
copilot --server --stdio
```

Verifique se há conflitos de porta se estiver usando o modo TCP:

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

Os servidores MCP (Protocolo de Contexto de Modelo) podem ser complicados de depurar. Para obter orientações completas sobre a depuração do MCP, consulte o Guia de depuração do servidor MCP específico.

Lista de verificação rápida do MCP

O executável do servidor MCP existe e é executado de forma independente
O caminho do comando está correto (use caminhos absolutos)
As ferramentas estão habilitadas: tools: ["*"]
O servidor responde à initialize solicitação corretamente
O diretório de trabalho (cwd) é definido, se necessário

Testar o servidor MCP

Antes de integrar com o SDK, verifique se o 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 Guia de depuração do servidor MCP para obter uma solução de problemas detalhada.

Problemas de conexão

modo stdio vs TCP

O SDK dá suporte a dois modos de transporte:

Modo	Description	Caso de uso
Stdio (padrão)	A CLI é executada como subprocesso, comunica-se por meio de pipes	Desenvolvimento local, processo único
TCP	A CLI é executada separadamente, comunica-se por meio do soquete TCP	Vários clientes, CLI remota

Modo stdio (padrão):

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
});

Conecte-se ao servidor existente:

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

Diagnosticando falhas de conexão

Verifique o estado do cliente:

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

Ouça as alterações de estado:

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

Verifique se o processo da CLI está em execução:

# Check for copilot processes
ps aux | grep copilot

Problemas de execução da ferramenta

Ferramenta personalizada não está sendo chamada

Verificar o registro da ferramenta:

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

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

Verificar se o esquema da ferramenta é um 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 };
  },
};

Verifique se o manipulador retorna o resultado válido:

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

Erros de ferramenta que não são exibidos

Inscreva-se em eventos de erro:

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 da plataforma

Windows

Separadores de caminho: Use cadeias de caracteres brutas ou barras para frente:

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

Resolução PATHEXT: O SDK lida com isso automaticamente, mas se os problemas persistirem:
```
// Explicitly specify .exe
Command = "myserver.exe"  // Not just "myserver"
```
Codificação do console: Certifique-se de UTF-8 para tratamento JSON adequado:
```
Console.OutputEncoding = System.Text.Encoding.UTF8;
```

macOS

Problemas do gatekeeper: Se a CLI estiver bloqueada:
```
xattr -d com.apple.quarantine /path/to/copilot
```

Problemas de PATH em aplicativos de GUI: Os aplicativos de GUI podem não herdar o PATH do shell:

const client = new CopilotClient({
  cliPath: "/opt/homebrew/bin/copilot",  // Full path
});

Linux

Problemas de permissão:
```
chmod +x /path/to/copilot
```
Bibliotecas ausentes: Verifique se há bibliotecas compartilhadas necessárias:
```
ldd /path/to/copilot
```

Obtendo ajuda

Se você ainda estiver preso:

Coletar informações de depuração:
- Versão do SDK
- Versão da CLI (copilot --version)
- Sistema operacional
- Debugar logs
- Código de reprodução mínimo
Pesquisar issues existentes:GitHub Issues
Abrir um novo problema com as informações coletadas

Consulte também

Crie seu primeiro aplicativo com tecnologia do Copilot
Using MCP servers with the GitHub Copilot SDK - Configuração e instalação do MCP
Guia de depuração do servidor MCP – Solução de problemas detalhada do MCP
Referência da API

Neste artigo