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環境（可選）。

📄 許可證

[在此添加許可證信息]