模拟电商MCP服务器

┌─────────────────────────────────────────────────────────────┐
│                        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

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 ──< Session
Customer ──< Address
Customer ──< Cart ──< CartItem >── Product
Customer ──< WishlistItem >── Product
Cart ──── Checkout ──── Order ──< OrderItem >── Product
Checkout ──< Payment
Order ──< Shipment ──< OrderItem
Order ──< Ticket ──< TicketComment
Shipment ──< Review (DELIVERY type)
Product ──< Review (PRODUCT type)
Product ──< ProductAttribute

chmod +x run-local.sh
./run-local.sh

# 1. Build
mvn clean package -DskipTests

# 2. Run (H2 in-memory, dev profile)
mvn spring-boot:run

# Or run the JAR directly
java -jar target/mcp-server-1.0.0-SNAPSHOT.jar

java -jar target/mcp-server-1.0.0-SNAPSHOT.jar --server.port=9090

# Build and start all services
mvn clean package -DskipTests
docker-compose up --build

# Stop
docker-compose down

# Stop and remove data volume
docker-compose down -v

http://localhost:8080

# Install dependencies (first time only)
cd ui
npm install

# Build — outputs to src/main/resources/static/
npm run build

# Then rebuild the JAR so Spring Boot picks up the new assets
cd ..
mvn clean package -DskipTests
java -jar target/mcp-server-1.0.0-SNAPSHOT.jar

# Terminal 1 — start the backend
java -jar target/mcp-server-1.0.0-SNAPSHOT.jar

# Terminal 2 — start the Vite dev server
cd ui
npm run dev

cd ui && npm run build
cd ..
git add src/main/resources/static/
git commit -m "chore: update UI build"

# All cities with restaurants
curl http://localhost:8080/api/v1/cities

# Restaurants in Bangalore
curl "http://localhost:8080/api/v1/restaurants?cityName=Bangalore"

# Veg restaurants in Mumbai
curl "http://localhost:8080/api/v1/restaurants?cityName=Mumbai&isPureVeg=true"

# Cuisines available in Hyderabad
curl "http://localhost:8080/api/v1/cuisines?cityName=Hyderabad"

# Full menu for Paradise Biryani
curl "http://localhost:8080/api/v1/restaurants/400001/menu"

# Search for "biryani" across all restaurants
curl "http://localhost:8080/api/v1/menu-items?q=biryani"

# Search for "biryani" in Bangalore only
curl "http://localhost:8080/api/v1/menu-items?q=biryani&cityName=Bangalore"

# Electronics products
curl "http://localhost:8080/api/v1/products?category=Electronics&size=5"

# Laptop products
curl "http://localhost:8080/api/v1/products?q=laptop"

# Build with Swagger
mvn clean package -Pswagger -DskipTests

# Run
java -jar target/mcp-server-1.0.0-SNAPSHOT.jar

# Open in browser
open http://localhost:8080/swagger-ui.html

URL:      http://localhost:8080/h2-console
JDBC URL: jdbc:h2:file:./data/mockecomdb
Username: sa
Password: (leave blank)

curl http://localhost:8080/actuator/health
# {"status":"UP","components":{"db":{"status":"UP"},"diskSpace":{"status":"UP"}}}

# Step 1 — Get a session
sessionId = serverToServerLogin(
  phone    = "9999999999",
  platform = "WEB",
  secret   = "mock-platform-secret-key"
)

# Step 2 — Use sessionId in all authenticated tools
addToCart(productId=<id>, quantity=1, sessionId=<sessionId>)

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

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

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

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

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

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

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

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

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

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

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

# 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

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

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

# 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

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

# 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

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

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

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
        })

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