A .NET-based superhero management system comprised of a Clean Architecture API backend and a Model Context Protocol (MCP) server for AI assistant integration.
This project demonstrates how to build a modern .NET application with clean architecture principles and integrate it with the Model Context Protocol (MCP) for AI assistant capabilities. It consists of two main parts:
- HeroApi - A .NET 9 WebAPI built with Clean Architecture principles
- HeroMcp - A Model Context Protocol server that provides AI tool capabilities for interacting with the API
The application is built around a superhero domain model that includes:
- Heroes - Characters with powers, name, alias, and power level
- Teams - Groups of heroes that can undertake missions
- Missions - Tasks that teams can execute and complete
- .NET 9 SDK
- Docker (for database)
- VS Code or other .NET IDE
- Navigate to the AppHost directory:
cd Api/tools/AppHost- Run the application with the .NET CLI:
dotnet runThis will:
- Start a SQL Server container for the database
- Run migrations to set up the database schema
- Start the HeroApi on https://localhost:7255
- Open https://localhost:7255/scalar/v1 in your browser to view the API documentation
- Navigate to the Mcp directory:
cd Mcp- Run the MCP server:
dotnet runThis starts the MCP server which provides tools for interacting with the HeroApi.
The MCP Inspector is a helpful tool for testing your MCP server directly. It allows you to inspect available tools and call them interactively.
- Navigate to the Mcp directory:
cd Mcp- Run the MCP Inspector with the following command:
npx @modelcontextprotocol/inspector dotnet runThis will:
- Start the MCP server
- Launch the MCP Inspector in a terminal interface
- Display available tools and allow you to test them interactively
The inspector will show all available tools from your MCP server and provides a simple interface to call them and view their responses, which is useful for development and debugging.
The project uses Microsoft Kiota to generate a strongly-typed API client. To regenerate the client:
- Ensure the HeroApi is running
- Navigate to the Mcp directory:
cd Mcp- Run the Kiota generator:
dotnet kiota generate --openapi https://localhost:7255/openapi/v1.json --language csharp --class-name HeroClient --clean-output --additional-data falseThis will regenerate the API client in the output directory based on the latest OpenAPI specification.
- Clean Architecture: Separation of concerns with Domain, Application, Infrastructure, and WebApi layers
- Domain-Driven Design: Rich domain model with aggregates, entities, and value objects
- CQRS Pattern: Separation of commands and queries using MediatR
- Minimal APIs: Fast and lightweight API endpoints
- OpenAPI/Scalar: Modern, interactive API documentation
- EF Core: Data access with Entity Framework Core
- Aspire Dashboard: For observability and resource orchestration
- Strongly Typed IDs: Using Vogen to prevent primitive obsession
- Health Checks: Monitor application health
- Comprehensive Testing: Architecture tests, domain unit tests, and API integration tests
- Model Context Protocol: Integration with AI assistants using the MCP standard
- AI Tools: Custom tools for managing heroes, teams, and missions
- Generated API Client: Uses Microsoft Kiota to access the HeroApi
The HeroApi provides the following endpoints:
- GET /api/heroes - Get all heroes
- POST /api/heroes - Create a new hero
- GET /api/teams - Get all teams
- GET /api/teams/{id} - Get a specific team
- POST /api/teams - Create a new team
- POST /api/teams/{id}/heroes/{heroId} - Add a hero to a team
- POST /api/teams/{id}/execute-mission - Execute a mission with a team
- POST /api/teams/{id}/complete-mission - Complete a team's current mission
The MCP server provides the following tools to AI assistants:
- GetHeroes - Retrieve all heroes from the API
- CreateHero - Create a new hero
- GetTeams - Retrieve all teams from the API
- GetTeam - Get a specific team by ID
- CreateTeam - Create a new team
- AddHeroToTeam - Add a hero to a team
- ExecuteMission - Execute a mission with a team
- CompleteMission - Complete a team's mission
- Echo and ReverseEcho - Simple tools for testing the MCP connection
dotnet-mcp-hero/
├── Api/ # Clean Architecture API
│ ├── src/ # Source code
│ │ ├── Application/ # Application layer (use cases)
│ │ ├── Domain/ # Domain layer (business entities)
│ │ ├── Infrastructure/ # Infrastructure layer
│ │ └── WebApi/ # WebApi layer (controllers)
│ ├── tests/ # Test projects
│ │ ├── Architecture.Tests/ # Architecture tests
│ │ ├── Domain.UnitTests/ # Domain unit tests
│ │ └── WebApi.IntegrationTests/ # API integration tests
│ └── tools/ # Developer tools
│ ├── AppHost/ # Aspire host
│ └── MigrationService/ # Database migrations
├── Mcp/ # Model Context Protocol server
│ ├── Program.cs # MCP server setup
│ ├── Tools/ # MCP tools
│ │ ├── Echo/ # Echo tools
│ │ ├── Heroes/ # Hero management tools
│ │ └── Teams/ # Team management tools
│ └── output/ # Generated API client
└── McpHero.sln # Solution file
This project follows Clean Architecture principles with the following layers:
- Domain Layer - Contains business entities, aggregates, value objects, and domain events
- Application Layer - Contains business logic, commands, queries, and interfaces
- Infrastructure Layer - Implements interfaces from the application layer
- WebApi Layer - Exposes the API endpoints
- Architecture Tests - Verifies that the codebase adheres to clean architecture principles
- Domain Unit Tests - Tests the business logic in isolation
- Integration Tests - Tests the API endpoints against a real database
This project is licensed under the MIT License - see the LICENSE file for details.
- Clean Architecture - Robert C. Martin
- Architectural Decision Records - For documenting architectural decisions
- Model Context Protocol - Microsoft's protocol for AI tool integration