.NET Hero API with Model Context Protocol

A .NET-based superhero management system comprised of a Clean Architecture API backend and a Model Context Protocol (MCP) server for AI assistant integration.

🎯 Project Overview

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:

1. HeroApi - A .NET 9 WebAPI built with Clean Architecture principles

2. HeroMcp - A Model Context Protocol server that provides AI tool capabilities for interacting with the API

Domain

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

🚀 Getting Started

Prerequisites

• .NET 9 SDK
• Docker (for database)
• VS Code or other .NET IDE

Running the Hero API

1. Navigate to the AppHost directory:

cd Api/tools/AppHost

2. Run the application with the .NET CLI:

dotnet run

This will:

• Start a SQL Server container for the database
• Run migrations to set up the database schema
• Start the HeroApi on https://localhost:7255

3. Open https://localhost:7255/scalar/v1 in your browser to view the API documentation

Running the MCP Server

1. Navigate to the Mcp directory:

cd Mcp

2. Run the MCP server:

dotnet run

This starts the MCP server which provides tools for interacting with the HeroApi.

Running the MCP Inspector

The MCP Inspector is a helpful tool for testing your MCP server directly. It allows you to inspect available tools and call them interactively.

1. Navigate to the Mcp directory:

cd Mcp

2. Run the MCP Inspector with the following command:

npx @modelcontextprotocol/inspector dotnet run

This 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.

Generating the API Client

The project uses Microsoft Kiota to generate a strongly-typed API client. To regenerate the client:

1. Ensure the HeroApi is running

2. Navigate to the Mcp directory:

cd Mcp

3. Run the Kiota generator:

dotnet kiota generate --openapi https://localhost:7255/openapi/v1.json --language csharp --class-name HeroClient --clean-output --additional-data false

This will regenerate the API client in the `output` directory based on the latest OpenAPI specification.

✨ Features

HeroApi

• 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

HeroMcp

• 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

📋 API Endpoints

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

🤖 MCP Tools

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

🏗️ Project Structure

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

📚 Architecture

This project follows Clean Architecture principles with the following layers:

1. Domain Layer - Contains business entities, aggregates, value objects, and domain events

2. Application Layer - Contains business logic, commands, queries, and interfaces

3. Infrastructure Layer - Implements interfaces from the application layer

4. WebApi Layer - Exposes the API endpoints

🧪 Testing

• 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

📖 License

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

🙏 Acknowledgements

• Clean Architecture - Robert C. Martin
• Architectural Decision Records - For documenting architectural decisions
• Model Context Protocol - Microsoft's protocol for AI tool integration