AI导哈

订单管理MCP服务器

一个基于.NET 6和C#构建的完整MCP服务器实现，通过自然语言查询使AI助手能够与业务数据交互。

  • by SpicyfyVentures
  • C#
  • 本地部署
  • 更新于
在 GitHub 查看 SpicyfyVentures/DotNetMCP

使用说明

客户订单管理MCP服务器

一个基于.NET 6和C#构建的全面模型上下文协议（MCP）服务器实现。该项目展示了如何创建一个可投入生产的MCP服务器，使AI助手能够通过自然语言查询与业务数据进行交互。

概述

模型上下文协议是一项开放标准，它允许大型语言模型安全地访问外部数据源并执行函数。此实现提供了一个完整的客户订单管理系统，可以通过人工智能助手使用自然语言进行查询。

关键特性

  • 完整的MCP服务器实现，包含RESTful API接口
  • Entity Framework Core 与内存数据库支持的集成
  • 七款全面的订单管理操作工具
  • API密钥认证用于安全访问控制
  • 可选使用Microsoft Identity平台进行OAuth 2.0身份验证
  • 使用Docker容器化实现轻松部署
  • 全面的健康监测与记录
  • Swagger API开发和测试文档

系统架构

服务器采用三层架构模式：

AI Assistant (MCP Client) → MCP Server (.NET 6) → Database (In-Memory/SQL Server)

MCP客户端通过HTTP端点与服务器进行通信，服务器随后与数据库层交互以检索和操作订单数据。

数据库设计

该系统使用了四个具有适当关系的核心实体：

  • 顾客存储客户信息，包括联系方式和注册日期
  • 订单包含订单记录，附有状态追踪和总金额
  • 订单详情代表订单中的单个条目
  • 产品维护包含定价和库存信息的产品目录

可用工具

服务器提供了七种不同的订单管理工具：

  1. 获取客户信息 - 通过ID或电子邮件地址检索完整的客户信息
  2. 获取订单详情 - 返回完整的订单信息，包括所有商品项
  3. 搜索客户订单 - 按客户姓名或电子邮件分页搜索订单
  4. 获取订单状态 - 提供订单状态和模拟追踪信息
  5. 检查产品可用性 - 显示当前库存水平和可用状态
  6. 获取最近订单 - 列出最近订单，并可选择状态过滤
  7. 创建客户 - 将新客户添加到系统中

入门指南

先决条件

  • .NET 6.0 SDK 或更高版本
  • Git用于版本控制
  • 可选：使用Docker进行容器化部署
  • 可选：用于生产数据库的 SQL Server

安装

  1. 克隆仓库：
git clone https://github.com/SpicyfyVentures/DotNetMCP.git
cd DotNetMCP
  1. 恢复 NuGet 包：
dotnet restore
  1. 构建项目：
dotnet build
  1. 运行应用程序：
dotnet run

服务器将在 http://localhost:5000 默认情况下。

验证

测试服务器健康状况：

curl http://localhost:5000/health

列出可用工具：

curl http://localhost:5000/mcp/tools

API 使用

客户信息检索

通过电子邮件检索客户详细信息：

curl -X POST "http://localhost:5000/mcp/tools/GetCustomerInfo" \
     -H "Content-Type: application/json" \
     -H "X-API-Key: your-api-key-here" \
     -d '"alice@example.com"'

按ID检索客户详细信息：

curl -X POST "http://localhost:5000/mcp/tools/GetCustomerInfo" \
     -H "Content-Type: application/json" \
     -H "X-API-Key: your-api-key-here" \
     -d '"1"'

注： 包括 X-API-Key 仅在启用API密钥认证时显示标题。

订单管理

获取详细的订单信息：

curl -X POST "http://localhost:5000/mcp/tools/GetOrderDetails" \
     -H "Content-Type: application/json" \
     -d '1'

搜索客户订单：

curl -X POST "http://localhost:5000/mcp/tools/SearchCustomerOrders" \
     -H "Content-Type: application/json" \
     -d '{"customerSearch": "Alice", "limit": 10}'

库存管理

检查产品可用性：

curl -X POST "http://localhost:5000/mcp/tools/CheckProductAvailability" \
     -H "Content-Type: application/json" \
     -d '"Laptop"'

客户开发/客户创造

添加新客户：

curl -X POST "http://localhost:5000/mcp/tools/CreateCustomer" \
     -H "Content-Type: application/json" \
     -d '{"name": "John Doe", "email": "john@example.com", "phone": "555-0199"}'

配置

数据库配置

该应用程序默认使用内存数据库进行开发。若要在生产环境中部署并使用 SQL Server，请更新连接字符串 appsettings.json：

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=localhost;Database=CustomerOrderDB;Trusted_Connection=true;MultipleActiveResultSets=true"
  }
}

API密钥认证

服务器支持API密钥认证以实现安全访问控制。要启用API密钥认证，请更新您的 appsettings.json:

{
  "ApiKey": {
    "Enabled": true,
    "HeaderName": "X-API-Key",
    "ValidApiKeys": [
      "your-secure-api-key-here",
      "another-api-key-for-different-client"
    ]
  }
}

重要的安全注意事项：

  • 为每个客户端生成强大且唯一的API密钥
  • 安全地存储API密钥，切勿将其提交到版本控制系统中
  • 在生产环境中使用环境变量或安全的配置提供程序
  • 定期轮换API密钥

OAuth 2.0 认证（替代方案）

要启用OAuth 2.0身份验证（而非API密钥），请配置Azure Active Directory设置：

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",
    "Audience": "api://your-api-identifier"
  }
}

Docker 部署

构建形象

创建一个Docker镜像：

docker build -t customer-order-mcp .

运行容器

启动容器：

docker run -p 5000:8080 customer-order-mcp

该应用程序将在 http://localhost:5000。

样本数据

应用程序在启动时会自动填充示例数据：

顾客：

  • 爱丽丝·约翰逊（alice@example.com）
  • 鲍勃·史密斯（bob@example.com）
  • 查理·布朗（charlie@example.com）

产品：

  • 笔记本电脑：999.99美元（库存15台）
  • 无线鼠标：29.99美元（库存50件）
  • 机械键盘：89.99美元（库存25件）
  • 4K显示器：399.99美元（库存8台）

订单：

  • 订单#1：爱丽丝已完成的订单（笔记本电脑+键盘）
  • 订单#2：鲍勃的处理顺序（显示器+鼠标）

自然语言集成

当与人工智能助手集成时，服务器可以处理诸如以下的对话查询：

  • “给我看看爱丽丝·约翰逊的订单历史”
  • “订单号1的订单状态如何？”
  • “库存里还有笔记本电脑吗？”
  • “列出过去一周的所有订单”
  • “为简·史密斯创建一个新的客户账户”

开发指南

项目结构

CustomerOrderMCP/
├── Data/
│   └── OrderDbContext.cs          # Entity Framework context
├── Models/
│   ├── Customer.cs                # Customer entity model
│   ├── Order.cs                   # Order entity model
│   ├── OrderDetail.cs             # Order detail entity model
│   └── Product.cs                 # Product entity model
├── Tools/
│   └── OrderManagementTools.cs    # MCP tool implementations
├── Examples/
│   ├── mcp-client-config.json     # Sample MCP client configuration
│   └── test-queries.md            # Example queries and tests
├── Program.cs                     # Application entry point
├── Dockerfile                     # Docker configuration
└── README.md                      # Project documentation

添加新工具

为服务器添加额外工具以进行扩展：

  1. 向（某物）添加一个新方法 OrderManagementTools 班级；阶级；类别
  2. 用……装饰该方法 [Description] 属性
  3. 在（相应系统/环境中）创建一个对应的HTTP端点 Program.cs
  4. 更新工具列表端点以包含新工具
  5. 测试新功能

错误处理

服务器实现了全面的错误处理机制：

  • 对所有参数进行输入验证
  • 优雅地处理数据库错误
  • 用于调试的结构化日志记录
  • 用户友好的错误提示
  • 正确的HTTP状态码

生产方面的考虑因素

安全

  • 输入消毒可防止注入攻击
  • OAuth 2.0集成以实现安全认证
  • 限制速率功能以防止滥用
  • 为合规要求进行审计日志记录
  • 安全的错误消息，不泄露内部细节

演出

  • 在整个代码库中执行异步操作
  • Entity Framework 查询优化
  • 数据库连接池以提高效率
  • 频繁访问数据的响应缓存
  • 适当的资源处置模式

监测

  • 负载均衡器的健康检查端点
  • 带可配置级别的结构化日志记录
  • 应用程序指标收集
  • 数据库连接监控
  • 性能计数器集成

部署选项

Azure 容器应用

部署到 Azure 容器应用以实现无服务器扩展：

az containerapp create \
  --name customer-order-mcp \
  --resource-group your-resource-group \
  --image your-registry.azurecr.io/customer-order-mcp:latest \
  --target-port 8080 \
  --ingress external \
  --min-replicas 1 \
  --max-replicas 10

环境变量

为生产环境配置以下环境变量：

  • ASPNETCORE_ENVIRONMENT设置为“生产”
  • ConnectionStrings__DefaultConnection数据库连接字符串
  • AzureAd__TenantIdAzure AD 租户标识符
  • AzureAd__ClientIdAzure AD 应用程序标识符

贡献

欢迎并感谢您的贡献。请遵循以下指南：

  1. 为该仓库创建一个分支并建立一个功能分支
  2. 编写清晰、有文档记录的代码，并附上适当的测试
  3. 遵循现有的代码风格和规范
  4. 更新文档以包含任何新功能
  5. 提交一个包含清晰更改说明的拉取请求

许可证

此项目遵循MIT许可协议。有关完整条款和条件，请参阅LICENSE文件。

支持与资源

如需咨询问题或报告问题，请在GitHub上创建一个议题，并提供有关您的问题或功能请求的详细信息。

相关 MCP