{"id":27521147,"url":"https://github.com/danielmackay/dotnet-mcp-hero","last_synced_at":"2026-04-09T21:37:01.603Z","repository":{"id":288072350,"uuid":"966736475","full_name":"danielmackay/dotnet-mcp-hero","owner":"danielmackay","description":"Clean Architecture Hero API + MCP Server","archived":false,"fork":false,"pushed_at":"2025-04-15T11:36:09.000Z","size":233,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-15T12:33:48.630Z","etag":null,"topics":["clean-architecture","dotnet","mcp","mcp-server"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/danielmackay.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-15T11:30:47.000Z","updated_at":"2025-04-15T11:36:12.000Z","dependencies_parsed_at":"2025-04-15T12:46:46.797Z","dependency_job_id":null,"html_url":"https://github.com/danielmackay/dotnet-mcp-hero","commit_stats":null,"previous_names":["danielmackay/dotnet-mcp-hero"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielmackay%2Fdotnet-mcp-hero","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielmackay%2Fdotnet-mcp-hero/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielmackay%2Fdotnet-mcp-hero/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielmackay%2Fdotnet-mcp-hero/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/danielmackay","download_url":"https://codeload.github.com/danielmackay/dotnet-mcp-hero/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249458836,"owners_count":21275779,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clean-architecture","dotnet","mcp","mcp-server"],"created_at":"2025-04-18T07:59:01.989Z","updated_at":"2026-04-09T21:36:56.565Z","avatar_url":"https://github.com/danielmackay.png","language":"C#","funding_links":[],"categories":["Servers"],"sub_categories":["DotNET"],"readme":"# .NET Hero API with Model Context Protocol\n\nA .NET-based superhero management system comprised of a Clean Architecture API backend and a Model Context Protocol (MCP) server for AI assistant integration.\n\n![.NET 9.0](https://img.shields.io/badge/.NET-9.0-blue)\n![Architecture](https://img.shields.io/badge/Architecture-Clean-green)\n![MCP](https://img.shields.io/badge/AI-MCP-purple)\n\n## 🎯 Project Overview\n\nThis 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:\n\n1. **HeroApi** - A .NET 9 WebAPI built with Clean Architecture principles\n2. **HeroMcp** - A Model Context Protocol server that provides AI tool capabilities for interacting with the API\n\n### Domain\n\nThe application is built around a superhero domain model that includes:\n\n- **Heroes** - Characters with powers, name, alias, and power level\n- **Teams** - Groups of heroes that can undertake missions\n- **Missions** - Tasks that teams can execute and complete\n\n## 🚀 Getting Started\n\n### Prerequisites\n\n- [.NET 9 SDK](https://dotnet.microsoft.com/download/dotnet/9.0)\n- [Docker](https://www.docker.com/products/docker-desktop/) (for database)\n- [VS Code](https://code.visualstudio.com/) or other .NET IDE\n\n### Running the Hero API\n\n1. Navigate to the AppHost directory:\n\n```bash\ncd Api/tools/AppHost\n```\n\n2. Run the application with the .NET CLI:\n\n```bash\ndotnet run\n```\n\nThis will:\n- Start a SQL Server container for the database\n- Run migrations to set up the database schema\n- Start the HeroApi on https://localhost:7255\n\n3. Open https://localhost:7255/scalar/v1 in your browser to view the API documentation\n\n### Running the MCP Server\n\n1. Navigate to the Mcp directory:\n\n```bash\ncd Mcp\n```\n\n2. Run the MCP server:\n\n```bash\ndotnet run\n```\n\nThis starts the MCP server which provides tools for interacting with the HeroApi.\n\n### Running the MCP Inspector\n\nThe MCP Inspector is a helpful tool for testing your MCP server directly. It allows you to inspect available tools and call them interactively.\n\n1. Navigate to the Mcp directory:\n\n```bash\ncd Mcp\n```\n\n2. Run the MCP Inspector with the following command:\n\n```bash\nnpx @modelcontextprotocol/inspector dotnet run\n```\n\nThis will:\n- Start the MCP server\n- Launch the MCP Inspector in a terminal interface\n- Display available tools and allow you to test them interactively\n\nThe 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.\n\n### Generating the API Client\n\nThe project uses Microsoft Kiota to generate a strongly-typed API client. To regenerate the client:\n\n1. Ensure the HeroApi is running\n2. Navigate to the Mcp directory:\n\n```bash\ncd Mcp\n```\n\n3. Run the Kiota generator:\n\n```bash\ndotnet kiota generate --openapi https://localhost:7255/openapi/v1.json --language csharp --class-name HeroClient --clean-output --additional-data false\n```\n\nThis will regenerate the API client in the `output` directory based on the latest OpenAPI specification.\n\n## ✨ Features\n\n### HeroApi\n\n- **Clean Architecture**: Separation of concerns with Domain, Application, Infrastructure, and WebApi layers\n- **Domain-Driven Design**: Rich domain model with aggregates, entities, and value objects\n- **CQRS Pattern**: Separation of commands and queries using MediatR\n- **Minimal APIs**: Fast and lightweight API endpoints\n- **OpenAPI/Scalar**: Modern, interactive API documentation\n- **EF Core**: Data access with Entity Framework Core\n- **Aspire Dashboard**: For observability and resource orchestration\n- **Strongly Typed IDs**: Using Vogen to prevent primitive obsession\n- **Health Checks**: Monitor application health\n- **Comprehensive Testing**: Architecture tests, domain unit tests, and API integration tests\n\n### HeroMcp\n\n- **Model Context Protocol**: Integration with AI assistants using the MCP standard\n- **AI Tools**: Custom tools for managing heroes, teams, and missions\n- **Generated API Client**: Uses Microsoft Kiota to access the HeroApi\n\n## 📋 API Endpoints\n\nThe HeroApi provides the following endpoints:\n\n- **GET /api/heroes** - Get all heroes\n- **POST /api/heroes** - Create a new hero\n- **GET /api/teams** - Get all teams\n- **GET /api/teams/{id}** - Get a specific team\n- **POST /api/teams** - Create a new team\n- **POST /api/teams/{id}/heroes/{heroId}** - Add a hero to a team\n- **POST /api/teams/{id}/execute-mission** - Execute a mission with a team\n- **POST /api/teams/{id}/complete-mission** - Complete a team's current mission\n\n## 🤖 MCP Tools\n\nThe MCP server provides the following tools to AI assistants:\n\n- **GetHeroes** - Retrieve all heroes from the API\n- **CreateHero** - Create a new hero\n- **GetTeams** - Retrieve all teams from the API\n- **GetTeam** - Get a specific team by ID\n- **CreateTeam** - Create a new team\n- **AddHeroToTeam** - Add a hero to a team\n- **ExecuteMission** - Execute a mission with a team\n- **CompleteMission** - Complete a team's mission\n- **Echo** and **ReverseEcho** - Simple tools for testing the MCP connection\n\n## 🏗️ Project Structure\n\n```\ndotnet-mcp-hero/\n├── Api/                           # Clean Architecture API\n│   ├── src/                       # Source code\n│   │   ├── Application/           # Application layer (use cases)\n│   │   ├── Domain/                # Domain layer (business entities)\n│   │   ├── Infrastructure/        # Infrastructure layer\n│   │   └── WebApi/                # WebApi layer (controllers)\n│   ├── tests/                     # Test projects\n│   │   ├── Architecture.Tests/    # Architecture tests\n│   │   ├── Domain.UnitTests/      # Domain unit tests\n│   │   └── WebApi.IntegrationTests/  # API integration tests\n│   └── tools/                     # Developer tools\n│       ├── AppHost/               # Aspire host\n│       └── MigrationService/      # Database migrations\n├── Mcp/                           # Model Context Protocol server\n│   ├── Program.cs                 # MCP server setup\n│   ├── Tools/                     # MCP tools\n│   │   ├── Echo/                  # Echo tools\n│   │   ├── Heroes/                # Hero management tools\n│   │   └── Teams/                 # Team management tools\n│   └── output/                    # Generated API client\n└── McpHero.sln                    # Solution file\n```\n\n## 📚 Architecture\n\nThis project follows Clean Architecture principles with the following layers:\n\n1. **Domain Layer** - Contains business entities, aggregates, value objects, and domain events\n2. **Application Layer** - Contains business logic, commands, queries, and interfaces\n3. **Infrastructure Layer** - Implements interfaces from the application layer\n4. **WebApi Layer** - Exposes the API endpoints\n\n## 🧪 Testing\n\n- **Architecture Tests** - Verifies that the codebase adheres to clean architecture principles\n- **Domain Unit Tests** - Tests the business logic in isolation\n- **Integration Tests** - Tests the API endpoints against a real database\n\n## 📖 License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## 🙏 Acknowledgements\n\n- [Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html) - Robert C. Martin\n- [Architectural Decision Records](https://adr.github.io/) - For documenting architectural decisions\n- [Model Context Protocol](https://github.com/microsoft/modelcontextprotocol) - Microsoft's protocol for AI tool integration","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanielmackay%2Fdotnet-mcp-hero","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdanielmackay%2Fdotnet-mcp-hero","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanielmackay%2Fdotnet-mcp-hero/lists"}