Pet Care Catalog API MCP Impl

宠物护理目录API和MCP实施

企业级Spring Boot多模块应用 通过REST API和MCP（模型上下文协议）服务器提供宠物护理产品目录服务。

目录

• 概述
• 建筑
• 先决条件
• 快速开始
• 模块结构
• 运行应用程序
• API 文档
• MCP服务器
• 发展
• 部署
• 贡献

概述

该项目展示了一个模块化的Spring Boot架构，通过以下方式展示宠物护理健康包：

• REST API -web/移动应用程序的传统HTTP端点
• MCP服务器 -AI代理集成的模型上下文协议
• 组合模式 -同时运行API和MCP服务器

主要特点

1. 多模块Maven架构
2. 使用Java 21的Spring Boot 3.2.6
3. H2（开发）和PostgreSQL（产品）数据库
4. Liquibase数据库迁移
5. OpenAPI 3.0文档
6. Docker和Docker编写就绪
7. 普罗米修斯指标
8. WireLock用于外部服务模拟
9. 全面的测试覆盖率

建筑

当前体系结构

User Request
    ↓
ChatController (Port 8083)
    ↓
ConversationService
    ↓
Intent Detection
    ↓
McpClientService
    ↓
MCP Server (Port 8082)
    ↓
Tools → PackageService
    ↓
Response

Next Steps - Where Do You Want to Go?
Option A: Add Real AI (OpenAI Integration)

Integrate with OpenAI GPT-4
Add function calling
Make conversations truly intelligent
Let AI decide which MCP tools to use

Option B: Enhanced Multi-Agent System

Activate all 5 agents (Advisor, Research, Recommendation, Comparison, Sales)
Build the orchestrator
Add agent handoff
Implement routing strategies

Option C: Add More Features

Conversation memory/history
Vector database for RAG
Caching layer
WebSocket for streaming responses

Option D: Deploy to Cloud

Create Terraform scripts
GitHub Actions workflows
Deploy to AWS/Azure/GCP
Set up CI/CD

Option E: Build Agentic AI Module

Create catalog-agentic-ai module
Multi-agent orchestration with CrewAI
Complex workflow automation
n8n integration

Option B: Enhanced Multi-Agent System
* Activate all 5 agents (Advisor, Research, Recommendation, Comparison, Sales)
* Build the orchestrator
* Add agent handoff
* Implement routing strategies then 
Option C: Add More Features
* Conversation memory/history
* Vector database for RAG
* Caching layer
* WebSocket for streaming responses then 
Option D: Deploy to Cloud
* Create Terraform scripts
* GitHub Actions workflows
* Deploy to AWS/Azure/GCP
* Set up CI/CD then 
Option A: Add Real AI (OpenAI Integration)
* Integrate with OpenAI GPT-4
* Add function calling
* Make conversations truly intelligent
* Let AI decide which MCP tools to use then Option E: Build Agentic AI Module
   * Create catalog-agentic-ai module
   * Multi-agent orchestration with CrewAI
   * Complex workflow automation
   * n8n integration

模块依赖

catalog-common (Base Layer)
       ↑
       |
catalog-core (Business Logic)
       ↑
       |
    ┌──┴──────────────┬──────────────┐
    |                 |              |
catalog-api    catalog-mcp-server   catalog-api-mcp

技术栈

先决条件

• Java 21+
• Maven 3.9+
• Docker&Docker编写 （基础设施）
• Git

快速开始

1.克隆存储库

git clone https://github.com/yourusername/Pet-Care-Catalog-API-MCP-Impl.git
cd Pet-Care-Catalog-API-MCP-Impl

2.启动基础设施

cd DevOps
chmod +x docker-up.sh docker-down.sh docker-status.sh
./docker-up.sh

这将开始：

• PostgreSQL在端口上 5432
• 端口上的WireLock 9090

3.构建所有模块

cd ..
mvn clean install

4.运行应用程序

选项A:仅限API

cd catalog-api
mvn spring-boot:run

访问权限：http://localhost:8080

选项B：仅限MCP服务器

cd catalog-mcp-server
mvn spring-boot:run

访问权限：http://localhost:8081

方案C：组合式（API+MCP）

cd catalog-api-mcp
mvn spring-boot:run

访问：8080上的API，8081上的MCP

模块结构

目录通用

共享DTO、常量、枚举、异常和DAO接口

包裹: com.jk.labs.springai.petcare

关键部件：

• dto/ -数据传输对象
• enums/ -PetType、年龄组、护理级别、服务类别
• exception/ -自定义例外
• constants/ -应用程序常量
• util/ -公用事业类别

目录核心

核心业务逻辑、JPA实体、存储库实现

包裹: com.jk.labs.springai.petcare

关键部件：

• entity/ -JPA实体
• repository/ -Spring数据JPA存储库
• service/impl/ -业务逻辑实现
• facade/ -用于复杂操作的立面层
• mapper/ -MapStruct地图绘制器
• db/changelog/ -液基迁移

目录api

REST API控制器和OpenAPI文档

包裹: com.jk.labs.springai.petcare

关键部件：

• controller/ -REST控制器
• config/ -API配置（OpenAPI，安全）
• exception/ -全局异常处理程序

终点：

• GET /api/v1/packages -列出所有包
• GET /api/v1/packages/{code} -获取包裹详细信息
• POST /api/v1/recommendations -获取套餐推荐
• POST /api/v1/packages/compare -比较软件包

目录mcp服务器

使用AI代理工具实现MCP服务器

包裹: com.jk.labs.springai.petcare

关键部件：

• mcp/ -MCP协议实现
• mcp/tools/ -MCP工具实现
• mcp/schema/ -MCP协议模式

MCP工具：

• search_packages -搜索包裹
• get_package_details -获取详细的包裹信息
• recommend_package -基于人工智能的推荐
• compare_packages -并排比较
• calculate_savings -计算成本节约
• get_services -列出可用服务

目录api mcp

运行API和MCP服务器的组合模块

API 文档

Swagger用户界面（开发）

在开发模式下运行时，访问交互式API文档：

统一资源定位符: http://localhost:8080/swagger-ui.html

API请求示例

获取所有套餐

curl -X GET http://localhost:8080/api/v1/packages

按代码获取包

curl -X GET http://localhost:8080/api/v1/packages/DOG_ACTIVE_CARE

获取推荐

curl -X POST http://localhost:8080/api/v1/recommendations \
  -H "Content-Type: application/json" \
  -d '{
    "petType": "DOG",
    "ageYears": 3,
    "ageMonths": 6,
    "needsDentalCare": true
  }'

MCP服务器

什么是MCP？

模型上下文协议（MCP）使AI代理能够与外部系统进行交互。我们的MCP服务器公开了AI代理可以使用的宠物护理目录工具。

MCP工具使用

列出可用工具

curl -X POST http://localhost:8081/mcp/tools

执行工具

curl -X POST http://localhost:8081/mcp/tools/search_packages \
  -H "Content-Type: application/json" \
  -d '{
    "petType": "DOG",
    "ageGroup": "ADULT"
  }'

与AI代理集成

MCP服务器可以与以下设备集成：

• 克劳德桌面
• 自定义AI代理
• LangChain应用
• CrewAI多智能体系统

发展

数据库访问

H2控制台 （发展）

• 网址：http://localhost:8080/h2-控制台
• JDBC网址： jdbc:h2:mem:petcare_catalog
• 用户名： sa
• 密码：（空）

PostgreSQL （生产）

• 主机：本地主机：5432
• 数据库：petcare_catalog
• 用户名：petcare_user
• 密码：petcare_密码

运行测试

# Run all tests
mvn test

# Run tests for specific module
cd catalog-core
mvn test

# Run integration tests
mvn verify

代码质量

# Check code style
mvn checkstyle:check

# Run static analysis
mvn pmd:check

热重新加载

mvn spring-boot:run -Dspring-boot.run.fork=false

Docker部署

构建Docker镜像

# Build API image
docker build -f catalog-api/Dockerfile -t petcare-catalog-api:latest .

# Build MCP image
docker build -f catalog-mcp-server/Dockerfile -t petcare-catalog-mcp:latest .

Docker编写部署

cd DevOps
docker-compose -f docker-compose-all.yml up -d

Kubernetes部署

kubectl apply -f k8s/

监控

健康检查

• API: http://localhost:8080/actuator/health
• 主控程序: http://localhost:8081/actuator/health

普罗米修斯指标

• API: http://localhost:8080/actuator/prometheus
• 主控程序: http://localhost:8081/actuator/prometheus

使用WireLock进行测试

WireMock服务器在端口9090上运行，并为外部服务提供模拟响应。

管理用户界面: http://localhost:9090/\_\_admin

测试模拟端点:

curl http://localhost:9090/payment/health
curl -X POST http://localhost:9090/payment/process

可用包

由以下材料制成❤️ 宠物和它们的人类

______________________________________________________________________

推荐代理模块

概述

这 推荐代理人 是宠物护理多代理系统的一部分。它分析宠物的概况和护理需求，以推荐最合适的健康套餐。

建筑

┌─────────────────────────────────────────────────────────────────┐
│                    Recommendation Agent                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  RecommendationController                                        │
│         │                                                        │
│         ▼                                                        │
│  RecommendationService                                           │
│         │                                                        │
│    ┌────┴────┐                                                   │
│    │         │                                                   │
│    ▼         ▼                                                   │
│  Research   MCP Client                                           │
│  Service    Service                                              │
│    │         │                                                   │
│    ▼         ▼                                                   │
│  Research   MCP Server                                           │
│  Agent      (recommend_package tool)                             │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

特性

1.完整推荐

• 全面的宠物档案分析
• 考虑年龄、健康需求、牙科护理、慢性病
• 返回主要推荐+备选方案
• 提供推理和关键优势

2.快速推荐

• 最小输入（宠物类型+年龄）
• 快速响应简单查询

3.细化推荐

• 用其他上下文更新建议
• 基于会话的连续性

文件结构

recommendation/
├── config/
│   └── RecommendationConfig.java       # Agent configuration properties
├── controller/
│   └── RecommendationController.java   # REST API endpoints
├── model/
│   ├── RecommendationRequest.java      # Input model
│   └── RecommendationResponse.java     # Output model with PackageRecommendation
├── service/
│   ├── RecommendationService.java      # Service interface
│   └── impl/
│       └── RecommendationServiceImpl.java  # Core recommendation logic
└── resources/
    └── application-recommendation.yml  # Configuration

API终点

样品申请

curl -X POST http://localhost:8083/api/v1/agents/recommendation/recommend \
  -H "Content-Type: application/json" \
  -d '{
    "petType": "DOG",
    "petName": "Buddy",
    "ageYears": 3,
    "ageMonths": 6,
    "needsDentalCare": true,
    "budgetPreference": "STANDARD"
  }'

样品响应

{
  "agentName": "Recommendation Agent",
  "primaryRecommendation": {
    "packageCode": "DOG_GROWNUP_CARE_PLUS",
    "packageName": "Grown-Up Care Plus",
    "description": "Comprehensive adult dog care with dental coverage",
    "monthlyPrice": 54.99,
    "includedServices": ["Wellness Exams", "Vaccinations", "Dental Cleaning"],
    "matchScore": 0.92
  },
  "alternatives": [
    {
      "packageCode": "DOG_GROWNUP_CARE",
      "packageName": "Grown-Up Care",
      "description": "Standard adult dog care package",
      "monthlyPrice": 39.99,
      "includedServices": ["Wellness Exams", "Vaccinations"],
      "matchScore": 0.78
    }
  ],
  "reasoning": "Based on your adult dog Buddy, I recommend the Grown-Up Care Plus package...",
  "keyBenefits": [
    "Tailored for adult pets",
    "Includes 8 essential services",
    "Dental coverage included"
  ],
  "confidence": 0.85,
  "recommendationType": "BEST_FIT",
  "suggestComparison": true,
  "nextAgentSuggestion": "Comparison Agent"
}

与其他代理集成

使用研究代理

推荐代理在做出推荐之前调用研究代理收集包数据。

移交给比较代理

当多个包具有高匹配分数时，建议使用比较代理。

移交给销售代理

接受推荐后，可以交给销售代理进行采购流程。

配置

agent:
  recommendation:
    enabled: true
    model: gpt-4o-mini
    temperature: 0.5
    min-confidence-threshold: 0.6
    max-alternatives: 3

此代理之后的后续步骤

1. 比较剂 -并排比较多个包
2. 顾问代理 -一般宠物护理问答
3. 销售代理 -处理购买转换
4. 编排器 -基于意图的代理之间的路由

______________________________________________________________________

代理进度跟踪器

比较代理模块

概述

这 比较剂 是宠物护理多代理系统的一部分。它提供了健康套餐的详细并排比较，帮助用户做出明智的决定。

建筑

┌─────────────────────────────────────────────────────────────────┐
│                     Comparison Agent                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ComparisonController                                            │
│         │                                                        │
│         ▼                                                        │
│  ComparisonService                                               │
│         │                                                        │
│    ┌────┴────┐                                                   │
│    │         │                                                   │
│    ▼         ▼                                                   │
│  Research   MCP Client                                           │
│  Service    Service                                              │
│    │         │                                                   │
│    ▼         ▼                                                   │
│  Research   MCP Server                                           │
│  Agent      (get_package_details, compare_packages tools)        │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

特性

1.全面比较

• 比较2-4个包
• 特征矩阵（并排）
• 价格比较与节省分析
• 带推理的获奖者推荐
• 突出关键差异

2.快速比较

• 快速比较两个包裹
• 所需输入最少

3.重点比较

• 指定要关注的功能（牙科、价格、疫苗接种）
• 基于优先级的加权评分

4.宠物特定比较

• 考虑宠物类型和年龄
• 为特定宠物推荐最佳包装

文件结构

comparison/
├── config/
│   └── ComparisonConfig.java         # Agent configuration properties
├── controller/
│   └── ComparisonController.java     # REST API endpoints
├── model/
│   ├── ComparisonRequest.java        # Input model
│   └── ComparisonResponse.java       # Output with all comparison details
├── service/
│   ├── ComparisonService.java        # Service interface
│   └── impl/
│       └── ComparisonServiceImpl.java    # Core comparison logic
└── resources/
    └── application-comparison.yml    # Configuration

API终点

样品申请

curl -X POST http://localhost:8083/api/v1/agents/comparison/compare \
  -H "Content-Type: application/json" \
  -d '{
    "packageCodes": ["DOG_GROWNUP_CARE", "DOG_GROWNUP_CARE_PLUS", "DOG_ELDER_CARE"],
    "petType": "DOG",
    "petAgeYears": 5,
    "priorities": ["dental", "value"],
    "maxBudget": 60.00
  }'

样品响应

{
  "agentName": "Comparison Agent",
  "packages": [
    {
      "packageCode": "DOG_GROWNUP_CARE",
      "packageName": "Grown-Up Care",
      "monthlyPrice": 39.99,
      "includesDental": false,
      "valueScore": 0.8
    },
    {
      "packageCode": "DOG_GROWNUP_CARE_PLUS",
      "packageName": "Grown-Up Care Plus",
      "monthlyPrice": 54.99,
      "includesDental": true,
      "valueScore": 0.85
    }
  ],
  "featureMatrix": {
    "features": {
      "Monthly Price": { "DOG_GROWNUP_CARE": "$39.99", "DOG_GROWNUP_CARE_PLUS": "$54.99" },
      "Dental Coverage": { "DOG_GROWNUP_CARE": "✗", "DOG_GROWNUP_CARE_PLUS": "✓" }
    }
  },
  "priceComparison": {
    "cheapestPackage": "DOG_GROWNUP_CARE",
    "mostExpensivePackage": "DOG_GROWNUP_CARE_PLUS",
    "priceDifference": 15.00,
    "bestValuePackage": "DOG_GROWNUP_CARE_PLUS"
  },
  "winner": {
    "packageCode": "DOG_GROWNUP_CARE_PLUS",
    "packageName": "Grown-Up Care Plus",
    "winReason": "Best overall balance considering your priorities: dental, value",
    "advantages": ["Includes dental coverage", "Excellent value for money"],
    "disadvantages": ["Higher price point than alternatives"],
    "bestForBudget": "DOG_GROWNUP_CARE",
    "bestForCoverage": "DOG_GROWNUP_CARE_PLUS",
    "bestForValue": "DOG_GROWNUP_CARE_PLUS"
  },
  "summary": "Comparing 2 packages: Grown-Up Care, Grown-Up Care Plus...",
  "keyDifferences": [
    "Price range: $39.99 to $54.99 per month",
    "1 of 2 packages include dental coverage"
  ],
  "confidence": 0.85,
  "nextAgentSuggestion": "Sales Agent"
}

响应组件

包装比较

正在比较的每个包裹的详细信息。

特征矩阵

并排网格显示所有软件包的功能。

价格比较

价格分析包括最便宜、最贵和最划算。

比较赢家

推荐包含推理、优势和类别获奖者的套餐。

与其他代理集成

由呼叫

• 推荐代理人 -当发现多个良好匹配时
• 顾问代理 -当用户想要比较选项时

呼叫

• 研究代理 -如果MCP发生故障，收集包数据
• MCP客户端 -有关包裹详细信息

放手给

• 销售代理 -用户决定包裹后

配置

agent:
  comparison:
    enabled: true
    max-packages-to-compare: 4
    min-packages-to-compare: 2
    price-weight: 0.3
    coverage-weight: 0.4
    value-weight: 0.3

______________________________________________________________________

代理进度跟踪器

______________________________________________________________________

后续步骤

1. 顾问代理 -一般宠物护理问答和切入点
2. 销售代理 -处理采购流程
3. 编排器 -基于意图的代理之间的路由

下一个特工？ 准备构建下一个代理。你更喜欢哪一种？

顾问代理-一般宠物护理问答，对话切入点 销售代理-推荐/比较后处理采购流程