Dotnetframeworkmcp

🚀 .NET Framework MCP Server for Windows

A TCP-based Model Context Protocol (MCP) server tailored for building, testing, and running .NET Framework projects on Windows. It allows Claude Code (running in WSL or other environments) to remotely build .NET Framework projects using the Windows build toolchain.

🚀 Quick Start

The .NET Framework MCP Server is designed to facilitate the building, testing, and running of .NET Framework projects on Windows. It acts as a bridge between AI assistants like Claude Code and the Windows .NET Framework build environment.

✨ Features

• TCP-Only Architecture: Enables remote access from WSL or other environments.
• Process-Based MSBuild: Directly executes MSBuild.exe for maximum compatibility.
• .NET Framework Focus: Specifically built for .NET Framework projects (not .NET Core/.NET 5+).
• Build Operations: Fully supports Debug/Release configurations and platform targets.
• Error Parsing: Structured parsing of MSBuild errors and warnings.
• Minimal Dependencies: Clean architecture with only essential packages.

📦 Installation

On Windows (Server Side)

• Visual Studio 2019/2022 or Build Tools for Visual Studio
• .NET 8.0 SDK (for running the MCP server itself)
• Windows OS (Windows 10/11 or Windows Server)

On WSL/Linux (Client Side)

• Claude Code with MCP support
• netcat (nc) for TCP communication (only if using the bridge script): sudo apt install netcat-openbsd

Windows Setup

1. Clone the repository on your Windows machine:

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

2. Build the MCP server:

   build-on-windows.bat
   

   This creates a self - contained executable in the publish folder.
3. Start the TCP server:

   run-tcp-server.bat
   

   The server will start listening on port 3001.

WSL/Linux Setup (Claude Code)

How the WSL - to - Windows Bridge Works

Since Claude Code only runs on macOS/Linux, Windows users must run it in WSL2. The bridge enables communication between Claude Code (in WSL2) and the MCP server (on Windows):

1. The MCP server runs on Windows as a TCP server listening on port 3001.
2. Claude Code runs in WSL2 and needs to connect to the Windows MCP server.
3. WSL2 networking - By default, WSL2 uses NAT - based networking. To connect from WSL2 to Windows:
   • In WSL2's default NAT mode, you may need to use the Windows host IP instead of localhost.
   • Windows 11 22H2+ offers "Mirrored Mode" networking which improves localhost connectivity.
   • The bridge script is configured to use localhost which works in many setups.
4. The bridge script (wsl-mcp-bridge.sh) uses netcat to establish the TCP connection:
   • Claude Code executes the bridge script.
   • The script runs nc localhost 3001.
   • This connects to the Windows MCP server via WSL2's localhost forwarding.
   • All MCP protocol communication flows through this TCP connection.

The flow looks like this:

Claude Code (WSL2) → Bridge Script → netcat → localhost:3001 → Windows MCP Server

You don't directly interact with netcat - it's wrapped inside the bridge script that Claude Code executes automatically.

Configuration Steps

1. Configure Claude Code by editing ~/.config/Claude/claude_desktop_config.json:

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

2. Create the bridge script (adjust the path to your project location):

   #!/bin/bash
   exec nc localhost 3001
   

3. Make it executable:

   chmod +x wsl-mcp-bridge.sh
   

4. Restart Claude Code to pick up the configuration.

💻 Usage Examples

Basic Usage

The MCP server provides several tools to interact with .NET Framework projects:

build_project

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "build_project",
  "params": {
    "path": "path/to/your/project.csproj",
    "configuration": "Debug",
    "platform": "Any CPU",
    "restore": true
  }
}

run_tests

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "run_tests",
  "params": {
    "path": "path/to/your/test/project",
    "filter": "TestCategory=Unit",
    "verbose": true
  }
}

Advanced Usage

run_project

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "run_project",
  "params": {
    "path": "path/to/your/project",
    "args": ["arg1", "arg2"],
    "workingDirectory": "path/to/working/directory"
  }
}

analyze_solution

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "analyze_solution",
  "params": {
    "path": "path/to/your/solution.sln"
  }
}

list_packages

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "list_packages",
  "params": {
    "path": "path/to/your/project"
  }
}

📚 Documentation

Testing the Service

With Claude Code (WSL to Windows)

Option 1: Build Once, Run Compiled Executable (Recommended)

1. Build the project on Windows:

   build-on-windows.bat
   

   This creates a self - contained executable in the publish folder.
2. Start the TCP server:

   run-tcp-server.bat
   

   Or directly:

   publish\DotNetFrameworkMCP.Server.exe --port 3001
   

Option 2: Build and Run Each Time

1. Start the TCP server (builds if needed):

   start-tcp-server.bat
   

   Or manually:

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

2. Configure Claude Code in WSL:

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

3. Make sure netcat is installed in WSL:

   sudo apt install netcat-openbsd
   

Benefits of Pre - Building on Windows

• Faster startup: No build time when starting the server.
• No build dependencies: The compiled executable includes all dependencies.
• Consistent behavior: Same executable every time.
• Easy deployment: Just copy the publish folder.

Troubleshooting

• MSBuild errors: The server will automatically find Visual Studio MSBuild. If you get MSBuild errors:
  • Use run-tcp-server-vs2022.bat for explicit VS2022 MSBuild.
  • Or set environment variable: set MSBUILD_PATH=C:\Path\To\MSBuild\Bin.
  • Ensure Visual Studio or Build Tools for Visual Studio is installed.
• If the server doesn't start: Check Windows Firewall - it may block port 3001.
• If WSL can't connect: WSL2 networking varies by configuration. Try these solutions:

  # Option 1: Find Windows host IP (for default NAT mode):
  ip route show | grep -i default | awk '{ print $3}'
  # Or check nameserver:
  cat /etc/resolv.conf | grep nameserver
  
  # Option 2: Enable Mirrored Mode networking (Windows 11 22H2+)
  # Add to .wslconfig in your Windows user directory:
  # [wsl2]
  # networkingMode=mirrored
  

  Then update WINDOWS_HOST in wsl-mcp-bridge.sh to use the IP address instead of "localhost".
• Port already in use: Change the port in both the server startup and bridge script.

Manual Testing

Use the provided test script:

./test-tcp-server.sh

Or test with netcat:

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

Available Test Messages

See test-messages.json for example MCP protocol messages you can send to test different functionality.

Configuration

The service can be configured through appsettings.json or environment variables:

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

Configuration Options

• MsBuildPath: Path to MSBuild.exe or "auto" for automatic detection.
• DefaultConfiguration: Default build configuration (Debug/Release).
• DefaultPlatform: Default target platform (Any CPU/x86/x64).
• TestTimeout: Test execution timeout in milliseconds (default: 5 minutes).
• BuildTimeout: Build timeout in milliseconds (default: 20 minutes).
• EnableDetailedLogging: Enable verbose logging.
• PreferredVSVersion: Preferred Visual Studio version ("2022", "2019", or "auto").
• UseDotNetCli: Use dotnet CLI instead of MSBuild/VSTest (default: false).
• DotNetPath: Path to dotnet CLI executable (default: "dotnet").

The PreferredVSVersion setting controls which Visual Studio version's MSBuild and VSTest tools to use when multiple versions are installed:

• "2022": Prefer Visual Studio 2022 tools (default).
• "2019": Prefer Visual Studio 2019 tools.
• "auto": Use any available version (searches 2022 first, then 2019).

Environment variables use the prefix MCPSERVER_, for example:

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

Using dotnet CLI Instead of MSBuild

The MCP server now supports using the dotnet CLI as an alternative to MSBuild/VSTest. This can be useful when:

• You don't have Visual Studio or Build Tools installed.
• You prefer using the .NET SDK toolchain.
• You're working with newer .NET projects that support the dotnet CLI.

To enable dotnet CLI mode:

1. Via configuration file (appsettings.json):

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

2. Via environment variable:

   set MCPSERVER__UseDotNetCli=true
   

Note: The dotnet CLI has some limitations when working with older .NET Framework projects:

• Some project types may not be fully supported.
• Complex build configurations might require MSBuild.
• Legacy project formats (.csproj before SDK - style) may have limited support.

When UseDotNetCli is enabled:

• dotnet build is used instead of MSBuild.exe.
• dotnet test is used instead of VSTest.Console.exe.

🔧 Technical Details

Architecture

┌─────────────────┐    TCP/3001     ┌──────────────────┐
│ Claude Code     │ ──────────────→ │ TCP MCP Server   │
│ (WSL/Linux)     │                 │ (Windows)        │
└─────────────────┘                 └──────────────────┘
                                            │
                                            ▼
                                    ┌──────────────────┐
                                    │ MSBuild.exe      │
                                    │ (Visual Studio)  │
                                    └──────────────────┘

Development Status

🎉 FIRST RELEASE READY - Core functionality complete for .NET Framework building and testing.

✅ Completed (Ready for Release)

• Core Infrastructure: MCP protocol, TCP server, configuration management.
• Build System: MSBuild integration with VS version selection, output parsing, error handling.
• Test Runner: Multi - framework support (NUnit/xUnit/MSTest) with TRX parsing for detailed results.
• Quality Features: Cancellation support, intelligent output truncation, comprehensive logging.
• Cross - Platform: WSL - to - Windows communication bridge for Claude Code integration.

🚀 Available MCP Tools

• build_project - Build .NET Framework solutions and projects.
• run_tests - Execute tests with detailed error reporting and stack traces.

📋 Future Enhancements (Post - Release)

• ⏳ run_project - Execute console applications.
• ⏳ analyze_solution - Solution structure analysis.
• ⏳ list_packages - NuGet package listing.
• ⏳ Authentication & Security - API key or token - based authentication for secure access.
• ⏳ Enhanced debugging and profiling integration.

Release Notes

v1.0.0 - First Release

Core Features:

• Complete MCP protocol implementation with TCP server for WSL - to - Windows communication.
• MSBuild integration with Visual Studio 2019/2022 version selection.
• Comprehensive test runner supporting NUnit, xUnit, and MSTest frameworks.
• TRX file parsing for accurate error messages, stack traces, and class names.
• Intelligent output truncation to comply with Claude Code's 25k token limit.
• Robust error handling, build cancellation, and timeout management.
• Extensive configuration options via appsettings.json and environment variables.

Requirements:

• Windows with Visual Studio 2019 or 2022 (or Build Tools).
• .NET Framework projects and solutions.
• WSL environment for Claude Code integration (optional).

📄 License

[Add your license here]