Mock Ecom MCP Server

模拟电子商务MCP服务器

通用型 模拟MCP（模型上下文协议）服务器 建于 Java 21+Spring Boot 3.3.6+Spring AI 1.0.0-M6.

一个使用此服务器的AI聊天机器人可以为跨平台的用户提供服务 杂货、时尚、电子、美容和家居 类别，以及 外卖 （旋转风格的餐厅）。暴露 40+MCP工具 任何兼容MCP的AI客户端（Claude、GPT、Gemini等）都可以发现和调用。

______________________________________________________________________

目录

1. 需求
2. 建筑
3. 代码结构
4. 本地运行时--快速入门
5. Web UI——数据浏览器
6. 本地端点
7. 28种电子商务MCP工具
8. 餐厅和Swiggy刮刀工具
9. 种子数据管道
10. LLM产品数据生成
11. 测试用例
12. 在本地运行测试
13. 生产部署
14. 连接MCP客户端
15. 状态 & 全部

______________________________________________________________________

需求

功能需求

• 暴露 28个MCP工具 通过HTTP/SSE实现AI聊天机器人集成
• 支持 5个产品类别：杂货、时尚、电子、美容、家居
• 完整的电子商务流程：搜索→ cart → 结账→ 支付→ 订单→ 装运→ 审查
• 通过电话号码+平台密码进行基于会话的身份验证
• 模拟数据生成——不需要真正的数据库种子；产品按需生成
• 支持门票和愿望清单管理

非功能性需求

• Java 21 最小
• 用于本地/dev的内存H2数据库；PostgreSQL用于生产
• 所有工具均以结构化JSON字符串进行响应
• 会话TTL:24小时
• 分页：默认10个项目，最多50个
• 异步生成产品以避免阻止搜索响应

先决条件

______________________________________________________________________

建筑

┌─────────────────────────────────────────────────────────────┐
│                        MCP Client                           │
│          (Claude Desktop / VS Code / Custom App)            │
└─────────────────────┬───────────────────────────────────────┘
                      │  HTTP/SSE  (MCP Protocol)
                      ▼
┌─────────────────────────────────────────────────────────────┐
│              Spring Boot MCP Server  :8080                  │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  MCP Tool Layer  (12 Tool Classes, 28 Tools)         │   │
│  │  ProductSearch · ProductDetail · Delivery · Auth     │   │
│  │  Cart · Address · Payment · Order · Shipment         │   │
│  │  Ticket · Review · Wishlist                          │   │
│  └──────────────────────┬───────────────────────────────┘   │
│  ┌──────────────────────▼───────────────────────────────┐   │
│  │  Service Layer  (12 Services)                        │   │
│  │  Auth · Product · Cart · Checkout · Order · Payment  │   │
│  │  Address · Delivery · Review · Ticket · Wishlist     │   │
│  │  MockDataGenerator                                   │   │
│  └──────────────────────┬───────────────────────────────┘   │
│  ┌──────────────────────▼───────────────────────────────┐   │
│  │  Repository Layer  (16 Spring Data JPA Repos)        │   │
│  └──────────────────────┬───────────────────────────────┘   │
│  ┌──────────────────────▼───────────────────────────────┐   │
│  │  Database: H2 (dev/test)  │  PostgreSQL (prod)       │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

数据流——端到端购物之旅

Login (phone) → sessionId
  → searchProducts / filterProducts
    → addToCart (sessionId)
      → checkout (cartId, sessionId)
        → selectAddress (checkoutId, addressId, sessionId)
          → initiatePayment (checkoutId, method, sessionId)
            → orderId created automatically
              → getOrderDetails / getShipments
                → submitProductReview / createTicket

关键设计决策

• 按需模拟数据 --产品是从搜索关键字+类别中确定地生成的；无需人工播种
• SSE运输 --工具通过服务器发送事件公开，以提供实时流媒体支持
• 内存中的H2 对于dev意味着零设置；模式在启动时创建，在退出时删除
• 异步生成 --当搜索没有返回结果时，将在后台异步生成8个产品

______________________________________________________________________

代码结构

src/
├── main/java/com/mock/ecom/mcpserver/
│   ├── MockEcomMcpServerApplication.java   # Entry point (@EnableAsync)
│   ├── config/
│   │   ├── AppProperties.java              # App config (session TTL, secret, pagination)
│   │   ├── AsyncConfig.java                # Thread pool (5 core, 20 max, 100 queue)
│   │   └── McpToolsConfig.java             # Registers all 12 tool classes with MCP
│   ├── entity/                             # 16 JPA entities
│   │   ├── Customer, Session, Address
│   │   ├── Product, ProductAttribute
│   │   ├── Cart, CartItem, Checkout
│   │   ├── Order, OrderItem, Payment
│   │   ├── Shipment, Review
│   │   ├── Ticket, TicketComment, WishlistItem
│   ├── repository/                         # 16 Spring Data JPA repositories
│   ├── service/                            # 12 business services
│   │   ├── AuthService.java                # Session create/validate, customer lookup
│   │   ├── ProductService.java             # Search, filter, reviews, lazy generation
│   │   ├── MockDataGeneratorService.java   # Deterministic mock data for 5 categories
│   │   ├── CartService.java                # Add to cart, recalculate totals, checkout
│   │   ├── CheckoutService.java            # Checkout lifecycle
│   │   ├── OrderService.java               # Order creation and status transitions
│   │   ├── PaymentService.java             # Payment initiation and status
│   │   ├── AddressService.java             # Address CRUD
│   │   ├── DeliveryService.java            # Delivery estimate by pincode
│   │   ├── ReviewService.java              # Product and shipment reviews
│   │   ├── TicketService.java              # Support tickets and comments
│   │   └── WishlistService.java            # Wishlist add/view
│   └── tools/                              # 12 MCP tool classes
│       ├── ProductSearchTools.java         # Tools 1-4
│       ├── ProductDetailTools.java         # Tools 5-6
│       ├── DeliveryTools.java              # Tool 7
│       ├── AuthTools.java                  # Tool 8
│       ├── CartTools.java                  # Tools 9-10
│       ├── AddressTools.java               # Tools 11-12
│       ├── PaymentTools.java               # Tools 13-14
│       ├── OrderTools.java                 # Tools 15-19
│       ├── ShipmentTools.java              # Tool 20
│       ├── TicketTools.java                # Tools 21-24
│       ├── ReviewTools.java                # Tools 25-26
│       ├── WishlistTools.java              # Tools 27-28
│       └── ToolResponseHelper.java         # JSON serialization utility
└── main/resources/
    ├── application.yml                     # Dev profile (H2, port 8080)
    ├── application-test.yml                # Test profile (H2, separate DB)
    └── application-prod.yml                # Prod profile (PostgreSQL, env vars)

src/test/java/com/mock/ecom/mcpserver/
├── MockEcomMcpServerApplicationTests.java
└── integration/
    ├── EndToEndShoppingJourneyTest.java    # Full 28-tool flow
    ├── AuthAndCartFlowTest.java            # Tools 8-14
    ├── ProductToolsIntegrationTest.java    # Tools 1-7
    ├── OrderManagementTest.java            # Tools 15-20
    ├── TicketAndReviewTest.java            # Tools 21-26
    ├── WishlistTest.java                   # Tools 27-28
    └── MockDataGeneratorTest.java          # Data generation logic

实体关系

Customer ──── Product
Customer ──── Product
Cart ──── Checkout ──── Order ──── Product
Checkout ──, quantity=1, sessionId=)

______________________________________________________________________

餐厅和Swiggy刮刀工具

该服务器包括一个完整的Swiggy数据抓取器和餐厅查询层，增加了 12个新的MCP工具 用于食品配送用例。

它在创业中是如何运作的

餐厅查询工具（6个工具）

刮板控制工具（6个工具）

从Swiggy抓取实时数据

要求： 网络访问 www.swiggy.com.服务器必须在能够访问Swiggy的API的计算机上运行。

第1步-取消所有餐厅：

{ "name": "startRestaurantScraping", "arguments": {} }

监视器 getScraperStatus每个城市大约需要30-120秒（速率限制为1.5秒）。所有50个城市都需要1~2个小时。

步骤2–废弃菜单：

{ "name": "startMenuScraping", "arguments": {} }

数千家餐厅可能需要几个小时。两个刮刀都是 渐进的 –可以随时中断和恢复。

步骤3–检查进度：

{ "name": "getScraperStatus", "arguments": {} }

退货 totalCities, scrapedCities, totalRestaurants, restaurantsWithMenu以及奔跑的旗帜。

______________________________________________________________________

种子数据管道

种子数据管道允许您将抓取的数据提交到git，这样每次新部署都会满载启动，不需要重新抓取。

导出抓取的数据

刮完之后，打电话给 exportSeedData MCP工具：

{ "name": "exportSeedData", "arguments": {} }

这写道 ./seed-export/seed-data.json --一个包含所有餐厅及其完整菜单的便携式JSON文件。

提交种子文件

cp seed-export/seed-data.json src/main/resources/db/seed/seed-data.json
git add src/main/resources/db/seed/seed-data.json
git commit -m "chore: add scraped Swiggy restaurant seed data (N restaurants)"
git push

重建和部署

mvn clean package -DskipTests
java -jar target/mcp-server-1.0.0-SNAPSHOT.jar

在首次使用新数据库启动时， SeedDataLoader 检测种子文件并自动导入所有数据。 SampleRestaurantDataSeeder 当数据已经存在时跳过。

重新抓取后的增量更新

当你重新运行刮刀来挑选新餐厅时：

• 城市： scrapeRestaurantsForCity Swiggy ID的更新——更新现有餐厅，插入新餐厅
• 菜单： startMenuScraping 跳过以下餐厅 menuScraped = true；使用 scrapeRestaurantMenu 强制刷新一家餐厅
• 重新抓取后，致电 exportSeedData 再次复制新文件，并提交

数据持久性（开发）

开发H2数据库持续存在 ./data/mockecomdb.* （基于文件的H2）。数据在服务器重启后仍然有效。这 ./data/ 目录是 .gitignored——仅出口 seed-data.json 在 src/main/resources/db/seed/ 承诺。

______________________________________________________________________

LLM产品数据生成

服务器可以使用Anthropic LLM（Claude）来生成 按需提供真实的印度市场产品数据.当产品搜索或筛选器未返回现有结果，并且配置了Anthropic API密钥时，服务器调用 claude-haiku-4-5 生成产品，将其保存到数据库，并将其返回给调用者。

运作原理

MCP call: searchProducts / filterProducts
    │
    ▼
productRepository.searchByQuery(...)  →  results found?
    │ no results                              │ yes
    ▼                                         ▼
LlmProductGeneratorService.isAvailable()?  return existing data
    │ yes (API key set)        │ no
    ▼                          ▼
callAnthropicAPI(...)     MockDataGeneratorService (deterministic fallback)
    │
    ▼
Parse JSON → save Products + ProductAttributes to DB
    │
    ▼
Return newly generated products to MCP caller

生成的产品是 持久化到数据库 立即，所以：

• 对同一查询的后续调用返回已保存的产品（没有额外的API调用）
• 数据可以导出为种子JSON并提交，以便新的部署开始完全加载

设置--启用LLM生成

选项A：环境变量（推荐）

export ANTHROPIC_API_KEY=sk-ant-your-key-here
mvn spring-boot:run

选项B:application.yml

app:
  llm:
    api-key: sk-ant-your-key-here
    model: claude-haiku-4-5-20251001   # default, any Claude model works
    enabled: true

注： API密钥故意不提交给git。始终通过环境变量或局部变量传递它 .env 文件已从版本控制中排除。

当 ANTHROPIC_API_KEY 未设置， LlmProductGeneratorService.isAvailable() 回报 false 服务器回退到 MockDataGeneratorService --从哈希种子生成的确定性模拟产品。不会抛出任何错误。

种子产品-Seed.json从LLM输出

通过MCP调用（或直接通过REST API）生成产品后，将其导出到种子文件：

{ "name": "exportProductSeedData", "arguments": {} }

这写道 ./seed-export/products-seed.json。将其复制到resources目录并提交：

cp seed-export/products-seed.json src/main/resources/db/seed/products-seed.json
git add src/main/resources/db/seed/products-seed.json
git commit -m "chore: add LLM-generated product seed data"
git push

在下一次新的部署中， ProductSeedLoader （@Order 3）在调用LLM之前自动加载文件。

加载产品种子的启动订单

预加载种子数据

承诺 src/main/resources/db/seed/products-seed.json 包含 70产品 在所有类别中：

所有产品都使用现实的印度卢比定价，并提供有意义的折扣，并包括3-5个特定类别的属性（例如，电子产品的保修+RAM+处理器；杂货的保质期+FSSAI认证）。

环境变量摘要

______________________________________________________________________

测试用例

测试套件（7个文件，83个测试）

端到端流程（端到端购物旅程测试）

1.  serverToServerLogin        → sessionId
2.  searchProducts             → productId
3.  filterProducts             → filtered list
4.  getFilters                 → filter facets
5.  getSortOptions             → sort options
6.  getProductDetails          → product info
7.  getProductReviews          → reviews
8.  getDeliveryTime            → estimate
9.  addToWishlist              → wishlistItem
10. getWishlist                → wishlist
11. addToCart (x2 products)    → cartId
12. checkout                   → checkoutId
13. getAddresses               → addressId
14. selectAddress              → confirmed
15. initiatePayment (UPI)      → paymentId, orderId
16. getPaymentStatus           → SUCCESS
17. getOrderDetails            → order + items
18. getOrders                  → history
19. getShipments               → shipmentId
20. sendDeliveryOtp            → OTP sent
21. createTicket               → ticketId
22. getTickets                 → list
23. getTicketDetails           → ticket + comments
24. addTicketComment           → comment added
25. submitProductReview        → review saved
26. submitShipmentReview       → review saved

______________________________________________________________________

在本地运行测试

# Run all tests (uses test profile with separate H2 DB)
mvn test

# Run a specific test class
mvn test -Dtest=EndToEndShoppingJourneyTest

# Run a specific test method
mvn test -Dtest=ProductToolsIntegrationTest#testSearchProducts

# Run with verbose output
mvn test -Dsurefire.useFile=false

# Run tests + generate coverage report (if jacoco configured)
mvn verify

# Skip tests during build
mvn clean package -DskipTests

测试配置文件

测试使用 application-test.yml:

• 在内存DB中分离H2： jdbc:h2:mem:testdb
• 为每次测试运行创建新的架构(ddl-auto: create-drop)
• NON_KEYWORDS=VALUE 添加以避免H2 SQL关键字冲突
• 禁用SQL日志记录以获得更清晰的输出

CI（GitHub操作）

通过以下方式在每次推送/PR上自动运行测试 .github/workflows/build.yml:

• Java 21（temurin），Maven缓存
• mvn clean verify -Dspring.profiles.active=test
• JAR工件上传成功

______________________________________________________________________

生产部署

Docker Compose（推荐）

# Build the JAR
mvn clean package -DskipTests

# Start app + PostgreSQL
docker-compose up --build -d

# View logs
docker-compose logs -f app

# Stop
docker-compose down

服务已启动：

• 应用 --端口上的Spring Boot 8080，个人资料 prod
• Postgres --PostgreSQL 16端口 5432，DB mockecomdb

PostgreSQL数据保存在Docker卷中 pgdata.

自定义环境变量

docker-compose up \
  -e DB_PASSWORD=supersecret \
  -e SERVER_PORT=9000 \
  --build

或者创建一个 .env 旁边的文件 docker-compose.yml:

DB_URL=jdbc:postgresql://myhost:5432/mydb
DB_USERNAME=myuser
DB_PASSWORD=mysecret
SPRING_PROFILES_ACTIVE=prod

手动JAR部署

# Build
mvn clean package -DskipTests

# Run with prod profile
java -jar target/mcp-server-1.0.0-SNAPSHOT.jar \
  --spring.profiles.active=prod \
  --server.port=8080 \
  --DB_URL=jdbc:postgresql://localhost:5432/mockecomdb \
  --DB_USERNAME=postgres \
  --DB_PASSWORD=postgres

Kubernetes/云

服务器是无状态的（数据库中的所有状态），因此可以水平扩展。关键考虑因素：

• 集 spring.jpa.hibernate.ddl-auto=update （已设置 application-prod.yml)
• 使用托管PostgreSQL服务（RDS、Cloud SQL等）
• 将环境变量挂载为Kubernetes的秘密
• 活体探针： GET /actuator/health
• 准备就绪探针： GET /actuator/health

______________________________________________________________________

连接MCP客户端

克劳德桌面

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "mock-ecom": {
      "url": "http://localhost:8080/sse",
      "type": "sse"
    }
  }
}

重新启动克劳德桌面。您将看到28个可用工具。

克劳德代码（CLI）

# Add MCP server
claude mcp add mock-ecom --transport sse http://localhost:8080/sse

# List configured servers
claude mcp list

# Remove
claude mcp remove mock-ecom

或编辑 ~/.claude/settings.json:

{
  "mcpServers": {
    "mock-ecom": {
      "type": "sse",
      "url": "http://localhost:8080/sse"
    }
  }
}

VS代码（复制/继续/临床）

添加到您的VS代码 settings.json:

{
  "mcp": {
    "servers": {
      "mock-ecom": {
        "type": "sse",
        "url": "http://localhost:8080/sse"
      }
    }
  }
}

自定义MCP客户端（Python）

from mcp import ClientSession
from mcp.client.sse import sse_client

async with sse_client("http://localhost:8080/sse") as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        tools = await session.list_tools()
        result = await session.call_tool("searchProducts", {
            "query": "laptop",
            "page": 0,
            "pageSize": 10
        })

自定义MCP客户端（JavaScript/TypeScript）

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";

const transport = new SSEClientTransport(
  new URL("http://localhost:8080/sse")
);
const client = new Client({ name: "my-client", version: "1.0.0" }, {});
await client.connect(transport);

const result = await client.callTool("serverToServerLogin", {
  phone: "9999999999",
  platform: "WEB",
  secret: "mock-platform-secret-key"
});

正在验证连接

# Test SSE endpoint is alive
curl -N http://localhost:8080/sse

# Health check
curl http://localhost:8080/actuator/health

______________________________________________________________________

状态 & 全部

当前状态：✅ 工作

TODO/未来增强功能

已知限制

• 无法通过MCP工具创建地址（可以使用自动生成的模拟地址）
• 支付处理完全模拟（UPI/CARD/NETBANKING/WALLET总是成功，COD总是成功）
• 生成交付OTP，但实际上并没有发送到任何地方
• 产品图片来源于 picsum.photos （外部依赖性）
• H2数据 持续 在开发模式下跨重启（基于文件的数据库 ./data/).删除 ./data/ 重置。
• Live Swiggy抓取需要无限制的互联网访问 www.swiggy.com；沙盒/受限环境必须使用提交的种子文件

______________________________________________________________________

文档

• 需求
• 建筑
• 实施指南
• SDLC和Sprint计划
• 任务列表（TODO）