mcp-csharp-debug

用途

mcp-csharp-debug 用于在本地运行、调试和交互式测试 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；未指定时从环境检测。

代理行为：通过检查 .csproj 中是否存在对 ModelContextProtocol.AspNetCore 的 PackageReference 来判断传输类型。存在则为 HTTP，否则为 stdio。

工作流程

第 1 步：本地运行服务器

stdio 传输：

cd <ProjectDir>
dotnet run

进程启动并在 stdin 上等待 JSON-RPC 消息。stdout 无输出表示运行正常。

HTTP 传输：

cd <ProjectDir>
dotnet run
# 服务器监听 http://localhost:3001（或配置的端口）

第 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 提供用于测试工具、查看 schema 和检查协议消息的 UI。

stdio 服务器：

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

HTTP 服务器：

启动服务器：dotnet run

运行 Inspector：npx @modelcontextprotocol/inspector

连接到 http://localhost:3001

详细的 Inspector 能力、用法和故障排除参见 references/mcp-inspector.md。

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

打开 GitHub Copilot Chat → 切换到 Agent 模式。
点击 Select Tools（扳手图标）→ 验证服务器和工具已列出。
使用应触发工具提示词进行测试。
在提示时批准工具执行。

如果工具未出现，排查工具发现：

先重新构建——过期的构建是首要原因：

dotnet build

然后重启 MCP 服务器（在 VS Code 中点击 Stop → Start，或重启 dotnet run）。

检查特性和注册：

验证类上的 [McpServerToolType] 和每个公共方法上的 [McpServerTool]。
方法可以是静态或实例（实例类型需要 DI 注册）。
验证 Program.cs 中的 .WithTools<T>() 或 .WithToolsFromAssembly()。
检查 mcp.json 指向正确的项目路径。

如果仍未出现，显式引用工具：Using #tool_name, do X。

第 5 步：设置断点调试

在工具方法中设置断点。
使用调试器启动：
- VS Code：F5（需要 launch.json，参见 references/ide-config.md）。
- Visual Studio：F5 或右键项目 → Debug → Start。
触发工具（通过 Inspector、Copilot 或测试客户端）。
执行在断点处暂停。

关键：在 Debug 配置中构建。Release 构建中断点不会命中。

诊断工具错误

当工具单独运行正常但通过 MCP 失败时，逐项检查：

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

builder.Logging.AddFile("mcp-debug.log"); // 或使用 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。

参考文件

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

技能介绍

用途

输入