デバッグガイド

デバッグログを有効化する

デバッグの最初の手順は、詳細ログを有効にして、内部で何が起こっているかを確認することです。

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

ログディレクトリ

CLI は、ディレクトリにログを書き込みます。カスタムの場所を指定できます。

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.

メモ

PYTHON SDK ログの構成は制限されています。高度なログ記録を行う場合は、 --log-dir を使用して CLI を手動で実行し、 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.

一般的な問題

"CLI が見つかりません" / "Copilot: コマンドが見つかりません"

Cause: Copilot CLI が PATH にインストールされていないか、インストールされていません。

Solution:

CLI のインストール: インストールガイド
インストールを確認します。
```
copilot --version
```
または、完全なパスを指定します。

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

"認証されていません"

Cause: CLI はGitHubで認証されません。

Solution:

CLI を認証します。
```
copilot auth login
```
または、プログラムでトークンを指定します。

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

"セッションが見つかりません"

原因： 破棄されたセッションまたは存在しないセッションを使用しようとしています。

Solution:

disconnect()後にメソッドを呼び出していないことを確認します。
```
await session.disconnect();
// Don't use session after this!
```
セッションを再開する場合は、セッション ID が存在することを確認します。
```
const sessions = await client.listSessions();
console.log("Available sessions:", sessions);
```

"接続が拒否されました" / "ECONNREFUSED"

原因： CLI サーバープロセスがクラッシュしたか、開始に失敗しました。

Solution:

CLI が正しくスタンドアロンで実行されているかどうかを確認します。
```
copilot --server --stdio
```

TCP モードを使用している場合は、ポートの競合を確認します。

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

MCP サーバーのデバッグ

MCP (モデルコンテキストプロトコル) サーバーは、デバッグが難しい場合があります。包括的な MCP デバッグガイダンスについては、専用 MCP サーバーデバッグガイド を参照してください。

クイック MCP チェックリスト

MCP サーバー実行可能ファイルが存在し、独立して実行される
コマンドパスが正しい (絶対パスを使用)
ツールが有効になっています。 tools: ["*"]
サーバーが initialize 要求に正しく応答する
作業ディレクトリ (cwd) が必要に応じて設定される

MCP サーバーをテストする

SDK と統合する前に、MCP サーバーが動作することを確認します。

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

詳細なトラブルシューティングについては、 MCP サーバーデバッグガイドを参照してください。

接続に関する問題

stdio と TCP モード

SDK では、次の 2 つのトランスポートモードがサポートされています。

モード	Description	ユースケース(事例)
Stdio (既定)	CLI はサブプロセスとして実行され、パイプ経由で通信します	ローカル開発、単一プロセス
TCP	CLI は個別に実行され、TCP ソケット経由で通信します	複数のクライアント、リモート CLI

Stdio モード (既定):

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

TCP モード:

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

既存のサーバーに接続します。

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

接続エラーの診断

クライアントの状態を確認します。

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

状態の変化を監視する:

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

CLI プロセスが実行されていることを確認します。
```
# Check for copilot processes
ps aux | grep copilot
```

ツールの実行に関する問題

カスタムツールが呼び出されない

ツールの登録を確認します。

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

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

ツールスキーマが有効な JSON スキーマであることを確認します。

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

ハンドラーが有効な結果を返すことを確認します。

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

ツールエラーが表示されない

エラーイベントを購読する:

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

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

プラットフォーム固有の問題

ウィンドウズ

パス区切り文字: raw 文字列またはフォワードスラッシュを使用します。

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

PATHEXT の解決: SDK はこれを自動的に処理しますが、問題が解決しない場合:
```
// Explicitly specify .exe
Command = "myserver.exe"  // Not just "myserver"
```
コンソールエンコード: 適切な JSON 処理のために UTF-8 を確認します。
```
Console.OutputEncoding = System.Text.Encoding.UTF8;
```

macOS

ゲートキーパーの問題: CLI がブロックされている場合:
```
xattr -d com.apple.quarantine /path/to/copilot
```
GUI アプリでの PATH の問題: GUI アプリケーションはシェル PATH を継承できません。
```
const client = new CopilotClient({
  cliPath: "/opt/homebrew/bin/copilot",  // Full path
});
```

Linux

アクセス許可の問題:
```
chmod +x /path/to/copilot
```
不足しているライブラリ: 必要な共有ライブラリを確認します。
```
ldd /path/to/copilot
```

ヘルプを受ける

まだ解決しない場合:

デバッグ情報を収集します。
- SDK のバージョン
- CLI バージョン (copilot --version)
- オペレーティングシステム
- デバッグログ
- 最小限の再現コード
既存の問題を検索する:GitHub Issues
収集された情報に関する新しい問題を開く

こちらも参照ください

初めてのCopilot搭載アプリを構築する
Using MCP servers with the GitHub Copilot SDK - MCP の構成とセットアップ
MCP サーバーデバッグガイド - MCP の詳細なトラブルシューティング
API リファレンス

この記事で

目次

デバッグログを有効化する

ログディレクトリ

一般的な問題

"CLI が見つかりません" / "Copilot: コマンドが見つかりません"

"認証されていません"

"セッションが見つかりません"

"接続が拒否されました" / "ECONNREFUSED"

MCP サーバーのデバッグ

クイック MCP チェックリスト

MCP サーバーをテストする

接続に関する問題

stdio と TCP モード

接続エラーの診断

ツールの実行に関する問題

カスタムツールが呼び出されない

ツールエラーが表示されない

プラットフォーム固有の問題

ウィンドウズ

macOS

Linux

ヘルプを受ける

こちらも参照ください

デバッグ ガイド

この記事で

デバッグガイド