What is Dotnet Mcp Hero

dotnet-mcp-hero is a .NET-based superhero management system that combines a Clean Architecture API backend with a Model Context Protocol (MCP) server, enabling AI assistant integration.

Use cases

Use cases include managing superhero data, facilitating team missions, and providing AI-driven interactions for users through the MCP server.

How to use

To use dotnet-mcp-hero, ensure you have the .NET 9 SDK and Docker installed. Navigate to the AppHost directory and run ‘dotnet run’ to start the Hero API. Then, navigate to the Mcp directory and run ‘dotnet run’ to start the MCP server.

Key features

Key features include a Clean Architecture design, integration with AI tools via the MCP server, and a domain model that supports heroes, teams, and missions.

Where to use

dotnet-mcp-hero can be used in various domains such as gaming, entertainment, and AI development, particularly where superhero-themed applications or AI interactions are desired.

.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