在 Copilot SDK 中调试 MCP 服务器

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

谁可以使用此功能？

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 服务器。

手动协议测试

通过 stdin 发送 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 示例，请参阅 MCP 服务器调试指南（位于 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
  },
}

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

  3. 初始化握手失败： 服务器必须正确响应 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"
});

  2. 工具描述不清晰

    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. 工具模式问题： 确保 inputSchema 为有效的 JSON Schema。必需字段必须列在 required 数组中。

超时错误

症状： MCP tool call timed out 错误。

  1. 增加超时时间

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

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

  3. 对于长时间运行的工具，如支持，请考虑使用流式响应。

JSON-RPC 错误

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

常见原因

  1. 服务器错误地写入 stdout： 调试输出写入 stdout 而不是 stderr，或出现额外的换行或空白。

    TypeScript
    // Wrong—pollutes stdout
console.log("Debug info");

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

  2. 编码问题： 确保使用 UTF-8 编码且无 BOM（字节顺序标记）。

  3. 消息帧： 每条消息必须是完整的 JSON 对象，并以换行分隔（每行一条消息）。

平台特定问题

Windows

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

有关 .NET 控制台应用和 NPX 命令的 Windows 特定配置示例，请参阅 MCP 服务器调试指南（位于 github/copilot-sdk 仓库）。

路径问题

  • 使用原始字符串（@\"C:\\path\"）或正斜杠（\"C:/path\"）。
  • 尽量避免路径中出现空格。
  • 如果必须使用空格，请确保正确引用。

macOS

  1. Gatekeeper 阻止： 如果服务器被阻止

    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 Inspector 检查

使用官方的 MCP Inspector 工具

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

它提供了一个网页 UI，用于发送测试请求、查看响应并检查工具模式。

协议版本不匹配

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

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

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

调试检查清单

在 GitHub Issues 上打开 issue 或请求帮助时，请收集以下信息

  • SDK 语言及版本
  • CLI 版本（copilot --version）
  • MCP 服务器类型（Node.js、Python、.NET、Go 等）
  • 完整的 MCP 服务器配置（请隐藏机密信息）
  • 手动 initialize 测试结果
  • 手动 tools/list 测试结果
  • 来自 SDK 的调试日志
  • 任何错误信息
© . This site is unofficial and not affiliated with GitHub, Inc.