Shopping MCP Server

Reactive shopping backend exposed as Model Context Protocol (MCP) tools over Spring WebFlux + SSE.

This project is designed for AI agents (and any MCP-compatible client) to perform end-to-end shopping actions such as product discovery, cart management, wishlist operations, and order lifecycle handling.

Tech Stack

• Java 21
• Spring Boot 3.4.x
• Spring WebFlux (reactive runtime)
• Spring AI MCP Server (WebFlux starter)
• Spring Data R2DBC
• H2 (file-persisted)
• Lombok

Core Capabilities

• Session-based shopping identity (no login/auth)
• Product search, category browse, and stock checks
• Cart add/update/remove/show flows
• Wishlist add/remove/show/move-to-cart flows
• Order placement with transactional stock decrement and cart clear
• Order history/details and cancellation with stock restoration
• Structured error payloads for tool consumers
• Startup schema initialization + seed catalog insertion

Architecture

The code follows a clear layered design:

• Tools layer (src/main/java/com/example/shopping/tools) : MCP-exposed methods (@Tool) and tool-level error mapping.
• Service layer (src/main/java/com/example/shopping/service) : Business rules, validations, and transactional workflows.
• Repository layer (src/main/java/com/example/shopping/repository) : Reactive DB access using ReactiveCrudRepository + custom SQL queries.
• Domain layer (src/main/java/com/example/shopping/domain) : R2DBC-mapped entities.
• DTO layer (src/main/java/com/example/shopping/dto) : Tool response contracts.

Reactive Design

• Services and tools are built on Mono/Flux.
• No blocking calls inside business logic.
• Transactions are applied on reactive flows (@Transactional) for critical operations (e.g., order placement/cancellation).

Project Layout

src/main/java/com/example/shopping
├── ShoppingMcpApplication.java
├── config/
│   ├── McpServerConfig.java
│   └── R2dbcConfig.java
├── domain/
├── dto/
├── init/
│   └── DatabaseInitializer.java
├── repository/
├── service/
├── tools/
└── util/

src/main/resources
├── application.yml
└── schema.sql

Configuration

Main runtime config is in src/main/resources/application.yml.

Current defaults:

• Server port: 8085
• R2DBC URL: r2dbc:h2:file:///./data/shopping-db;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE
• MCP transport: sse
• App logging:
  • com.example.shopping: DEBUG
  • com.example.shopping.tools: INFO

Persistence

H2 is persisted to the project-local data/ directory.

Expected DB file:

• data/shopping-db.mv.db

Database Schema

Defined in src/main/resources/schema.sql.

Tables:

• products
• sessions
• cart_items
• wishlist_items
• orders
• order_items

Notable schema decisions:

• cart_items and wishlist_items enforce one row per (session_id, product_id).
• order_items stores denormalized product_name and unit_price snapshots.
• Order status is text-based (PLACED, CANCELLED, etc.).

Startup Behavior

On startup, DatabaseInitializer performs:

1. Ensures data/ directory exists.
2. Executes all schema.sql statements.
3. Checks products table count.
4. Inserts seed data if empty.

Seed catalog:

• 20 products across 4 categories:
  • Electronics
  • Clothing
  • Books
  • Home & Kitchen

If products already exist, seeding is skipped.

MCP Tools

The following 18 tools are exposed via classes in tools/:

Session

1. createSession

Product

2. productSearchByName
3. getProductDetailsById
4. checkProductStock
5. getProductsByCategory
6. listCategories

Cart

7. addProductToCart
8. updateCartItemQuantity
9. removeProductFromCart
10. showCartDetails

Wishlist

11. addProductToWishlist
12. showWishlistDetails
13. removeFromWishlist
14. `moveWishlistItemTo

... View full README on GitHub