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端设置

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

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

构建MCP服务器：
```
build-on-windows.bat
```
此操作会在publish文件夹中创建一个自包含的可执行文件。
启动TCP服务器：
```
run-tcp-server.bat
```
服务器将开始监听3001端口。

WSL/Linux端设置（Claude Code）

WSL到Windows的桥接工作原理

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

MCP服务器：在Windows上作为TCP服务器运行，监听3001端口。
Claude Code：在WSL2中运行，需要连接到Windows MCP服务器。
WSL2网络：默认情况下，WSL2使用基于NAT的网络。要从WSL2连接到Windows：
- 在WSL2的默认NAT模式下，可能需要使用Windows主机IP而非localhost。
- Windows 11 22H2+提供“镜像模式”网络，可改善localhost连接。
- 桥接脚本配置为使用localhost，在许多设置中均可正常工作。
桥接脚本 (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自动执行的桥接脚本中。

配置步骤

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

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

创建桥接脚本（根据项目位置调整路径）：
```
#!/bin/bash
exec nc localhost 3001
```
使其可执行：
```
chmod +x wsl-mcp-bridge.sh
```
重启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：预构建，运行编译后的可执行文件（推荐）

在Windows上构建项目：
```
build-on-windows.bat
```
此操作会在publish文件夹中创建一个自包含的可执行文件。

启动TCP服务器：

run-tcp-server.bat

或者直接执行：

publish\DotNetFrameworkMCP.Server.exe --port 3001

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

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

start-tcp-server.bat

或者手动执行：

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

在WSL中配置Claude Code：

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

确保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模式：

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

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

通过环境变量：
```
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环境（可选）。

📄 许可证

[在此添加许可证信息]

0 条评论
分类：开发