Superhero Team Management

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

![.NET 9.0](https://img.shields.io/badge/.NET-9.0-blue) ![Architecture](https://img.shields.io/badge/Architecture-Clean-green) ![MCP](https://img.shields.io/badge/AI-MCP-purple)

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:

**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

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](https://dotnet.microsoft.com/download/dotnet/9.0)

[Docker](https://www.docker.com/products/docker-desktop/) (for database)

[VS Code](https://code.visualstudio.com/) or other .NET IDE

Running the Hero API

Navigate to the AppHost directory:

Run the application with the .NET CLI:

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

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

Running the MCP Server

Navigate to the Mcp directory:

Run the MCP server:

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.

Navigate to the Mcp directory:

Run the MCP Inspector with the following command:

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:

Ensure the HeroApi is running

Navigate to the Mcp directory:

Run the Kiota generator:

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

Architecture

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

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](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html) - Robert C. Martin

[Architectural Decision Records](https://adr.github.io/) - For documenting architectural decisions

[Model Context Protocol](https://github.com/microsoft/modelcontextprotocol) - Microsoft's protocol for AI tool integration