mcp-csharp-debug

C# MCP 服务调试

运行、调试并交互式测试 C# MCP 服务。涵盖本地执行、使用 IDE 断点调试、使用 MCP Inspector 进行协议级测试，以及与 GitHub Copilot Agent Mode 集成。

适用场景

• 首次在本地运行 MCP 服务
• 配置 VS Code 或 Visual Studio 以调试 MCP 服务
• 使用 MCP Inspector 交互式测试工具
• 验证工具是否显示在 GitHub Copilot Agent Mode 中
• 诊断问题：未发现工具、协议错误、服务崩溃
• 设置 mcp.json 或 .mcp.json 配置

停止信号

• 还没有项目？ → 请先使用 mcp-csharp-create
• 需要自动化测试？ → 请使用 mcp-csharp-test
• 生产环境部署问题？ → 请使用 mcp-csharp-publish

输入

输入	必需	描述
项目路径	是	.csproj 文件或项目目录的路径
传输类型	建议提供	stdio 或 http——如未指定，则从 .csproj 检测
IDE	建议提供	VS Code 或 Visual Studio——如未指定，则从环境中检测

Agent 行为： 检查 .csproj 中是否有对 ModelContextProtocol.AspNetCore 的 PackageReference，以检测传输类型。如果存在 → HTTP，否则 → stdio。

工作流

步骤 1：在本地运行服务

stdio 传输：

cd <ProjectDir>
dotnet run

进程启动后会等待从 stdin 接收 JSON-RPC 消息。stdout 没有输出表示运行正常。

HTTP 传输：

cd <ProjectDir>
dotnet run
# Server listens on http://localhost:3001 (or configured port)

步骤 2：生成 MCP 配置

检测 IDE 和传输方式，然后创建相应的配置文件。

对于 VS Code——创建 .vscode/mcp.json：

stdio：

{
  "servers": {
    "<ProjectName>": {
      "type": "stdio",
      "command": "dotnet",
      "args": ["run", "--project", "<path/to/ProjectFile.csproj>"]
    }
  }
}

HTTP：

{
  "servers": {
    "<ProjectName>": {
      "type": "http",
      "url": "http://localhost:3001"
    }
  }
}

对于 Visual Studio——在解决方案根目录创建 .mcp.json（JSON 结构相同）。

有关 IDE 专属配置的详细信息（launch.json、环境变量、密钥），请参阅 references/ide-config.md。

步骤 3：使用 MCP Inspector 测试

MCP Inspector 提供一个 UI，可用于测试工具、查看架构和检查协议消息。

stdio 服务：

npx @modelcontextprotocol/inspector dotnet run --project <path/to/ProjectFile.csproj>

HTTP 服务：

1. 启动服务：dotnet run
2. 运行 Inspector：npx @modelcontextprotocol/inspector
3. 连接到 http://localhost:3001

有关 Inspector 功能、用法和故障排除的详细信息，请参阅 references/mcp-inspector.md。

步骤 4：使用 GitHub Copilot Agent Mode 测试

1. 打开 GitHub Copilot Chat → 切换到 Agent 模式
2. 点击 选择工具（扳手图标）→ 确认列表中显示了你的服务和工具
3. 使用应触发工具的提示词进行测试
4. 根据提示批准工具执行

如果工具未显示——排查工具发现问题：

1. 先重新生成项目——过时的构建是最常见的原因：

   dotnet build
   

   然后重启 MCP 服务（在 VS Code 中点击“停止”→“启动”，或重启 dotnet run）。

2. 检查特性和注册：

   • 确认类上有 [McpServerToolType]，每个公共方法上都有 [McpServerTool]
   • 方法可以是 static 或实例方法（实例类型需要进行 DI 注册）
   • 确认 Program.cs 中有 .WithTools<T>() 或 .WithToolsFromAssembly()

3. 检查 mcp.json 是否指向正确的项目路径

4. 如果仍未显示，请明确引用该工具：Using #tool_name, do X

步骤 5：设置断点调试

1. 在工具方法中设置断点
2. 使用调试器启动：
   • VS Code： F5（需要 launch.json——请参阅 references/ide-config.md）
   • Visual Studio： F5 或右键点击项目 → 调试 → 开始
3. 触发工具（通过 Inspector、Copilot 或测试客户端）
4. 执行会在断点处暂停

重要： 使用 Debug 配置进行构建。Release 构建中断点不会命中。

诊断工具错误

当工具单独运行正常，但通过 MCP 调用时失败，请逐一检查以下事项：

1. 检查 MCP 输出通道 — 在 VS Code 中：视图 → 输出 → 选择你的 MCP 服务名称。这里会显示协议错误和服务的 stderr。在 Visual Studio 中：在“输出”窗口中查找 MCP 相关消息。
2. 附加调试器 — 在发生故障的工具方法中设置断点并逐步执行（参见步骤 5）。检查是否有异常被吞掉或参数值不符合预期。
3. 使用 MCP Inspector 测试 — 通过 Inspector 直接调用工具，以确定问题出在工具代码还是客户端集成：npx @modelcontextprotocol/inspector dotnet run --project <path>
4. 检查 stdout 污染（仅 stdio） — 任何 Console.WriteLine() 或输出到 stdout 的日志都会破坏 JSON-RPC 协议。请将所有输出重定向到 stderr（参见步骤 6）。
5. 检查常见问题：
   • 序列化错误 — 返回类型必须可序列化为 JSON。避免循环引用。
   • DI 注册 — 缺少服务注册会导致运行时异常。检查 Program.cs。
   • 参数绑定 — 确保参数名称和类型与工具架构匹配。
   • 未处理的异常 — 使用 try-catch 包裹工具逻辑，并将日志写入 stderr 或文件。
6. 启用文件日志 — 为便于事后分析，将日志写入文件：

   builder.Logging.AddFile("mcp-debug.log"); // or use Serilog/NLog
   

步骤 6：配置日志记录

对 stdio 传输至关重要： 任何输出到 stdout 的内容（包括 Console.WriteLine）都会破坏 MCP JSON-RPC 协议，导致响应乱码或程序崩溃。所有日志和诊断输出都必须写入 stderr。

stdio 传输 — 仅将日志写入 stderr：

builder.Logging.AddConsole(options =>
    options.LogToStandardErrorThreshold = LogLevel.Trace);

HTTP 传输 — 有关 HTTP 传输的日志配置，请参见 references/ide-config.md。

在工具方法中 — 通过构造函数注入 ILogger<T>，并使用 logger.LogDebug() / logger.LogError()。通过 ILogger 记录日志会遵循上述 stderr 配置。

验证

• 通过 dotnet run 启动服务，且无错误
• MCP Inspector 成功连接，并列出所有预期工具
• 通过 Inspector 调用工具可返回预期结果
• 在 IDE 中调试时能命中断点
• 工具显示在 GitHub Copilot Agent Mode 工具列表中
• stdio：stdout 上没有日志输出（仅 stderr）

常见问题

问题	解决方案
更改后工具未显示或仍显示旧内容	先重新构建： 运行 dotnet build，然后重启服务。如果仍未显示，请确认类上有 [McpServerToolType]、方法上有 [McpServerTool]，并在 Program.cs 中使用 WithTools<T>() 或 WithToolsFromAssembly()
stdio 服务输出乱码	Console.WriteLine() 或日志正在写入 stdout。所有输出都必须写入 stderr。在控制台日志记录器上设置 LogToStandardErrorThreshold = LogLevel.Trace
HTTP 服务在 MCP 端点返回 404	Program.cs 中缺少 app.MapMcp()
未命中断点	正在以 Release 模式构建。请在 Debug 模式下重新构建：运行 dotnet build -c Debug，然后重启
环境变量未传递给服务	在 mcp.json 中添加 "env" 部分。在 VS Code 中使用 "${input:var_id}" 语法来处理机密信息
MCP Inspector 无法连接到 HTTP 服务	服务未运行或端口错误。检查 dotnet run 的输出，确认监听 URL

相关技能

• mcp-csharp-create — 创建新的 MCP 服务项目
• mcp-csharp-test — 自动化测试和评估
• mcp-csharp-publish — NuGet、Docker、Azure 部署

参考文件

• references/mcp-inspector.md — MCP Inspector 的详细用法：安装、连接服务、功能介绍和故障排查。**在以下情况下加载：**用户需要 MCP Inspector 的详细指导，或遇到连接问题。
• references/ide-config.md — 完整的 VS Code 和 Visual Studio 配置：mcp.json 模板、launch.json、环境变量和条件断点。**在以下情况下加载：**设置 IDE 调试或配置特定环境的设置。

更多信息

• MCP Inspector — 用于调试 MCP 服务的交互式工具
• VS Code MCP 文档 — 在 VS Code 中配置 MCP 服务