Dotnetframeworkmcp

🚀 Windows版.NET Framework MCP服务器

这是一个基于TCP的模型上下文协议（MCP）服务器，专为在Windows上构建、测试和运行.NET Framework项目而设计。借助该工具，Claude Code（可运行于WSL或其他环境）能够使用Windows构建工具链远程构建.NET Framework项目。

🚀 快速开始

此MCP服务器在AI助手（如Claude）和Windows .NET Framework构建环境之间搭建了桥梁，适用于以下场景：

• Claude Code在WSL/Linux中运行，但需要构建Windows .NET Framework项目。
• 需要构建依赖Visual Studio MSBuild的旧版.NET Framework应用程序。
• 希望在Windows上借助AI辅助进行.NET Framework开发。

✨ 主要特性

• 仅支持TCP架构：专为从WSL或其他环境进行远程访问而设计。
• 基于进程的MSBuild：直接执行MSBuild.exe，确保最大兼容性。
• 专注于.NET Framework：专门为.NET Framework项目构建（不适用于.NET Core/.NET 5+）。
• 构建操作：全面支持Debug/Release配置和平台目标。
• 错误解析：对MSBuild错误和警告进行结构化解析。
• 依赖极少：架构简洁，仅包含必要的包。

📦 安装指南

Windows端设置

1. 克隆仓库：在Windows机器上执行以下命令：

   git clone https://github.com/yourusername/dotnet-framework-mcp
   cd dotnet-framework-mcp
   

2. 构建MCP服务器：

   build-on-windows.bat
   

   此操作会在publish文件夹中创建一个自包含的可执行文件。
3. 启动TCP服务器：

   run-tcp-server.bat
   

   服务器将开始监听3001端口。

WSL/Linux端设置（Claude Code）

WSL到Windows的桥接工作原理

由于Claude Code仅可在macOS/Linux上运行，Windows用户需在WSL2中运行它。该桥接功能可实现Claude Code（在WSL2中）与MCP服务器（在Windows上）之间的通信：

1. MCP服务器：在Windows上作为TCP服务器运行，监听3001端口。
2. Claude Code：在WSL2中运行，需要连接到Windows MCP服务器。
3. WSL2网络：默认情况下，WSL2使用基于NAT的网络。要从WSL2连接到Windows：
   • 在WSL2的默认NAT模式下，可能需要使用Windows主机IP而非localhost。
   • Windows 11 22H2+提供“镜像模式”网络，可改善localhost连接。
   • 桥接脚本配置为使用localhost，在许多设置中均可正常工作。
4. 桥接脚本 (wsl-mcp-bridge.sh)：使用netcat建立TCP连接：
   • Claude Code执行桥接脚本。
   • 脚本运行nc localhost 3001。
   • 通过WSL2的localhost转发连接到Windows MCP服务器。
   • 所有MCP协议通信均通过此TCP连接进行。

具体流程如下：

Claude Code (WSL2) → 桥接脚本 → netcat → localhost:3001 → Windows MCP Server

你无需直接与netcat交互，它被封装在Claude Code自动执行的桥接脚本中。

配置步骤

1. 配置Claude Code：编辑~/.config/Claude/claude_desktop_config.json：

   {
     "mcpServers": {
       "dotnet-framework": {
         "command": "/path/to/wsl-mcp-bridge.sh",
         "env": {
           "MCP_DEBUG": "true"
         }
       }
     }
   }
   

2. 创建桥接脚本（根据项目位置调整路径）：

   #!/bin/bash
   exec nc localhost 3001
   

3. 使其可执行：

   chmod +x wsl-mcp-bridge.sh
   

4. 重启Claude Code：使配置生效。

💻 使用示例

基础用法

该服务实现了以下MCP工具：

build_project

用于构建.NET项目或解决方案。 参数：

• path（字符串，必填）：.csproj或.sln文件的路径。
• configuration（字符串）：构建配置（Debug/Release）。
• platform（字符串）：目标平台（Any CPU/x86/x64）。
• restore（布尔值）：是否恢复NuGet包。

run_tests

用于运行.NET测试项目中的测试。 参数：

• path（字符串，必填）：测试项目的路径。
• filter（字符串）：测试过滤表达式。
• verbose（布尔值）：是否启用详细输出。

run_project

用于执行.NET控制台应用程序。 参数：

• path（字符串，必填）：项目路径。
• args（数组）：命令行参数。
• workingDirectory（字符串）：工作目录。

analyze_solution

用于获取解决方案结构的信息。 参数：

• path（字符串，必填）：.sln文件的路径。

list_packages

用于列出项目中的NuGet包。 参数：

• path（字符串，必填）：项目路径。

📚 详细文档

测试服务

通过Claude Code（从WSL到Windows）

若Claude Code在WSL中运行，而MCP服务器在Windows上：

选项1：预构建，运行编译后的可执行文件（推荐）

1. 在Windows上构建项目：

   build-on-windows.bat
   

   此操作会在publish文件夹中创建一个自包含的可执行文件。
2. 启动TCP服务器：

   run-tcp-server.bat
   

   或者直接执行：

   publish\DotNetFrameworkMCP.Server.exe --port 3001
   

选项2：每次都构建并运行

1. 启动TCP服务器（必要时进行构建）：

   start-tcp-server.bat
   

   或者手动执行：

   dotnet run --project src\DotNetFrameworkMCP.Server -- --port 3001
   

2. 在WSL中配置Claude Code：

   {
     "mcpServers": {
       "dotnet-framework": {
         "command": "/path/to/project/wsl-mcp-bridge.sh",
         "env": {
           "MCP_DEBUG": "true"
         }
       }
     }
   }
   

3. 确保WSL中安装了netcat：

   sudo apt install netcat-openbsd
   

在Windows上预构建的好处

• 启动更快：启动服务器时无需构建。
• 无需构建依赖：编译后的可执行文件包含所有依赖项。
• 行为一致：每次都是相同的可执行文件。
• 易于部署：只需复制publish文件夹。

故障排除

• MSBuild错误：服务器会自动查找Visual Studio MSBuild。若遇到MSBuild错误：
  • 使用run-tcp-server-vs2022.bat明确指定使用VS2022的MSBuild。
  • 或者设置环境变量：set MSBUILD_PATH=C:\Path\To\MSBuild\Bin。
  • 确保已安装Visual Studio或Visual Studio构建工具。
• 服务器无法启动：检查Windows防火墙，可能会阻止3001端口。
• WSL无法连接：WSL2网络配置可能不同。尝试以下解决方案：

  # 选项1：查找Windows主机IP（适用于默认NAT模式）：
  ip route show | grep -i default | awk '{ print $3}'
  # 或者检查名称服务器：
  cat /etc/resolv.conf | grep nameserver
  
  # 选项2：启用镜像模式网络（Windows 11 22H2+）
  # 在Windows用户目录的.wslconfig中添加：
  # [wsl2]
  # networkingMode=mirrored
  

  然后将wsl-mcp-bridge.sh中的WINDOWS_HOST更新为使用IP地址而非"localhost"。
• 端口已被占用：在服务器启动和桥接脚本中更改端口。

手动测试

使用提供的测试脚本：

./test-tcp-server.sh

或者使用netcat进行测试：

echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18"}}' | nc localhost 3001

可用的测试消息

可参考test-messages.json中的示例MCP协议消息，用于测试不同功能。

配置

该服务可通过appsettings.json或环境变量进行配置：

{
  "McpServer": {
    "MsBuildPath": "auto",
    "DefaultConfiguration": "Debug",
    "DefaultPlatform": "Any CPU",
    "TestTimeout": 300000,
    "BuildTimeout": 1200000,
    "EnableDetailedLogging": false,
    "PreferredVSVersion": "2022",
    "UseDotNetCli": false,
    "DotNetPath": "dotnet"
  }
}

配置选项

• MsBuildPath：MSBuild.exe的路径，或设置为"auto"以自动检测。
• DefaultConfiguration：默认构建配置（Debug/Release）。
• DefaultPlatform：默认目标平台（Any CPU/x86/x64）。
• TestTimeout：测试执行超时时间（毫秒，默认：5分钟）。
• BuildTimeout：构建超时时间（毫秒，默认：20分钟）。
• EnableDetailedLogging：是否启用详细日志记录。
• PreferredVSVersion：首选的Visual Studio版本（"2022"、"2019"或"auto"）。
• UseDotNetCli：是否使用dotnet CLI代替MSBuild/VSTest（默认：false）。
• DotNetPath：dotnet CLI可执行文件的路径（默认："dotnet"）。

PreferredVSVersion设置用于控制在安装多个版本时使用哪个Visual Studio版本的MSBuild和VSTest工具：

• "2022"：优先使用Visual Studio 2022工具（默认）。
• "2019"：优先使用Visual Studio 2019工具。
• "auto"：使用任何可用版本（先搜索2022，再搜索2019）。

环境变量使用MCPSERVER_前缀，例如：

• MCPSERVER_DefaultConfiguration=Release
• MCPSERVER_EnableDetailedLogging=true
• MCPSERVER_PreferredVSVersion=2019
• MCPSERVER_UseDotNetCli=true

使用dotnet CLI代替MSBuild

MCP服务器现在支持使用dotnet CLI作为MSBuild/VSTest的替代方案。在以下情况下可能会很有用：

• 未安装Visual Studio或构建工具。
• 更喜欢使用.NET SDK工具链。
• 正在处理支持dotnet CLI的较新.NET项目。

要启用dotnet CLI模式：

1. 通过配置文件 (appsettings.json)：

   {
     "McpServer": {
       "UseDotNetCli": true
     }
   }
   

2. 通过环境变量：

   set MCPSERVER__UseDotNetCli=true
   

注意：dotnet CLI在处理较旧的.NET Framework项目时存在一些限制：

• 某些项目类型可能不完全支持。
• 复杂的构建配置可能需要MSBuild。
• 旧版项目格式（SDK样式之前的.csproj）可能支持有限。

当UseDotNetCli启用时：

• 使用dotnet build代替MSBuild.exe。
• 使用dotnet test代替VSTest.Console.exe。

开发状态

🎉 首个版本发布 - .NET Framework的构建和测试核心功能已完成。

✅ 已完成（可发布）

• 核心基础设施：MCP协议、TCP服务器、配置管理。
• 构建系统：集成MSBuild，支持VS版本选择、输出解析和错误处理。
• 测试运行器：支持多框架（NUnit/xUnit/MSTest），通过TRX解析获取详细结果。
• 质量特性：支持取消操作、智能输出截断和全面日志记录。
• 跨平台：为Claude Code集成提供WSL到Windows的通信桥接。

🚀 可用的MCP工具

• build_project - 构建.NET Framework解决方案和项目。
• run_tests - 执行测试，提供详细的错误报告和堆栈跟踪。

📋 未来增强功能（发布后）

• ⏳ run_project - 执行控制台应用程序。
• ⏳ analyze_solution - 解决方案结构分析。
• ⏳ list_packages - 列出NuGet包。
• ⏳ 身份验证与安全 - 基于API密钥或令牌的身份验证，确保安全访问。
• ⏳ 增强调试和性能分析集成。

版本说明

v1.0.0 - 首个版本

核心特性：

• 完整实现MCP协议，通过TCP服务器实现WSL到Windows的通信。
• 集成MSBuild，支持Visual Studio 2019/2022版本选择。
• 全面的测试运行器，支持NUnit、xUnit和MSTest框架。
• 通过TRX文件解析获取准确的错误消息、堆栈跟踪和类名。
• 智能输出截断，以符合Claude Code的25k令牌限制。
• 强大的错误处理、构建取消和超时管理。
• 通过appsettings.json和环境变量提供广泛的配置选项。

要求：

• 安装Visual Studio 2019或2022（或构建工具）的Windows系统。
• .NET Framework项目和解决方案。
• 用于Claude Code集成的WSL环境（可选）。

📄 许可证

[在此添加许可证信息]