.NET Hero API with Model Context Protocol

基于 .NET 的超级英雄管理系统，包含一个 Clean Architecture API 后端和用于 AI 助手集成的 Model Context Protocol (MCP) 服务器。

🎯 项目概述

该项目展示了如何使用 Clean Architecture 原则构建现代 .NET 应用程序，并通过 Model Context Protocol (MCP) 将其与 AI 助手功能集成。它由两大部分组成：

1. HeroApi - 使用 Clean Architecture 原则构建的 .NET 9 WebAPI
2. HeroMcp - 提供与 API 交互的 AI 工具能力的 Model Context Protocol 服务器

领域

该应用程序围绕一个超级英雄领域模型构建，包括以下内容：

• Heroes - 拥有超能力、名称、别名和力量等级的角色
• Teams - 可以执行任务的英雄组
• Missions - 团队可以执行并完成的任务

🚀 快速开始

先决条件

• .NET 9 SDK
• Docker（用于数据库）
• VS Code 或其他 .NET IDE

运行 Hero API

1. 进入 AppHost 目录：

cd Api/tools/AppHost

2. 使用 .NET CLI 运行应用程序：

dotnet run

这将：

• 启动用于数据库的 SQL Server 容器
• 运行迁移以设置数据库模式
• 在 https://localhost:7255 上启动 HeroApi

3. 在浏览器中打开 https://localhost:7255/scalar/v1 查看 API 文档

运行 MCP 服务器

1. 进入 Mcp 目录：

cd Mcp

2. 运行 MCP 服务器：

dotnet run

这将启动 MCP 服务器，提供与 HeroApi 交互的工具。

运行 MCP Inspector

MCP Inspector 是一个用于直接测试您的 MCP 服务器的有用工具。它允许您检查可用工具并进行交互式调用。

1. 进入 Mcp 目录：

cd Mcp

2. 使用以下命令运行 MCP Inspector：

npx @modelcontextprotocol/inspector dotnet run

这将：

• 启动 MCP 服务器
• 在终端界面中启动 MCP Inspector
• 显示可用工具并允许您交互式测试它们

Inspector 将显示来自您的 MCP 服务器的所有可用工具，并提供简单的接口来调用它们并查看其响应，这对开发和调试非常有用。

生成 API 客户端

该项目使用 Microsoft Kiota 生成强类型的 API 客户端。要重新生成客户端：

1. 确保 HeroApi 正在运行
2. 进入 Mcp 目录：

cd Mcp

3. 运行 Kiota 生成器：

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

这将在 output 目录中根据最新的 OpenAPI 规范重新生成 API 客户端。

✨ 功能

HeroApi

• Clean Architecture: 包含 Domain、Application、Infrastructure 和 WebApi 层的关注点分离
• Domain-Driven Design: 包含聚合、实体和值对象的丰富领域模型
• CQRS Pattern: 使用 MediatR 分离命令和查询
• Minimal APIs: 快速轻量级的 API 端点
• OpenAPI/Scalar: 现代、交互式的 API 文档
• EF Core: 使用 Entity Framework Core 进行数据访问
• Aspire Dashboard: 用于可观测性和资源编排
• Strongly Typed IDs: 使用 Vogen 防止原始类型痴迷
• Health Checks: 监控应用程序健康状态
• 全面测试: 架构测试、领域单元测试和 API 集成测试

HeroMcp

• Model Context Protocol: 使用 MCP 标准与 AI 助手集成
• AI Tools: 管理英雄、团队和任务的自定义工具
• Generated API Client: 使用 Microsoft Kiota 访问 HeroApi

📋 API 端点

HeroApi 提供以下端点：

• GET /api/heroes - 获取所有英雄
• POST /api/heroes - 创建新英雄
• GET /api/teams - 获取所有团队
• GET /api/teams/{id} - 获取特定团队
• POST /api/teams - 创建新团队
• POST /api/teams/{id}/heroes/{heroId} - 将英雄添加到团队
• POST /api/teams/{id}/execute-mission - 使用团队执行任务
• POST /api/teams/{id}/complete-mission - 完成团队当前任务

🤖 MCP 工具

MCP 服务器为 AI 助手提供以下工具：

• GetHeroes - 从 API 检索所有英雄
• CreateHero - 创建新英雄
• GetTeams - 从 API 检索所有团队
• GetTeam - 按 ID 获取特定团队
• CreateTeam - 创建新团队
• AddHeroToTeam - 将英雄添加到团队
• ExecuteMission - 使用团队执行任务
• CompleteMission - 完成团队任务
• Echo 和 ReverseEcho - 用于测试 MCP 连接的简单工具

🏗️ 项目结构

dotnet-mcp-hero/
├── Api/                           # Clean Architecture API
│   ├── src/                       # 源代码
│   │   ├── Application/           # 应用层（用例）
│   │   ├── Domain/                # 领域层（业务实体）
│   │   ├── Infrastructure/        # 基础设施层
│   │   └── WebApi/                # WebApi 层（控制器）
│   ├── tests/                     # 测试项目
│   │   ├── Architecture.Tests/    # 架构测试
│   │   ├── Domain.UnitTests/      # 领域单元测试
│   │   └── WebApi.IntegrationTests/  # API 集成测试
│   └── tools/                     # 开发者工具
│       ├── AppHost/               # Aspire 主机
│       └── MigrationService/      # 数据库迁移
├── Mcp/                           # Model Context Protocol 服务器
│   ├── Program.cs                 # MCP 服务器设置
│   ├── Tools/                     # MCP 工具
│   │   ├── Echo/                  # 回声工具
│   │   ├── Heroes/                # 英雄管理工具
│   │   └── Teams/                 # 团队管理工具
│   └── output/                    # 生成的 API 客户端
└── McpHero.sln                    # 解决方案文件

📚 架构

该项目遵循 Clean Architecture 原则，包含以下层：

1. Domain Layer - 包含业务实体、聚合、值对象和领域事件
2. Application Layer - 包含业务逻辑、命令、查询和接口
3. Infrastructure Layer - 实现应用层中的接口
4. WebApi Layer - 暴露 API 端点

🧪 测试

• 架构测试 - 验证代码库是否遵循 Clean Architecture 原则
• 领域单元测试 - 隔离测试业务逻辑
• 集成测试 - 对真实数据库测试 API 端点

📖 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

🙏 致谢

• Clean Architecture - Robert C. Martin
• Architectural Decision Records - 用于记录架构决策
• Model Context Protocol - Microsoft 的 AI 工具集成协议