在 Copilot SDK 中调试 MCP 服务器

诊断和修复与 Copilot SDKMCP 服务器集成的问题，包括服务器启动失败、工具发现问题和协议错误。

谁可以使用此功能？

GitHub Copilot SDK 适用于所有 Copilot 计划。

在本文中

注意

          Copilot SDK 当前处于 公共预览版. 功能和可用性可能会发生更改。

快速诊断

清单

在深入潜水之前，请验证以下基础知识：

  • MCP 服务器可执行文件存在且可运行
  • 命令路径正确（怀疑时使用绝对路径）
  • 工具已启用（tools: ["*"] 或特定工具名称）
  • 服务器正确实现 MCP 协议（响应 initialize）
  • 没有防火墙或防病毒阻止进程 （Windows）

启用 MCP 调试日志记录

将环境变量添加到 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
    },
  },
}

独立测试 MCP 服务器

始终先在 SDK 外部测试 MCP 服务器。

手动协议测试

通过标准输入发送 initialize 请求：

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

          **预期响应：**

{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"your-server","version":"1.0"}}}

有关 Windows PowerShell 示例，请参阅存储库中的 github/copilot-sdk。

测试工具列表

初始化后，请求工具列表：

Bash
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | /path/to/your/mcp-server

          **预期响应：**

{"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"my_tool","description":"Does something","inputSchema":{...}}]}}

交互式测试脚本

创建测试脚本以交互方式调试 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

用法：

Bash
./test-mcp.sh | /path/to/mcp-server

常见问题

服务器未启动

          **症状：** 没有显示任何工具，日志中没有错误。
原因解决方案
命令路径错误使用绝对路径： /usr/local/bin/server
缺少可执行权限
          `chmod +x /path/to/server`运行 |

| 缺少依赖项 | 使用 ldd (Linux) 检查或手动运行 | | 工作目录问题 | 在配置中设置cwd |

通过手动运行进行调试：

Bash
# Run exactly what the SDK would run
cd /expected/working/dir
/path/to/command arg1 arg2

服务器启动但工具未显示

          **症状：** 服务器进程运行，但没有可用的工具。

1. 配置中未启用的工具：

TypeScript
mcpServers: {
  "server": {
    // ...
    tools: ["*"],  // Must be "*" or list of tool names
  },
}

  1.        **服务器不公开工具：** 手动使用 `tools/list` 请求进行测试。 检查服务器是否实现了 `tools/list` 该方法。

  2.        **初始化握手失败：** 服务器必须正确响应 `initialize` 并处理 `notifications/initialized`。

列出但从未调用过的工具

          **症状：** 工具显示在调试日志中，但模型不使用它们。

1. 提示显然不需要该工具：

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

  1.        **工具说明不清楚：**
    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." }

  2.        **工具架构问题：** 确保 `inputSchema` 是有效的 JSON 架构。 必填字段必须列在 `required` 数组中。

系统超时错误

          **症状：**`MCP tool call timed out` 错误。

  1. 增加超时时间

    TypeScript
    mcpServers: {
  "slow-server": {
    // ...
    timeout: 300000,  // 5 minutes
  },
}

  2. 通过添加进度日志记录来优化服务器性能，以确定瓶颈、考虑异步操作以及检查是否阻止 I/O。

  3. 对于长时间运行的工具，请考虑流式处理响应（如果受支持）。

JSON-RPC 错误

          **症状：** 解析错误，无效请求错误。

常见原因：

  1.           **服务器错误写入标准输出：** 调试输出写入标准输出而非标准错误，或多余换行符或空格：
    TypeScript
    // Wrong—pollutes stdout
console.log("Debug info");

// Correct—use stderr for debug
console.error("Debug info");

  2.        **编码问题：** 确保不带 BOM 的 UTF-8 编码（字节顺序标记）。

  3.        **消息框架：** 每个消息必须是完整的 JSON 对象，换行符分隔（每行一条消息）。

特定于平台的问题

Windows操作系统

在 Windows 上，防病毒或防火墙软件可能会阻止通过 stdin/stdout 进行通信的新可执行文件或进程。 根据需要为 MCP 服务器可执行文件添加排除项。

有关适用于 .NET 控制台应用和 NPX 命令的特定于 Windows 的配置示例，请参阅存储库中的 github/copilot-sdk。

          **路径问题：**
  • 使用原始字符串（@"C:\path"）或正斜杠（"C:/path"）。
  • 尽可能避免路径中的空格。
  • 如果需要空格，请确保进行适当的引用。

macOS

  1.        **守护程序阻止：** 如果服务器被阻止：
    Bash
    xattr -d com.apple.quarantine /path/to/mcp-server

  2.        **Homebrew 路径：** GUI 应用在 PATH 中可能没有 `/opt/homebrew` 。 使用完整路径：
    TypeScript
    mcpServers: {
  "my-server": {
    command: "/opt/homebrew/bin/node",  // Full path
    args: ["/path/to/server.js"],
  },
}

Linux

  1.        **权限问题：**
    Bash
    chmod +x /path/to/mcp-server

  2.        **缺少共享库：**
    Bash
    # Check dependencies
ldd /path/to/mcp-server

# Install missing libraries
apt install libfoo  # Debian/Ubuntu
yum install libfoo  # RHEL/CentOS

高级调试

捕获所有 MCP 流量

创建包装器脚本以记录所有通信：

Bash
#!/bin/bash
# mcp-debug-wrapper.sh

LOG="/tmp/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"

使用它：

TypeScript
mcpServers: {
  "debug-server": {
    command: "/path/to/mcp-debug-wrapper.sh",
    args: ["/actual/server/path", "arg1", "arg2"],
  },
}

使用 MCP 检查器进行检查

使用官方 MCP 检查器工具：

Bash
npx @modelcontextprotocol/inspector /path/to/your/mcp-server

这提供了用于发送测试请求、查看响应和检查工具架构的 Web UI。

协议版本不匹配

检查服务器是否支持 SDK 使用的协议版本：

// In initialize response, check protocolVersion
{"result":{"protocolVersion":"2024-11-05",...}}

如果版本不匹配，请更新 MCP 服务器库。

调试清单

在 GitHub 问题上打开问题或请求帮助时，请收集：

  • SDK 语言和版本
  • CLI 版本 （copilot --version）
  • MCP 服务器类型（Node.js、Python、.NET、Go 等）
  • 完整的 MCP 服务器配置（隐去机密信息）
  • 手动 initialize 测试的结果
  • 手动 tools/list 测试的结果
  • SDK 调试日志
  • 任何错误消息