dotnet-mcp-hero

dotnet-mcp-hero

3
ai_chatbot

The .NET Hero API project is a superhero management system utilizing clean architecture principles with a Model Context Protocol (MCP) server to enable AI assistant integration. It's designed to manage superheroes, teams, and missions through a structured API and AI tools.

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

🎯 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

Running the Hero API

  1. Navigate to the AppHost directory:
cd Api/tools/AppHost
  1. 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
  1. 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
  1. 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
  1. 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
  1. 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