AI导哈

卡牌管理平台

MagicCardVault是一款基于.NET 8的全栈魔法风云会卡牌管理平台，提供JWT安全的REST API、双重持久化策略、本地LLM集成以及多平台客户端应用。

  • by Phosky71
  • C#
  • 本地部署
  • 更新于
在 GitHub 查看 Phosky71/ProyectoFinal-EV1-BigData

使用说明

MagicCardVault

全栈魔法：用构建的收集卡管理平台。NET 8，具有JWT安全的REST API、双持久性策略、与本地LLM的MCP协议集成以及多平台客户端应用程序。

目录

概述

MagicCardVault是一个后端优先应用程序，它公开了一个RESTful API，用于管理从Kaggle数据集加载的Magic:TheGathering卡数据。它实现了一个干净的分层架构，具有可插拔的持久性（MySQL或内存中）、基于JWT的身份验证，以及由模型上下文协议（MCP）和本地托管的LLM支持的AI层 LM 工作室.

开箱即用提供了三个客户端前端：Console应用程序、WPF桌面应用程序和跨平台应用程序。NET MAUI移动/桌面应用程序。

建筑

┌──────────────────────────────────────────────────┐
│                  Client Layer                    │
│   ConsoleApp  │  WPFApp  │  MAUIApp              │
└───────────────────────┬──────────────────────────┘
                        │ HTTP / JWT
┌───────────────────────▼──────────────────────────┐
│                   REST API (.NET 8)              │
│  AuthController  │  DataController  │  MCPController │
├──────────────────────────────────────────────────┤
│              Business / Service Layer            │
│   JwtService  │  McpClientService  │  KaggleDataLoader │
├──────────────────────────────────────────────────┤
│               MCP Layer (JSON-RPC)               │
│   MagicCardMcpServer  ◄──►  McpClientService     │
│              (LM Studio / Local LLM)             │
├──────────────────────────────────────────────────┤
│              Persistence Layer                   │
│   PersistenceManager (Open/Close Pattern)        │
│   MemoryRepository  │  MySQLRepository           │
└──────────────────────────────────────────────────┘

持久层遵循 开闭原则：在MySQL和内存存储之间切换只需要更改配置，不需要修改代码。

特征

  • JWT身份验证 --基于无状态令牌的身份验证，具有可配置的颁发者、受众和过期时间。
  • 双重坚持 --通过配置在运行时在MySQL和内存存储之间切换。
  • Kaggle数据集集成 --启动时自动从本地CSV加载MTG卡数据。
  • MCP协议（JSON-RPC） --标准模型上下文协议架构，具有专用的MCP服务器公开工具和编排LLM交互的MCP客户端。
  • 本地LLM支持 -与LM Studio集成，用于完全离线的AI供电卡查询，不需要外部API密钥。
  • Swagger/OpenAPI -开发模式下提供交互式API文档。
  • 多平台客户端 --控制台、WPF和。NET MAUI客户端共享相同的后端合约。
  • CORS支持 --在开发过程中配置了广泛的兼容性。

技术栈

层 技术
运行时 。净值8
API框架 ASP。NET核心
身份验证 JWT承载（Microsoft.AspNetCore.Authentication.JwtBearer）
ORM/DB MySQL（MySQL连接器）
人工智能协议 模型上下文协议（MCP）——JSON-RPC
本地LLM LM Studio（OpenAI兼容端点）
API文档 摇摆器/摇摆带扣
桌面用户界面 WPF（.NET 8）
移动/桌面 。毛伊网
数据来源 Kaggle MTG卡数据集（CSV）

项目结构

MagicCardVault/
├── config/                        # Environment and deployment config files
├── src/
│   ├── Backend/
│   │   ├── API/
│   │   │   ├── Auth/              # JwtService
│   │   │   ├── Controllers/       # AuthController, DataController, MCPController
│   │   │   ├── Properties/
│   │   │   ├── Services/          # KaggleDataLoader, ConfigurationService
│   │   │   ├── Program.cs
│   │   │   └── appsettings.json
│   │   ├── MCP/
│   │   │   ├── Client/            # McpClientService (LLM orchestrator)
│   │   │   └── Server/            # MagicCardMcpServer (tool definitions)
│   │   └── Persistence/
│   │       ├── Interfaces/        # IRepository<T>
│   │       ├── Memory/            # MemoryRepository
│   │       ├── Models/            # Card model
│   │       ├── MySQL/             # MySQLRepository
│   │       └── PersistenceManager.cs
│   └── Frontend/
│       ├── ConsoleApp/            # CLI client
│       ├── WPFApp/                # Windows desktop client
│       └── MAUIApp/               # Cross-platform mobile/desktop client
└── ProyectoFinal.sln

入门指南

先决条件

配置

编辑 src/Backend/API/appsettings.json （或使用环境变量/用户机密）：

{
  "Jwt": {
    "Secret": "YOUR_SECRET_KEY_MIN_32_CHARACTERS",
    "Issuer": "MagicCardVault",
    "Audience": "MagicCardVaultUsers",
    "ExpirationMinutes": "60"
  },
  "Persistence": {
    "Mode": "Memory"
  },
  "ConnectionStrings": {
    "MySQL": "Server=localhost;Database=magic_card_vault;User=root;Password=yourpassword;"
  },
  "Kaggle": {
    "DatasetPath": "Data/cards.csv"
  }
}

持久模式：

  • Memory --不需要数据库。数据在进程中存储，并在重新启动时重置。
  • MySQL --需要一个正在运行的MySQL实例，其连接字符串已在上面配置。

LM工作室设置：

  1. 下载并安装 LM 工作室.
  2. 加载任何与OpenAI兼容的模型。
  3. 启动本地服务器（默认： http://localhost:1234).
  4. MCP客户端将自动连接到它。

运行API

cd src/Backend/API
dotnet run

Swagger用户界面将在 http://localhost:53620 在开发模式中。

运行客户端

慰问：

cd src/Frontend/ConsoleApp
dotnet run

WPF：

cd src/Frontend/WPFApp
dotnet run

毛伊：

cd src/Frontend/MAUIApp
dotnet run

对于MAUI，请确保安装了适当的工作负载： dotnet workload install maui

API 参考

所有受保护的端点都需要 Bearer 令牌在 Authorization 头球

认证

方法 端点 描述 身份验证
职位 /api/auth/login 获取JWT令牌 否
职位 /api/auth/register 注册新用户 否

数据（卡片）

方法 端点 描述 身份验证
得到 /api/data/cards 列出所有卡片 是
得到 /api/data/cards/{id} 凭身份证取卡 是
职位 /api/data/cards 创建新卡 是
PUT /api/data/cards/{id} 更新卡片 是
删除 /api/data/cards/{id} 删除卡片 是

MCP/AI

方法 端点 描述 身份验证
职位 /api/mcp/query 向LLM发送自然语言查询 是

在开发模式下运行时，可通过Swagger在API根目录下获得完整的交互式文档。

MCP和LLM集成

MagicCardVault实现了 模型上下文协议（MCP） 使用JSON-RPC架构：

  • MCP服务器(MagicCardMcpServer) --公开由真实持久层支持的工具（例如，搜索卡片、获取卡片详细信息）。
  • MCP客户端(McpClientService) --充当主持人/协调人。它向本地LLM发送用户提示（通过LM Studio），从模型接收工具调用请求，在MCP服务器上执行这些请求，并返回最终响应。

这种设计使LLM完全离线，并且不需要外部API密钥。任何与OpenAI聊天完成API格式兼容的模型都可以使用。

持久模式

持久层使用 开闭原则 通过a PersistenceManager 它包含对这两个实现的引用，并公开当前活动的 IRepository<Card>:

PersistenceManager
├── MemoryRepository  (IRepository<Card>)
└── MySQLRepository   (IRepository<Card>)

活动存储库在启动时根据 Persistence:Mode 配置值。切换模式只需要更改配置——这两个实现总是在DI容器中注册的。

贡献

  1. 分叉存储库
  2. 创建要素分支： git checkout -b feature/my-feature
  3. 提交您的更改： git commit -m 'feat: add my feature'
  4. 推到分支： git push origin feature/my-feature
  5. 打开拉取请求

请跟随 约定式提交 用于提交消息。

许可证

该项目根据MIT许可证获得许可。请参阅 许可证 文件以获取详细信息。

相关 MCP