jamesburton/AspireMcpServer

.NET Aspire MCP Server

A comprehensive Model Context Protocol (MCP) server that exposes .NET Aspire CLI commands as MCP tools. Built with the Microsoft ModelContextProtocol library and optimized for AOT compilation with minimal footprint.

Features

Core .NET Aspire Commands

• Project Lifecycle: Initialize, build, run, publish, and deploy .NET Aspire applications
• Development Environment: Start and manage the Aspire development experience with dashboard
• Application Management: Start, stop, list, and monitor running Aspire applications
• Template Management: List, install, and uninstall Aspire project templates
• Deployment: Generate manifests and deploy to various targets (Kubernetes, Docker Compose, etc.)

🆕 Enhanced Template & Extension Management

• Custom Template Creation: Create, package, and validate custom Aspire project templates
• Template Source Management: Add, remove, and update template sources from multiple repositories
• Template Discovery: Search and get detailed information about available templates
• Extension Integration: Seamless integration with Aspire extensions and community templates

🆕 Advanced Resource Monitoring & Health Checks

• Real-time Monitoring: Monitor CPU, memory, network, and disk metrics in real-time
• Health Status Tracking: Comprehensive health checks with dependency analysis
• Performance Analytics: Resource utilization statistics and performance reports
• Alerting System: Configurable monitoring alerts with webhook integration
• Security Scanning: Vulnerability, configuration, and compliance scanning
• Auto-scaling: Intelligent resource scaling based on performance metrics

🆕 Multi-Cloud Deployment Support

• Azure Integration: Deploy to Azure Container Apps with full configuration support
• AWS Support: Deploy to AWS ECS with VPC, security groups, and load balancer integration
• Google Cloud: Deploy to Google Cloud Run with service accounts and resource limits
• Multi-cloud Strategies: Configure failover and traffic distribution across providers
• Custom Cloud Targets: Support for custom cloud providers and deployment endpoints

🆕 Container Orchestration Integration

• Kubernetes Support: Full Kubernetes deployment with ConfigMaps, Secrets, and HPA
• Docker Swarm: Deploy to Docker Swarm with network and volume management
• Service Mesh: Integration with Istio, Linkerd, and Consul Connect
• Ingress Management: Configure ingress controllers and TLS termination
• Persistent Storage: Manage persistent volumes and storage classes
• Cluster Policies: Configure network, security, and RBAC policies

🆕 DevOps & CI/CD Integration

• Pipeline Generation: Generate GitHub Actions, Azure DevOps, and GitLab CI pipelines
• Infrastructure as Code: Support for Terraform, Bicep, ARM, Pulumi, and CDK
• Testing Automation: Configure unit, integration, e2e, performance, and security testing
• Deployment Strategies: Blue-green, canary, rolling, and recreate deployment patterns
• Observability: Integrate with Prometheus, Grafana, Jaeger, ELK, and commercial APM tools
• Secrets Management: Integration with Azure Key Vault, AWS Secrets, HashiCorp Vault
• Compliance: Generate SOC2, ISO27001, HIPAA, GDPR, and PCI-DSS compliance reports
• Disaster Recovery: Configure backup, replication, and failover strategies

Dynamic CLI Tool

• DynamicAspire: Execute any .NET Aspire CLI command with custom arguments
• Future-Proof: Supports any current or future Aspire CLI commands automatically
• Flexible: Working directory support and comprehensive error handling

Advanced Features

• AOT Compilation: Optimized for ahead-of-time compilation with minimal binary size
• Cross-Platform: Supports Windows, Linux, and macOS
• Single File: Can be compiled to a single, self-contained executable
• High Performance: Minimal memory footprint and fast startup times

Prerequisites

• .NET 9.0 SDK or later
• .NET Aspire workload: dotnet workload install aspire
• .NET Aspire CLI (included with the workload)

Installation & Usage

Basic Setup

1. Clone and Build:

   git clone <repository-url>
   cd AspireMcpServer
   dotnet build
   

2. Run the Server:

   cd AspireMcpServer
   dotnet run
   

AOT Compilation

For production deployment with optimal performance:

# Windows x64
dotnet publish -c Release -r win-x64

# Linux x64
dotnet publish -c Release -r linux-x64

# macOS ARM64
dotnet publish -c Release -r osx-arm64

The resulting binary will be a single, self-contained executable optimized for size and performance.

Available MCP Tools

Core Aspire Commands

Template Management

Dynamic CLI Tool

Usage Examples

Initializing a New Aspire Project

{
  "tool": "InitProjectAsync",
  "arguments": {
    "name": "MyECommerceApp",
    "output": "./MyECommerceApp",
    "template": "aspire-starter",
    "workingDirectory": "C:\\Projects"
  }
}

Starting Development Environment

{
  "tool": "DevAsync",
  "arguments": {
    "project": "MyECommerceApp.AppHost",
    "launchBrowser": true,
    "port": 15000
  }
}

Publishing for Production

{
  "tool": "PublishAsync",
  "arguments": {
    "project": "MyECommerceApp.AppHost",
    "configuration": "Release",
    "registry": "myregistry.azurecr.io",
    "tag": "v1.0.0",
    "output": "./publish"
  }
}

Using Dynamic CLI Tool

{
  "tool": "DynamicAspireAsync",
  "arguments": {
    "command": "deploy --manifest ./aspire-manifest.json --environment production",
    "workingDirectory": "./MyECommerceApp"
  }
}

Generating Kubernetes Manifests

{
  "tool": "GenerateAsync",
  "arguments": {
    "project": "MyECommerceApp.AppHost",
    "output": "./k8s-manifests",
    "format": "k8s"
  }
}

Architecture

The project follows modern .NET practices with AOT optimization:

• Core/AspireExecutor: Process execution engine for Aspire CLI commands
• Services/AspireCommands: Comprehensive MCP tool implementations
• Program.cs: Minimal hosting setup with MCP server registration
• ILLink.Descriptors.xml: AOT compatibility configuration
• AOT Optimizations: Size and performance optimizations for production

Key Features

Development Experience

• Easy project initialization and template management
• Integrated development environment with hot reload
• Real-time dashboard for monitoring and debugging
• Comprehensive logging and status monitoring

Deployment & Operations

• Multi-target manifest generation (Kubernetes, Docker Compose, etc.)
• Container registry integration with versioning
• Environment-specific deployments
• Application lifecycle management

Performance & Deployment

• AOT compilation for optimal performance
• Single-file deployment ready
• Minimal memory footprint (typically < 50MB)
• Fast startup times (< 100ms)
• Cross-platform compatibility

Dynamic CLI Integration

• Execute any Aspire CLI command through DynamicAspireAsync
• Future-proof design supporting new Aspire features
• Comprehensive error handling and reporting
• Working directory support for complex scenarios

AOT Compilation Benefits

• Size: Reduced application size (typically 20-50MB vs 200MB+ for regular .NET apps)
• Performance: Faster startup and improved runtime performance
• Deployment: Single executable with all dependencies included
• Security: Reduced attack surface with trimmed dependencies

Configuration for MCP Clients

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "aspire": {
      "command": "C:\\path\\to\\AspireMcpServer.exe",
      "env": {
        "ASPIRE_ALLOW_UNSECURED_TRANSPORT": "true"
      }
    }
  }
}

Development Configuration

For development with dotnet run:

{
  "mcpServers": {
    "aspire": {
      "command": "dotnet",
      "args": [
        "run",
        "--project",
        "C:\\Development\\MCP\\AspireMcpServer\\AspireMcpServer"
      ],
      "cwd": "C:\\Development\\MCP\\AspireMcpServer",
      "env": {
        "ASPIRE_ALLOW_UNSECURED_TRANSPORT": "true"
      }
    }
  }
}

Error Handling

• CLI Validation: Checks Aspire CLI availability on startup
• Command Validation: Validates command arguments before execution
• Process Management: Robust process execution with timeout handling
• Error Reporting: Detailed error messages with context and suggestions
• Graceful Degradation: Continues operation even if some commands fail

Development Workflow Integration

Local Development

1. Use InitProjectAsync to create new Aspire projects
2. Use DevAsync to start the development environment
3. Use DashboardAsync to monitor applications
4. Use LogsAsync to debug issues

Build & Test

1. Use BuildAsync to compile applications
2. Use RunAsync to test locally
3. Use StatusAsync to verify application health

Deployment

1. Use GenerateAsync to create deployment manifests
2. Use PublishAsync to build and push container images
3. Use DeployAsync to deploy to target environments
4. Use StatusAsync and LogsAsync to monitor deployments

Troubleshooting

Common Issues

Aspire CLI not found:

# Install the Aspire workload
dotnet workload install aspire

# Verify installation
aspire --version

AOT Compilation Issues:

• Ensure all dependencies support AOT
• Check ILLink.Descriptors.xml for missing type preservation
• Use --verbosity detailed for detailed trimming warnings

Performance Issues:

• Use Release configuration for production builds
• Enable AOT compilation for optimal performance
• Monitor memory usage with built-in diagnostics

Contributing

1. Fork the repository
2. Create a feature branch
3. Follow the existing code patterns
4. Test with both regular and AOT builds
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Related Projects

• - MCP server for .NET CLI commands
• .NET Aspire Documentation
• ModelContextProtocol - .NET implementation of Model Context Protocol